Skip to content

Microsoft Shifts Schedule Sync

ZAI can connect to your Microsoft Shifts rotas and use them as the live source of truth for who's on shift. Once it's enabled, availability across the Resource Scheduling dashboard updates automatically from your published shifts — no manual timetable entry required.

Overview

ZAI polls the Microsoft Graph API on a background timer, reads each Teams team's published rota and time-off blocks, and stores them as concrete, dated schedule entries. An availability resolver then works out whether each employee is on shift at any moment from those entries. The Resource Scheduling view receives live updates over SignalR, so shift cards flip on and off in real time as each poll completes.

Employees not yet covered by Shifts keep using the static weekly schedule template, so you can roll the integration out team by team.

Getting started

Prerequisites

  • Microsoft Teams with the Shifts app set up, and at least one team with a published schedule.
  • ZAI's Microsoft Graph integration configured for your tenant, with permission to read team schedules. This is part of your ZAI environment setup.
  • Each employee who appears in Shifts must be linked to their Microsoft 365 account in ZAI, so ZAI can map a Graph user to the right employee.

Schedule read permission needs admin consent

Reading team schedules from Microsoft Graph uses application-level permission that a tenant administrator must consent to. Without consent, the sync logs an authorisation error and no data flows. Your administrator (or Zenzero support) handles this during setup.

Steps (administrator)

  1. Enable the Shifts sync in your ZAI environment's configuration.
  2. Add the Microsoft Teams team IDs you want to sync.
  3. Adjust the polling interval and how far ahead to read, if needed (see Configuration).
  4. Restart the application — the background poller starts immediately and logs its first sync result.
  5. Confirm each Shifts employee is linked to their Microsoft 365 account in ZAI. Anyone unmatched appears in the sync log and won't be Shifts-managed until linked.

Finding a team ID

In the Microsoft Teams admin centre, open the team — its ID appears in the URL. Alternatively, use Graph Explorer: GET https://graph.microsoft.com/v1.0/me/joinedTeams.

Key concepts

Shifts-managed vs template-managed

An employee is Shifts-managed while ZAI has recently seen them in a synced rota. Their on-shift status then comes entirely from their actual shifts — the weekly template is ignored.

If that data goes stale (for example, the poller can't reach Graph for a while, or the employee leaves all synced teams), ZAI automatically falls back to the weekly schedule template. Availability is never left blank.

Time-off takes priority

If an employee has a published time-off block covering the current moment, they're shown as off-shift even if a shift block would otherwise be active — matching how Shifts itself presents availability.

Live updates

After each sync cycle, ZAI pushes an update for every affected employee to anyone viewing the Resource Scheduling dashboard. Each update reflects the employee's current on-shift status, the shift in progress (if any), and when their status is next expected to change — all without a page refresh.

Only published shifts sync

ZAI reads the published version of each schedule. Draft shifts a manager hasn't published yet won't appear until they're published in Teams.

Configuration

Shifts sync is configured in your ZAI environment by an administrator. The key settings are:

Setting Default Description
Enabled Off Turns the background poller on.
Team IDs — The Microsoft Teams teams to sync (one entry per team).
Poll interval 5 minutes How often ZAI checks Graph for rota changes.
Horizon 14 days How far ahead to read shifts (overnight shifts from the previous day are always included).
Staleness window 30 minutes How long after the last successful sync an employee stays Shifts-managed before falling back to the weekly template.

Hosted customers

On a Zenzero-hosted instance, ask Zenzero support to enable Shifts sync and supply your team IDs. There's no in-app toggle for this feature.

Troubleshooting

Employees show as off-shift when they should be on. Confirm the shift is published in Teams (not just drafted), and that the employee is correctly linked to their Microsoft 365 account in ZAI. The sync log flags any unmatched team members.

No sync activity in the logs. Check that the sync is enabled, at least one team ID is configured, and admin consent has been granted for the schedule-read permission.

Live updates aren't appearing on the dashboard. The dashboard reconnects automatically after a dropped connection, but a hard page refresh always re-establishes it. If updates never arrive, confirm the application was restarted after the feature was enabled.

Employees keep falling back to the weekly template during the day. The poller may be failing silently — usually an expired Graph token, revoked consent, or an incorrect tenant configuration. Check the application log for failed sync cycles.