Skip to main content

​
Overview

Use the Google Calendar integration after the shared GCP setup to ingest Google Workspace calendar data for the domain you want Asymptote to track. The current Google Calendar integration enumerates Workspace users through the Admin SDK Directory API, runs an initial calendar backfill, receives ongoing Google Calendar push notifications through a public webhook and Pub/Sub ingest pipeline, normalizes calendar events, and renews calendar watches on a schedule.

​
Before you start

  • Run the shared GCP setup first with ./cloud-providers/gcp/scripts/init.sh.
  • Install Terraform >= 1.9, gcloud, jq, openssl, and curl.
  • Make sure you have a Google Workspace super admin who can grant domain-wide delegation in the Google Workspace Admin Console.
  • Make sure the Workspace domain and admin subject email you plan to use belong to the Google Workspace tenant you want to ingest.
  • If you have more than one generated GCP install under generated/gcp/, decide which install-state.json you want to use and pass it with --install-state PATH.
  • Use a GCP identity that can create Google Calendar integration resources and deploy the Google Calendar workloads.
The Google Calendar installer prints a delegated service account OAuth client ID. A Google Workspace super admin must add that client ID in the Admin Console before the installer can validate calendar access and start the backfill.

​
Fill install.yaml

The Google Calendar installer reads cloud-providers/gcp/scripts/integrations/google-calendar/install.yaml by default. Google Calendar inherits the hosting mode, project ID, region, and other shared values from the base install-state.json. You do not set those again here. Fill in these fields:
  • google_calendar.workspace_domain: required. Use the Google Workspace domain whose users you want the installer to enumerate.
  • google_calendar.admin_subject_email: required. Use a Google Workspace admin email in that same tenant. The installer uses this subject for Admin SDK Directory listing and delegation validation.
  • google_calendar.watch_renewal_schedule: optional. Defaults to 0 4 * * *.
  • google_calendar.watch_renewal_time_zone: optional. Defaults to Etc/UTC.
  • google_calendar.normalization.filters.max_event_age_days: optional. Use 0 to disable the calendar event age filter.
Config shape: 
google_calendar:
  workspace_domain: "example.com"
  admin_subject_email: "admin@example.com"
  watch_renewal_schedule: ""
  watch_renewal_time_zone: ""
  normalization:
    filters:
      max_event_age_days: 0

​
Hosting modes

Google Calendar uses the same Google Workspace domain-wide delegation flow in both base modes.
  • self-hosting: the installer creates the Google Calendar-specific infrastructure in your project and then waits for a Workspace super admin to authorize the delegated service account client ID.
  • cloud-hosting: the shared GCP foundation still comes from your base mode, but the Google Calendar integration itself uses the same delegated service account grant flow as self-hosting.

​
Run the installer

1

Update `cloud-providers/gcp/scripts/integrations/google-calendar/install.yaml`

Fill in the Workspace domain, admin subject email, and any watch-renewal or normalization settings you want to override.
2

Run the script

From the repository root, run:
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-calendar
3

Approve the planned changes

Review the planned changes and approve them to continue.
4

Add the delegated OAuth client ID in Google Workspace Admin Console

After Terraform finishes, the installer prints the Google Calendar delegated service account email and its OAuth client ID, and writes the same instructions to:
generated/gcp/<project-id>/google-calendar-domain-wide-delegation.txt
Sign in to Google Workspace Admin Console as a super admin, then open:
Security > Access and data control > API controls > Manage Domain Wide Delegation
Add the printed client ID and authorize these scopes:
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/admin.directory.user.readonly
5

Resume the installer after the admin grant if needed

In an interactive shell, you can confirm the prompt after the Workspace grant is complete.If the installer already paused or you want to resume explicitly, rerun:
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-calendar --resume-after-admin-grant
If you want to use a different config file, target a specific base install, or skip confirmation prompts: 
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-calendar --config /path/to/install.yaml
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-calendar --install-state /path/to/install-state.json
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-calendar --auto-approve
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-calendar --resume-after-admin-grant --config /path/to/install.yaml --install-state /path/to/install-state.json
When the script finishes, it prints the project ID, Google Calendar events function URL, Google Calendar ingest function URL, Google Calendar normalization service URL, Google Calendar backfill job name, Google Calendar watch renewal job name, the raw events bucket, the path to the domain-wide delegation instructions file, the validation execution ID, and the live-bootstrap and initial backfill execution IDs when available.

​
Update the integration later

If Google Calendar is already connected and you want to change the Workspace domain, admin subject email, renewal cadence, or normalization filter, update the existing Google Calendar integration instead of rerunning the base GCP setup.
1

Update the Google Calendar settings

Edit cloud-providers/gcp/scripts/integrations/google-calendar/install.yaml and keep the current workspace_domain and admin_subject_email aligned with the tenant you want to ingest. Update google_calendar.watch_renewal_schedule, google_calendar.watch_renewal_time_zone, or google_calendar.normalization.filters.max_event_age_days if you want to change the refresh cadence or replay window.
2

Confirm the Workspace admin grant still matches the generated client ID

If you rerun against the same base install, the delegated client ID should stay the same. If you target a different base install or project and the installer prints a new client ID, add that new client ID in Google Workspace Admin Console before resuming.
3

Rerun only the Google Calendar installer

Run:
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-calendar
If needed, pass --install-state /path/to/install-state.json to target the existing base setup you want to update. If the installer pauses after printing the Workspace instructions, complete the grant and rerun with --resume-after-admin-grant.
After that rerun, the existing Google Calendar connection stays in place and the installer updates the stored config, validation, and runtime resources to match the YAML.

​
Troubleshooting

  • If the installer cannot find the base setup you want, pass --install-state /path/to/install-state.json.
  • If the installer says google_calendar.workspace_domain is required, fill in google_calendar.workspace_domain.
  • If the installer says google_calendar.admin_subject_email is required, fill in google_calendar.admin_subject_email with a Google Workspace admin email in the same tenant.
  • If the installer fails while validating Workspace delegation after you added the client ID, wait a few minutes for the Google Workspace Admin Console grant to propagate, then rerun with --resume-after-admin-grant.