Setting up calendars

Verifying the connection

Before importing, it's worth confirming the service account is actually working, independent of any Drupal-side configuration:

drush gcal:secrets

Shows the configured Google API service client (id, account email, scopes) and whether it successfully authenticates. If this fails, the problem is in the credentials/service-client setup, not in the import step.

drush gcal:listCalendars

Lists every calendar the service account can see on Google's side directly, via the API — bypassing the Drupal import UI entirely. Calendars not yet imported show as "Remote ONLY". If a calendar you shared with the service account (Setup Wizard, page 5) doesn't appear here, the problem is on Google's side (sharing/permissions), not in Drupal — recheck the share settings before troubleshooting further in Drupal.

Only once a calendar appears in this list should you expect it to show up on the Import Calendars page.

Drupal Calendar Import

Once a Google API service client is configured and selected on the Google Calendar settings page (see Installation), you can bring calendars into Drupal:

1. Go to Configuration > Google Calendar > Import Calendars (admin/config/google_calendar/calendars/import). This lists the calendars visible to the configured service account on Google's side.
2. Select the calendars you want to mirror into Drupal and import them. Each becomes a Google Calendar entity locally.
3. Events sync in via cron, or immediately with drush gcal:sync, or from the calendar's own Synchronize entity action.
4. View and manage imported calendars at Content > Google Calendars (admin/content/google_calendar), and their events at Content > Google Calendar Events (admin/content/google_calendar_event).

Only calendars the configured service account has been shared on (see the Setup Wizard, page 5) will appear in the import list.

Regular Updates

The module relies on the calendar being explicitly pulled from Google and uses a 'cron' hook to trigger the regular update needed. Each cron run for a running site is likely to take from a second to perhaps 10 seconds, though more commonly shorter than longer, but it does depend on whether you have many calendars set up, many events or a few, and a well configured database. When initially populating a calendar the sync does take noticeably longer, though.

If your normal cron is set to run relatively infrequently -- say every 30 minutes -- and you would prefer not to change that, then one option is to run drush gcal:update command as well (aliases: gcal:cron, gcal-cron). This is safe to run in parallel: there is a check to make sure it doesn't overlap with a 'real' cron.

The recommendation is running either 'normal' cron or 'drush gcal:update' every 5 minutes.

Calendar Event Entities

Each calendar event entity is imported once and the module does try hard to retain that record for as long as it is valid within the context of the Google API. This is often shorter than you would expect, though, as tools manipulating events do cause Google to cancel and recreate events rather than modify them.

The Google calendar API does force the use of a "horizon" of events, as it is very common to have infinitely repeating events. Importing "all" events into Drupal would therefore import an infinite number of entities. For practical reasons it is best to keep the horizon shorter: my site runs with -1 day and + 13 months.

Longer times work but obviously the number of entities being churned over grows, and so too does the load on your drupal database. That load can become onerous given a long enough horizon.

For reference: the algorithm that is run from 'cron' is, approximately:

Ask Google for the set of events in the current time period (as defined by the horizon).
For each event check whether we have an event with that google-assigned event id.
   If we do, check whether that event's Drupal data needs updating, (and if so do it).
   If we don't, import the event as a new one.
Finally, delete all events that we have in Drupal but the Google API result did not mention.

I have not yet come up with a better (lower cost, faster) way of doing this which is also correct and keeps to Drupal's standard database API. Some useful optimisation could be done if direct SQL queries were allowed, but that would likely break other things.

Google Calendar Event fields

user_id — Authored by
  The user ID of author of the Google Calendar Event entity.

name — Name
  The name of the event. This field is read-only, and should be changed in Google Calendar.

location — Location
  Event Location. This field is read-only, and should be changed in Google Calendar.

event_id — Event ID
  The Google created unique ID for this event. Unique even for recurring instances. Read-only.

ical_id — iCal ID
  The Google created iCal ID for this event. Not unique for recurring instances. Read-only.

google_link — Google Link
  External link to the event in its Google Calendar. Read-only.

calendar — Google Calendar
  The calendar this event is part of.

description — Description
  Long form description of the event.

start_date — Start Date
  Event Start Date. This field is read-only, and should be changed in Google Calendar.

end_date — End Date
  Event End Date. This field is read-only, and should be changed in Google Calendar.

end_unspecified — End Unspecified
  A boolean indicating that the end date/time was not specified. Read-only.

recurrence_id — Recurrence ID
  Recurrence event id. Read-only.

recurrence — Recurrence
  Recurrence info. Read-only.

etag — Tag
  An http tag value. Read-only.

guests_invite_others — Can guests invite others
  A boolean indicating that someone other than the owner of the event can invite people. Read-only.

guests_modify — Can guests edit
  A boolean indicating that someone other than the owner of the event change it. Read-only.

guests_see_invitees — Can guests view guest list
  A boolean indicating that guests can see who else is invited. Read-only.

locked — Locked status
  A boolean indicating that the Google Calendar Event is locked. Read-only.

transparency — Transparency
  A boolean indicating whether the event blocks time in the calendar. Allowed values: Opaque, Transparent. Read-only.

visibility — Event visibility
  Whether this event is public or private. Allowed values: Default, Public, Private, Confidential. Read-only.

state — State
  Allowed values: Tentative, Confirmed, Cancelled. Read-only.

status — Publishing status
  A boolean indicating whether the Google Calendar Event is published.

created — Created
  The time that the entity was created. Read-only.

creator — Event creator
  Name of event creator. Read-only.

creator_email — Event creator email
  Email of event creator. Read-only.

organizer — Event organizer
  Name of event organizer. Read-only.

organizer_email — Event organizer email
  Email of event organizer. Read-only.

changed — Changed
  The time that the entity was last edited.

updated — Updated
  The time that the entity was last edited.