Google Calendar write-back

Who this is for: Tenant owner, Admin (with operator google_calendar flag)
What you'll achieve: Push published SchoolRota duties into staff Google Calendars (Google Workspace)

Feature-gated

This integration is off by default: Your platform operator must enable the google_calendar flag for your school before Admin → School → Staff calendars → Google Calendar appears.

Requires

• Platform operator enables google_calendar for your tenant
• Google Workspace with domain-wide delegation for a service account
• Permission integrations.outlook.configure (shared with Outlook integration)

Overview

When a duty day is published, SchoolRota queues calendar sync jobs. For each staff member who opted in, duties appear on their primary Google Calendar. When the published board changes, SchoolRota updates or removes only events it created.

Staff on personal Gmail accounts can still use the ICS feed from My schedule when Settings → School → Calendar subscribe is on. No Workspace admin setup is required. That feed leaves SchoolRota.

Setup (Workspace admin)

1. In Google Cloud Console, create a service account and download the JSON key.
2. In Google Admin → Security → API controls → Domain-wide delegation, authorize the client ID with scope: https://www.googleapis.com/auth/calendar
3. In SchoolRota, open Admin in the sidebar, then Google Calendar under Calendar integrations. Paste:
   • Service account email
   • Private key (PEM)
   • Optional health-check staff email
   • Lookahead days (how far ahead to backfill when sync is enabled)
4. Save configuration, then Run health check - verifies delegation by impersonating that mailbox.
5. Enable sync, then opt in staff on the table below, or use Sync all staff with an email.

Sync control

Action	Purpose
Enable sync	Master switch; requires a successful health check first. Backfills published days in the lookahead window.
Disable sync	Stops new sync; existing calendar events remain until you disconnect or republish removes them.
Resync lookahead window	Re-queues sync jobs for all published days in the lookahead range.
Disconnect & cleanup	Stops sync and removes SchoolRota-owned Google events, then clears credentials.
Force disconnect	Clears credentials without deleting remote events.

While Disconnect cleanup is running, the page shows a progress message until all owned events are removed.

Sync scope

In Admin → School → Staff calendars → Google Calendar, choose What to sync:

• Duty posts only (default): playground and other duty posts
• Class cover only: lesson cover assignments only
• Teaching lessons only: imported lesson timetable events
• All published duties, class cover, and lessons: duties, lesson cover, and imported teaching lessons

Teaching lesson events are built from the teaching timetable for staff with Google sync enabled.

Recent sync jobs

The integration page lists recent jobs in plain language. Open Details to see who was added, updated, or removed. Try again on a failed job after fixing delegation or mailbox issues.

Staff opt-in

Use Sync all staff with an email to turn write-back on for everyone who already has an email, and for staff added later (directory, import, or SCIM). You can still untick a person to leave them out.

Or enable the checkbox for each teacher who should receive Google Calendar events.

Staff without an email in the directory cannot be synced. Personal Gmail accounts are not supported for write-back; those staff should use the ICS feed from My schedule.

Disconnect

• Disconnect & cleanup: stops new sync and removes SchoolRota-owned events from Google Calendars, then clears credentials.
• Force disconnect leaves remote events in place but clears stored credentials.

Behaviour

Topic	Detail
Ownership	Events carry private extended properties (schoolrotaTenantId, schoolrotaOccurrenceKey, schoolrotaPersonId)
Updates	Republish updates owned events; removes duties no longer on the live board
Conflicts	Same as Outlook: overwrite_on_publish (default)
Jobs	Durable outbox. The web process drains immediately and every 60 seconds. /api/cron/calendar-sync is the 15-minute backup (same as Outlook)

Troubleshooting

Symptom	What to try
Integration page missing	Operator enables google_calendar flag
Health check fails	Verify domain-wide delegation scope and staff email
No events for a person	Enable per-person sync; confirm published day exists
Events stale	Check Admin → recent sync jobs; retry failed jobs

See also

• Outlook calendar (Microsoft 365 schools)
• Exports / ICS (subscribe without write-back)