Microsoft Graph
Crate: adapter-microsoft-graph · Capabilities: calendars, tasks, contacts
The modern Microsoft API for Outlook/Microsoft 365 — calendars + events,
Microsoft To Do (todoTask), and Outlook contacts.
Authentication
Section titled “Authentication”OAuth2 (Microsoft identity platform). As with Google, the host owns the
flow and token refresh; the adapter sends a Bearer token.
Reading data
Section titled “Reading data”- Events: the adapter uses
/calendarView(withstartDateTime/endDateTime), which expands recurring events server-side into individual instances for the range. This is unlike the master+frontend-expansion model the other adapters use — it’s simpler here because Graph’s structured recurrence doesn’t map 1:1 to RRULE for every shape. Consequence: the adapter never returns a recurring master; each month’s instances are fetched (and cached) per range.iCalUIddiffers per instance, so it is an event’sical_uidonly for asingleInstance;uid, which a series shares, wins where Graph sends it (unmeasured whether the default property set carries it). - Delta:
/calendarView/delta,/todoTaskdelta, and contacts delta, each with the same410/invalid token → full resyncrule.
Quirks
Section titled “Quirks”-
Colours arrive as a named enum (
auto,lightBlue, …) and are mapped to hex. -
Recurrence model. Because
/calendarViewexpands server-side, the “recurring master missing from a future view” class of bug doesn’t apply here — but each range needs its own fetch (no master reuse across months). -
MS To Do has no assignment. Task assignment is a Planner concept, which is a separate, heavier surface and out of scope.
-
MS To Do has no subtasks either. Its
checklistItemsare plain strings without a usable write API and don’t map onto task→task parents, so the plugin manifest declaressubtasks: falseand the editors never offer subtasks on a Graph list. -
The organizer answers “organizer”. Graph lists the organizer among the attendees with
status.response“organizer”; the adapter drops that row by its response.isOrganizersays whether the signed-in user organizes the event, and that answer counts even without an organizer address; when it says no, or when it is missing and an organizer is named, the event isorganized_elsewhereand only the organizer notifies. An update whose invitees did not change (keep_attendees) sends noattendees, so Graph keeps its own list. One that removed every invitee (clear_attendees) sends an empty list, but only when notifying: Graph mails wheneverattendeesis in the body, so a silent removal cannot reach it. -
No repeat is a
null, and only on the host’s word (decision 280). A missing pattern leavesrecurrenceout of the PATCH, since a series whose pattern the adapter cannot read has none either. Onlyclear_recurrence, whichguard_updatesets when the cached copy repeats, the edit does not, and the edit was made from that very version (same ETag), sends"recurrence": null, as Graph’s update reference shows it. Not where the event read just before the PATCH holds no pattern (an occurrence, or a series another client made single). Unmeasured against a live mailbox, and dormant today: the adapter reads only/calendarView, so no cached row repeats andguard_updatenever sets the flag for a Microsoft 365 event. It takes effect once the adapter reads series masters. -
Graph always notifies. Attendees in the body of a create or an update are mailed, and deleting a meeting on the organizer’s calendar sends its cancellation (Microsoft’s documentation; not measured live). Its calendars therefore carry
always_notifies_attendeeswithnotifier_name“Microsoft 365”, and the editors say so instead of offering a silent save or delete (decision 82b). -
A busy Graph. The request helpers build
GraphError::Busy(decision 270): for 429, which did nothing, and for 503 withRetry-Afteron a request that writes nothing (the reads,getSchedulethroughpost_query_json, and the token endpoint). A write answered 503 may have been carried out, so it stays unsure. The wait Graph names is only logged. An update whose read of the current event is busy sends no PATCH. A task’s Aperio-Extras extension is written in place (PATCH, aPOSTonly where it is missing), never deleted and created again: a create that failed after the delete took the task’s recurrence with it. A failure of that write after the task’s own PATCH isGraphError::PartlySaved(277). A busy DELETE after a landed/cancelcounts as done, as a 404 does: the meeting is cancelled and off the calendar. Any other failure of that DELETE goes throughafter_landed: the cancellation reached every attendee, so it never reads as “nothing was changed”. A contact search says busy only where neither source answered. A new contact whose photo upload fails is still returned, withhas_photofalse, and the editor says so.
Testing
Section titled “Testing”mockito with canned Graph JSON, including delta envelopes
(@odata.deltaLink / @odata.nextLink). Tests cover the
initial-vs-follow delta paths, the 410 → resync fallback, and the
calendarView instance mapping. Live testing needs an Azure app
registration with the relevant Graph scopes.