Skip to main content

Outlook Calendar

Audience: Support, engineering · Where in app: Settings → Integrations → Calendars & booking → Outlook Calendar card — hidden unless the server has the Microsoft app configured · Plan availability: All plans once configured

Added with the tenant-chosen booking calendar (backend 225840d0d, ms-comm 5f1417d, ms-ai 5d620a17c, frontend 97eed5ef, 2026-11-05). It books into the connected account's default Outlook calendar through Microsoft Graph and is a full scheduling-port adapter (availability, book, find, reschedule, cancel). Nox meeting prep and calendar reads use it too.

Not tenant-visible yet

OutlookCalendarCard.vue renders only when GET /outlook/status returns configured: true (graph.configured() = client id + secret). No flux environment sets MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRET as of 2026-11-16, so the card is hidden everywhere and the customer docs don't mention Outlook.

How it works​

  • OAuth: GET /outlook/auth-url (passport, resolveIntegrationCompany, 503 when unconfigured) signs state with lib/oauthState ({company_id, user_id}); GET /outlook/callback (public) exchanges the code, reads /me (mail / userPrincipalName) and stores {access_token, refresh_token} in the credential vault (provider: 'outlook'). Scopes: offline_access User.Read Calendars.ReadWrite; authority common (work + personal accounts). Redirects to /settings/integrations?integration=outlook&success=….
  • Data (companies.outlook_calendar_integration): expires_at, account_email (the connected marker — tokens are vault-only), duration_minutes (15/30/45/60, default 30, PUT /outlook/settings), connected_at. DELETE /outlook/disconnect clears it.
  • Availability = company working_hours minus every calendarView event not marked free (same rule as Google). Spans ≤ 31 days per Graph call.
  • Length: duration_minutes, or a caller-requested 5–480 minutes (like Google).
  • Book posts /me/events with the invitee as attendee; a retry finding the invitee's own event at that start returns it. Meeting link = onlineMeeting.joinUrl, else webLink. Session rows: booking_type: 'outlook', outlook_event_id.
  • Sync back: CalendarSyncJob (15 min, schedular) re-reads our upcoming Outlook events and applies moves/cancels to bookings[] and the meetings mirror.
  • Ladder rung: isOutlookBookingEnabled (account_email set), right after Google Calendar.

Configuration & environment​

Env (backend and schedular)Notes
MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRETEntra ID app (multi-tenant + personal accounts)
MICROSOFT_REDIRECT_URIDefault BASE_URL + /outlook/callback; register it in Entra
MICROSOFT_AUTHORITYDefault https://login.microsoftonline.com/common

The schedular refreshes Graph tokens for CalendarSyncJob and Nox meeting prep, so both deployments need the keys.

Technical implementation​

  • backend: controllers/OutlookController.js, services/outlook/graph.js, services/scheduling/adapters/OutlookAdapter.js, jobs/CalendarSyncJob.js, configs/microsoft.js, routes/calendarIntegrationRoutes.js. Spec: outlook-calcom-scheduling-adapters.spec.js.
  • frontend: components/integrations/OutlookCalendarCard.vue (+ test). ms-comm / ms-ai: routed through backend /scheduling/* (TYPE_BY_PROVIDER, calendar-types.ts).