ceciliaorta/gcal-sync

Chart ApplicationAppointmentsPatient Scheduling

You can also View the extension on GitHub

gcal-sync — two-way Google Calendar sync for Canvas

Two-way sync between Canvas appointments and providers' Google Workspace calendars. Canvas appointments and provider admin blocks (lunch/PTO) are pushed into providers' Google calendars in near-real-time, and provider-created Google events are imported back into Canvas as admin holds that block availability. Canvas remains the system of record.

Problem it solves

Providers often keep personal availability — PTO, lunch, external meetings — in Google Calendar, while Canvas owns clinical scheduling. Without sync the two drift: Canvas shows a provider as available when they are actually blocked in Google, which leads to double-booking. gcal-sync keeps both directions aligned automatically so a provider's availability in Canvas reflects their real calendar.

Who it's for

Practices on Google Workspace whose providers manage availability in Google Calendar and want it reflected in Canvas scheduling (and vice versa) without manual double-entry.

What it does

Provider-created Google events are imported as admin holds (ScheduleEvent). Private/confidential events can be imported with their title masked to "Busy" — no event details from Google are written into Canvas beyond time and a generic label. Canvas-wins by default: edits made to a Canvas appointment from the Google side are reverted unless explicitly allow-listed.

Installation

canvas install gcal_sync

Then complete the one-time setup below.

Configuration (secrets)

One-time setup

Google Workspace admin setup

Your Google Workspace Administrator will need to:

1. Create a service account in Google Cloud Console
   1. Go to console.cloud.google.com and
      create a new project
      (e.g. "Canvas Calendar Sync").

• Enable the API: APIs & Services → Library → search
  " Google Calendar API"
  → click Enable. - Create the identity: IAM & Admin → Service Accounts →
  Create service account. 1. Name it something clear (e.g. canvas-calendar-sync). 2. Generate associated key (should be a JSON file). This becomes the
  GOOGLE_SERVICE_ACCOUNT_JSON plugin secret. 3. Note the associated Unique ID — this is the "Client ID" used in the next step.

2. Authorize it for your Workspace (Google Admin Console)
   1. Go to admin.google.com (must be signed in as a Super Admin).
   2. Navigate to Security → Access and data control → API controls → Domain-wide delegation → Manage Domain Wide Delegation.
   3. Add new and enter:
      • Client ID: the Unique ID from step 1 above.
      • OAuth scopes:https://www.googleapis.com/auth/calendar

Plugin secrets

Configure these secrets in the plugin settings on your Canvas instance:

Map providers to calendars

Open the "Google Calendar Sync" app from the left sidebar. Three options:

• Auto-map — maps every active staff member with a Provider role to their Canvas staff email
  (google_admin.py:auto_map). Best when provider staff emails match their Workspace calendar emails.
• Bulk CSV import — paste a CSV with emails in the first column
  (google_admin.py:bulk_import). The plugin matches each email to a Canvas staff profile. Use this when providers use a different calendar email than their Canvas staff email.
• Individual mapping — set each provider's calendar email one at a time.

When a mapping is saved as active, the plugin opens a Google events.watch channel for that calendar (google_admin.py:_open_channel_best_effort), enabling near-real-time inbound sync.

The admin UI shows sync health per provider: whether a watch channel is active, when the last outbound sync ran, and how many events are tracked. The nightly ReconciliationCron and ChannelRenewalCron handle catch-up and keep watch channels alive automatically.

Multi-domain note

The service account and delegation are per Google Workspace domain. If different partners or locations use separate Workspace domains, each domain's admin must complete Steps 1–2 independently with their own GCP project and JSON key file.

How auth works under the hood

The plugin holds one service-account key and, for each provider, mints a short-lived RS256 JWT that impersonates that provider (sub = provider@example.com) and exchanges it for an access token via the JWT-bearer grant (auth.py:GoogleAuth.get_access_token). Tokens are cached per provider for just under their 1-hour lifetime so bursts of appointment events don't mint a token per event. No per-user refresh tokens are stored or rotated.

What syncs and what doesn't

Outbound (Canvas → Google):

• Appointment create/update/cancel/reschedule (via AppointmentSyncHandler)
• Admin schedule blocks like lunch/PTO (via BlockSweepCron, every 15 min)
• Does NOT push Canvas schedule_events (availability/bookable windows) — those are Canvas-only

Inbound (Google → Canvas):

• Provider-created Google events become admin holds on the Canvas schedule
• Near real-time via webhook push notifications + daily reconciliation
• Private events imported with title masked to "Busy" (configurable via INGEST_PRIVATE_EVENTS)
• Canvas-wins by default: edits to a Canvas appointment from Google are reverted

Troubleshooting

If the sync returns 401 errors after deployment, delegation was not configured (or was configured on the wrong domain). The token exchange in auth.py:_exchange() surfaces Google's error body in the plugin logs to make this diagnosable.

Custom data

Uses the gcal_sync namespace (custom_data in the manifest) for its mapping and sync-state tables.

Screenshots

The admin application (app drawer → Google Calendar Admin) provides the staff↔calendar mapping table, a sync-health view, and per-provider reconcile / re-import / purge controls.

Running tests

uv run pytest tests/

Learn more about Canvas

Contact Sales