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
Included on new schools
New organisations get the outlook_calendar flag on, so Admin → School → Staff calendars → Outlook calendar is available. Sync does not start until your IT team completes the Microsoft Entra setup below. Your platform operator can still turn the flag off.
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.
Sync scope
In Admin → School → Staff calendars → Outlook 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 Outlook sync enabled.
Before you begin
- Confirm Admin → School → Staff calendars → Outlook calendar is visible (on by default for new schools). If it is hidden, ask your platform operator to enable
outlook_calendar. - 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. AddUser.Read.Allon the same app if you also want Microsoft profile photos. - Set
INTEGRATION_ENCRYPTION_KEYandCRON_SECRETin your deployment environment (see Deployment).
Configure in Admin
- Open Admin in the sidebar, then School, then Staff calendars, then Outlook calendar.
- 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
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 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 | My schedule or Exports, if Calendar subscribe is on | Admin integration + per-person enable |
| Personal events | Read-only | Untouched |
Use ICS for Apple Calendar users when Settings → School → Calendar subscribe is on (published duties then leave SchoolRota), or enable Google Calendar write-back for Google Workspace schools.
Troubleshooting
| Symptom | Check |
|---|---|
| Integration hidden | Operator flag outlook_calendar off (new schools have it on) |
| 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 stays pending | Wait about a minute, then refresh Recent sync jobs. The web process drains the outbox on its own |
| 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 uses plain wording (for example Published the rota and 1 event added). Open Details to see who was added, updated, or removed. Older jobs may only have a summary. Republishing a day that has not really changed is cheap: matching events are left as they are. Try again on a failed job resets its attempt counter.