Collection of Google Calendar related utility functions for Google Apps Script.

gCalUtils.js

/** @module GCalUtils */


/**
 * Gets all events that occur within a given time range,
 * and that include the specified guest email in the
 * guest list.
 *
 * @param {Calendar} calen Calendar to search
 * @param {Date} start the start of the time range
 * @param {Date} end the end of the time range, non-inclusive
 * @param {String} guestEmail Guest email address to search for
 *
 * @return {CalendarEvent[]} the matching events
 *
 * @see {@link https://developers.google.com/apps-script/reference/calendar/calendar-app?hl=en#getEvents(Date,Date)|CalendarApp.getEvents(Date,Date)}
 * @see {@link https://developers.google.com/apps-script/reference/calendar/calendar-event|Class CalendarEvent}
 */
function getEventsWithGuest(calen,start,end,guestEmail) {
  var events = calen.getEvents(start, end);
  var i = events.length;
  while (i--) {
    if (!events[i].getGuestByEmail(guestEmail)) {
      events.splice(i, 1);
    }
  }
  return events;
}

/**
 * Create or update a block reservation for a conference room,
 * starting 'blockFrom' days from today.
 */
function updateBlockReservation() {
  // Get Calendar
  var calName = 'Huddle Room';
  var cal = CalendarApp.getCalendarsByName(calName)[0];

  var title = 'Reserved';  // Reserved events will have this title
  var blockFrom = 7;       // Days from now until room is blocked
  var today = new Date();  // Today's date, ...
  today.setHours(0,0,0,0); // at midnight.
  var startDate            // Daily block reservation starts here
        = new Date(today.getTime() + (blockFrom * 24 * 60 * 60 * 1000));
  var endTime = new Date(startDate.getTime() + (24 * 60 * 60 * 1000) - 1);
  var recurrence = CalendarApp.newRecurrence().addDailyRule();
  
  // Look for existing block reservation
  var series = cal.getEvents(startDate, endTime, {search:title});
  
  if (series.length == 0) {
    // No block reservation found - create one.
    var reserved = cal.createAllDayEventSeries(title, startDate, recurrence);
  }
  else {
    // Block reservation exists - update the recurrence to start later.
    reserved = series[0].getEventSeries();
    reserved.setRecurrence(recurrence, startDate);
  }
  
  debugger;  // Pause if running in debugger
}

/**
 * Get the calendar ID for a named calendar.
 * Throws an error if the calendar name is not accessible by the user.
 *
 * @param {string} calName   Calendar Name
 *
 * @returns {string}         Calendar ID
 */
function getCalId( calName ) {
  var cal = CalendarApp.getCalendarsByName(calName);
  if (cal) {
    return cal[0].getId();
  }
  else {
    throw new Error( "Calendar not found: " + calName );
  }
}

/**
 * Set up calendar sharing for a single user. Refer to 
 * https://developers.google.com/google-apps/calendar/v3/reference/acl/insert.
 * Uses Advanced Calendar Service, which must be enabled via Developer's Dashboard.
 *
 * @param {string} calId   Calendar ID
 * @param {string} user    Email address to share with
 * @param {string} role    Optional permissions, default = "reader":
 *                         "none, "freeBusyReader", "reader", "writer", "owner"
 *
 * @returns {aclResource}  See https://developers.google.com/google-apps/calendar/v3/reference/acl#resource
 */
function shareCalendar( calId, user, role ) {
  role = role || "reader";
    
  var acl = null;
  
  // Check whether there is already a rule for this user
  try {
    var acl = Calendar.Acl.get(calId, "user:"+user);
  }
  catch (e) {
    // no existing acl record for this user - as expected. Carry on.
  }
  debugger;
  
  if (!acl) {
    // No existing rule - insert one.
    acl = {
      "scope": {
        "type": "user",
        "value": user
      },
      "role": role
    };
    var newRule = Calendar.Acl.insert(acl, calId);
  }
  else {
    // There was a rule for this user - update it.
    acl.role = role;
    newRule = Calendar.Acl.update(acl, calId, acl.id)
  }
  
  return newRule;
}

GCalUtils.md

Google Calendar Utilities

getEventsWithGuest

Gets all events that occur within a given time range, and that include the specified guest email in the guest list.

###Parameters:###

Name	Type	Description
calen	Calendar	Calendar to search
start	Date	the start of the time range
end	Date	the end of the time range, non-inclusive
guestEmail	String	Guest email address to search for

See:

• CalendarApp.getEvents(Date,Date)
• Class CalendarEvent

###Returns:### the matching events

Type

CalendarEvent[]

updateBlockReservation

Create or update a block reservation for a conference room, starting 'blockFrom' days from today.

getCalId

Get the calendar ID for a named calendar. Throws an error if the calendar name is not accessible by the user.

###Parameters:###

Name	Type	Description
calName	string	Calendar Name

###Returns:### the Calendar ID

Type

string

shareCalendar

Set up calendar sharing for a single user. Refer to https://developers.google.com/google-apps/calendar/v3/reference/acl/insert. Uses Advanced Calendar Service, which must be enabled via Developer's Dashboard.

###Parameters:###

Name	Type	Description
calId	string	Calendar ID
user	string	Email address to share with
role	Date	Optional permissions, default = "reader": * "none, "freeBusyReader", "reader", "writer", "owner"

###Returns:### See https://developers.google.com/google-apps/calendar/v3/reference/acl#resource.

Type

aclResource