Appearance
Outlook calendar sync
Who this is for: Tenant owner, Admin
What you'll achieve: Push published duty assignments into staff Outlook calendars via Microsoft Graph
Requires role
integrations.outlook.configure
Feature-gated
This integration is off by default. Your platform operator must enable the outlook_calendar flag for your school before Admin → Outlook calendar appears.
What it does
When a day is published, SchoolRota enqueues a background job that creates, updates, or deletes Outlook events for staff who have calendar sync enabled.
Safety rules:
- SchoolRota only modifies events it created (tracked by an internal link + Graph extension property).
- Personal meetings and other calendar items are never touched.
- Publishing always succeeds even if Outlook sync fails — failures appear in the sync job list with a retry option.
Before you begin
- Platform operator enables Outlook calendar for your tenant (
/operator→ Tenant feature flags). - Microsoft Entra admin registers an app with application permission
Calendars.ReadWrite(and directory read for UPN lookup), grants admin consent, and restricts mailbox access with Exchange application RBAC / access policy. - Set
INTEGRATION_ENCRYPTION_KEYandCRON_SECRETin your deployment environment (see Deployment).
Configure in Admin
- Open Admin → Outlook calendar integration.
- Enter Microsoft tenant ID, application client ID, and client secret.
- Save configuration, then Run health check (uses a test UPN or the first sync-enabled staff email).
- Enable sync per staff member (requires a work email on their person record).
- Enable sync (master switch) — this backfills the configured lookahead window of published days.
Staff opt-in
Sync is per person, not automatic for everyone with an email. Enable the checkbox for each teacher who should receive Outlook events.
Staff without an email in the directory cannot be synced.
Disconnect
- Disconnect & cleanup — stops new sync and removes SchoolRota-owned events from Outlook, then clears credentials.
- Force disconnect (documented for operators) leaves remote events in place.
ICS vs Outlook
| ICS export | Outlook write-back | |
|---|---|---|
| Direction | Pull (download/subscribe) | Push after publish |
| Setup | Exports page | Admin integration + per-person enable |
| Personal events | Read-only | Untouched |
Use ICS for Google Calendar or Apple Calendar users.
Troubleshooting
| Symptom | Check |
|---|---|
| Integration hidden | Operator flag outlook_calendar |
| Health check fails | Entra app permissions, admin consent, mailbox scope, correct UPN |
| Events not appearing | Person sync enabled, day published, job status in Admin |
| Job failed | Retry from Admin; verify CRON_SECRET, Redis/worker, Graph throttling |
| One person out of sync | Last error column in Staff calendar sync — usually a mailbox permission or renamed mailbox |
| Result says "queued for next run" | Normal on very large days: each run has a capped Outlook budget and a follow-up job finishes the rest |
Reading the job list. Each job shows what it did (created, updated, removed, unchanged). unchanged occurrences cost no Outlook calls, so republishing a day that has not really changed is cheap. Retrying a job resets its attempt counter, so it gets a full set of automatic retries again.