PSA/ee/docs/plans/2026-04-23-teams-meeting-on-appointment-approval/PRD.md

# PRD — Teams Meeting Link on Appointment Approval

- Slug: `teams-meeting-on-appointment-approval`
- Date: `2026-04-23`
- Status: Draft

## Summary

Generate a Microsoft Teams online meeting link automatically when an MSP staff member approves an appointment request, controlled per-appointment by a toggle on the approval form. The Teams join URL is embedded in the client-facing approval email, the calendar ICS attachment, the MSP schedule-entry view, and the client-portal appointment detail page. Meetings follow the appointment's lifecycle: they are patched when the schedule is changed and deleted when the appointment is cancelled.

## Problem

MSP operators running virtual consultations currently have to create a Teams meeting manually after approving an appointment request, then paste the join link into a follow-up email to the client. This is slow, error-prone, and leaves the ICS calendar attachment without a join URL. With the Teams integration shipping for tenant notifications, we have a viable path to create meetings on the tenant's behalf and close the loop.

## Goals

- Let MSP approvers create a Teams meeting at approval time with a single toggle (no second screen, no copy-paste).
- Ship the join URL to the client via the existing approval email and ICS attachment.
- Keep the meeting in sync when the appointment is rescheduled or cancelled so the link never points at a stale time.
- Expose tenant-level configuration (default meeting organizer) in an existing settings surface so admins can turn the feature on without a developer.
- EE-only: CE builds must continue to work unchanged.

## Non-goals

- Supporting providers other than Microsoft Teams (Zoom, Google Meet). The schema is generic to allow this later, but only the Teams provider is implemented.
- Per-user delegated OAuth. All meetings are created as a designated tenant organizer via app-only auth.
- A general "integrations" admin hub. The configuration lives inside Availability Settings → Teams Meetings tab because it is tied to the appointment-approval workflow, not a standalone concern.
- Retries / background queues / circuit breakers for Graph calls. On failure we log, show a warning toast, and let the approver retry manually if desired.
- Recording/transcript policies, lobby/PSTN options, federated participants. Meetings are created with Graph defaults.
- Translating templates beyond English for the new strings. Pseudo-locale regeneration + translation pass can follow the usual i18n pipeline.

## Users and Primary Flows

**MSP approver (primary)**
1. Opens a pending appointment request in the MSP panel or via the calendar Edit Entry modal.
2. Sees the "Generate Teams meeting link" toggle (only if their tenant has Teams configured AND has an organizer set). Toggle defaults ON.
3. Clicks Approve. Schedule entry is created and — if toggle on — a Teams meeting is created on behalf of the tenant's designated organizer.
4. Sees the join URL on the approved appointment's detail view, and a green success toast. If the Graph call failed, sees a yellow warning toast explaining the approval succeeded but the meeting was not created.

**MSP admin (setup)**
1. Navigates to Scheduling → Availability Settings. The "Teams Meetings" tab is visible only when `teams_integrations.install_status = 'active'`.
2. Enters the default meeting organizer UPN (e.g., `scheduling@acme.com`). Saves.
3. A validation server action optionally verifies the UPN resolves to a Microsoft user (best-effort; failure is a warning, not a blocker).

**MSP approver (reschedule)**
1. Opens an approved appointment request and updates `final_date` / `final_time`.
2. If the appointment has an `online_meeting_id`, the server patches the meeting via Graph to the new times.
3. If the PATCH fails, the reschedule still succeeds; a warning toast informs the approver.

**MSP approver (cancel / decline)**
1. Clicks Cancel or Delete on an approved appointment that has an associated Teams meeting.
2. A confirmation dialog warns: "This will also delete the Microsoft Teams meeting."
3. On confirm, the Graph DELETE is attempted. Success or failure, the appointment state change proceeds; Graph errors become warnings.

**Client (end user)**
1. Receives the approval email with a "Join Teams Meeting" button.
2. Opens the ICS attachment in their calendar; the LOCATION field shows "Microsoft Teams Meeting" and the URL/description contain the join link.
3. In the client portal, the appointment detail page shows a prominent "Join Teams Meeting" button.

## UX / UI Notes

**Approval form — toggle**
- Label: "Generate Microsoft Teams meeting link"
- Placement: between "Assign Technician" and "Internal Notes" in the approval form within `AppointmentRequestsPanel.tsx` and in the pending-request approval UI in `EntryPopup.tsx`.
- Visibility: only if `getTeamsMeetingCapability(tenantId)` returns `{ available: true }`.
- Default: checked.

**Availability Settings — new tab**
- New `TabsTrigger value="teams-meetings"` appended to the existing list in `AvailabilitySettings.tsx`.
- Tab visibility gated by a readiness check (`install_status = 'active'`); the whole `<TabsTrigger>` is conditionally rendered so non-configured tenants never see it.
- Body contains: a single Input for "Default meeting organizer (UPN or Microsoft user ID)" with help text, a Save button, and a small "Verify" link that calls Graph `/users/{upn}` to confirm the user exists.
- A warning banner at the top of the tab lists prerequisites the admin must complete in Azure: application permission `OnlineMeetings.ReadWrite.All` + an Application Access Policy granting the app permission to create meetings for this user.

**MSP schedule-entry view (approved)**
- Add a "Join Teams Meeting" button inside the existing success banner in `EntryPopup.tsx`. Clicking opens the URL in a new tab.

**Client-portal appointment details**
- Add a prominent primary button "Join Teams Meeting" when `online_meeting_url` is present. Placed near the date/time block in `AppointmentRequestDetailsPage.tsx`.

**Email templates**
- `appointment-request-approved-client`: add a conditional Handlebars block that renders a "Join Teams Meeting" button when `{{onlineMeetingUrl}}` is present.
- `appointment-assigned`: same conditional block for the assigned technician.

**ICS file**
- When `online_meeting_url` is present, set `LOCATION: Microsoft Teams Meeting` and include the URL in both the `URL` property (which `icsGenerator` already supports) and append a line to `DESCRIPTION`: "Join Teams Meeting: {{url}}".

**Failure UX**
- `approveAppointmentRequest` returns `{ success: true, data: ..., teamsMeetingWarning?: string }`. When the warning is present, the UI shows a yellow `variant="warning"` toast and continues showing the approved state.
- Reschedule failures → `{ ..., teamsMeetingWarning?: string }` in the update action's return, surfaced as a toast.
- Delete failures → warning toast: "Appointment deleted, but the Microsoft Teams meeting could not be removed. Please remove it manually in Teams."

## Requirements

### Functional Requirements

**FR-1 Schema: `appointment_requests`**
- Add nullable columns: `online_meeting_provider` (text), `online_meeting_url` (text), `online_meeting_id` (text).
- Values populated only when a meeting is successfully created.

**FR-2 Schema: `teams_integrations`**
- Add nullable column `default_meeting_organizer_upn` (text).
- Readiness check for meeting creation = `install_status = 'active'` AND `selected_profile_id IS NOT NULL` AND `default_meeting_organizer_upn IS NOT NULL`.

**FR-3 Helper: `createTeamsMeeting()`**
- Location: `ee/packages/microsoft-teams/src/lib/meetings/createTeamsMeeting.ts`.
- Input: `{ tenantId, subject, startDateTime, endDateTime }`.
- Behaviour: resolve profile via `resolveTeamsMicrosoftProviderConfigImpl`, fetch app token via `fetchMicrosoftGraphAppToken`, read organizer UPN from `teams_integrations`, POST to `https://graph.microsoft.com/v1.0/users/{upn}/onlineMeetings`.
- Output: `{ joinWebUrl, meetingId } | null`. Logs on failure and returns `null`.

**FR-4 Helper: `updateTeamsMeeting()`**
- Same location. Input: `{ tenantId, meetingId, startDateTime, endDateTime }`.
- PATCHes `/users/{upn}/onlineMeetings/{id}` with new times.

**FR-5 Helper: `deleteTeamsMeeting()`**
- Same location. Input: `{ tenantId, meetingId }`. Fire-and-forget DELETE. Surfaces errors only via log.

**FR-6 Readiness server action: `getTeamsMeetingCapability(tenantId)`**
- Location: `ee/packages/microsoft-teams/src/lib/actions/meetings/meetingCapabilityActions.ts`.
- Output: `{ available: boolean, reason?: 'ee_disabled' | 'not_configured' | 'no_organizer' }`.
- Called from the approval form to decide toggle visibility.

**FR-7 CE/EE split**
- `packages/scheduling/` (CE-safe) calls the Teams helpers only via a dynamic EE import guarded by an edition check. CE builds must not require the `ee/packages/microsoft-teams` package.
- Pattern: a thin `resolveTeamsMeetingService()` in scheduling that returns no-op handlers when EE is not available.

**FR-8 Approval schema update**
- `approveAppointmentRequestSchema` adds `generate_teams_meeting: boolean` (default false).

**FR-9 `approveAppointmentRequest` action**
- After schedule_entry insert, if `input.generate_teams_meeting === true`, call `createTeamsMeeting()`.
- On success: `UPDATE appointment_requests SET online_meeting_provider='teams', online_meeting_url=..., online_meeting_id=... WHERE appointment_request_id = ?`.
- Pass `onlineMeetingUrl` into the approved email template payload.
- Pass `url` into the ICS generator input.
- On failure: populate `teamsMeetingWarning` in response; do not fail the approval.

**FR-10 `updateAppointmentRequestDateTime` action**
- If the request has `online_meeting_id` and provider is `teams`, call `updateTeamsMeeting()` with the new start/end.
- On failure: surface `teamsMeetingWarning`.

**FR-11 Cancel / delete flow**
- `cancelAppointmentRequest` (client portal) and MSP-side deletion: when `online_meeting_id` present and provider is `teams`, call `deleteTeamsMeeting()`.
- UI: cancel/delete confirmation dialogs show the warning text about removing the Teams meeting when the appointment has one.
- After-the-fact warning toast on Graph failure.

**FR-12 UI: Approval form toggle**
- `AppointmentRequestsPanel.tsx` and the pending branch of `EntryPopup.tsx` render the toggle only when `getTeamsMeetingCapability` says available. Default checked.

**FR-13 UI: Join button on MSP entry view**
- `EntryPopup.tsx` approved banner includes a "Join Teams Meeting" button when `appointmentRequestData.online_meeting_url` is present.

**FR-14 UI: Join button on client portal**
- `packages/client-portal/src/components/appointments/AppointmentRequestDetailsPage.tsx` renders a primary button when URL is present.

**FR-15 Admin UI: Teams Meetings tab in Availability Settings**
- Conditional `<TabsTrigger>` + `<TabsContent>` in `AvailabilitySettings.tsx`.
- Form: single UPN input + Save + optional Verify button.
- Backing server action: `setDefaultMeetingOrganizer({ tenant, upn })` writes to `teams_integrations.default_meeting_organizer_upn` (requires `tenant_integrations:update` or equivalent permission).
- Optional `verifyMeetingOrganizer({ tenant, upn })` that calls Graph `/users/{upn}` and returns `{ valid: boolean, displayName?: string, reason?: string }`.

**FR-16 Email templates**
- Update the two template migrations (or add a new migration) to add a conditional "Join Teams Meeting" section rendered via `{{#if onlineMeetingUrl}}...{{/if}}`.
- Templates updated: `appointment-request-approved-client`, `appointment-assigned`.

**FR-17 ICS generator integration**
- Pass `url: online_meeting_url` and `location: 'Microsoft Teams Meeting'` into `ICSEventData` when a meeting was created.

**FR-18 i18n**
- New keys under `entryPopup`, `requests.approval`, `availabilitySettings.tabs`, `availabilitySettings.teamsMeetings.*`, and client-portal appointment translations. Add to English; regenerate pseudo locales.

### Non-functional Requirements

- **EE gating**: All Graph-calling code lives under `ee/`. CE build continues to succeed.
- **Fail soft**: Any Graph call that fails must not fail the parent user action (approve, reschedule, cancel). Errors are logged with a structured message including `tenant`, `appointment_request_id`, `operation` (`create | update | delete`), and the Graph error code/body.
- **Audit trail**: Meeting creation/update/delete operations go through existing `publishEvent` logging — one new event: `APPOINTMENT_ONLINE_MEETING_ATTACHED` (optional MVP, only if cheap to add). If not emitted, the regular `SCHEDULE_ENTRY_UPDATED` event still fires.

## Data / API / Integrations

**Migrations**

1. `server/migrations/<timestamp>_add_online_meeting_columns_to_appointment_requests.cjs`
   - Adds three nullable text columns to `appointment_requests`.
   - Safe under Citus (adds to distributed table, no distribution key change).

2. `ee/server/migrations/<timestamp>_add_default_meeting_organizer_to_teams_integrations.cjs`
   - Adds nullable `default_meeting_organizer_upn text` column.

**Microsoft Graph endpoints**

- Create: `POST https://graph.microsoft.com/v1.0/users/{upn}/onlineMeetings`
  - Body: `{ subject, startDateTime, endDateTime }` (ISO 8601, UTC).
  - Requires app permission `OnlineMeetings.ReadWrite.All` + Application Access Policy authorising the app for the organizer user.
- Update: `PATCH /users/{upn}/onlineMeetings/{id}` with `{ startDateTime, endDateTime }`.
- Delete: `DELETE /users/{upn}/onlineMeetings/{id}`.
- Verify user (optional): `GET /users/{upn}` returns `{ displayName, userPrincipalName, id }`.

**Reused infrastructure**

- `resolveTeamsMicrosoftProviderConfigImpl` at `ee/packages/microsoft-teams/src/lib/auth/teamsMicrosoftProviderResolution.ts`.
- `fetchMicrosoftGraphAppToken` at `ee/packages/microsoft-teams/src/lib/notifications/teamsNotificationDelivery.ts` (or extract to a shared auth module if preferred).
- `getTeamsIntegrationExecutionStateImpl` at `ee/packages/microsoft-teams/src/lib/actions/integrations/teamsActions.ts`.
- `generateICSBuffer` / `ICSEventData` at `packages/scheduling/src/utils/icsGenerator.ts` (already supports `url` and `location`).

## Security / Permissions

- **Tenant isolation**: Meeting creation always scoped to the tenant's own Microsoft profile; no cross-tenant Graph calls possible.
- **Organizer UPN update permission**: reuse `tenant_integrations:update` (or the existing permission covering `teams_integrations`).
- **Secret handling**: Graph tokens are short-lived and fetched per-call — not persisted. Existing `fetchMicrosoftGraphAppToken` path is already battle-tested.
- **Meeting URL exposure**: join URLs are visible to anyone who receives the email or can view the appointment in the client portal. This matches the current Teams meeting access model — Graph-issued links require the user to be allowed by the tenant's meeting policies.

## Observability

- Structured log lines for every Graph call at INFO on success and WARN on failure, including `tenant`, `appointment_request_id`, `operation`, and Graph response status/code.
- No new metrics or dashboards in this plan. (Out of scope per the "no gold-plating" principle.)

## Rollout / Migration

**Phase 1 — Ship dark (no behaviour change)**
- Apply both migrations. No code path reads the new columns yet, so CE + EE tenants are unaffected.

**Phase 2 — EE code + admin UI**
- Ship the helpers, server actions, availability-settings tab, approval-form toggle, email template update, and client-portal button.
- The toggle is only visible if the tenant has set `default_meeting_organizer_upn` — so the feature is inert until an admin opts in.

**Phase 3 — Documentation**
- Add an Azure admin runbook: how to grant `OnlineMeetings.ReadWrite.All` application permission and how to create the Application Access Policy authorizing the organizer user. Include the PowerShell snippets.
- Location: `docs/integrations/teams-meetings-setup.md`.

**Feature flag**
- Reuse existing PostHog flag `teams-integration-ui` for the UI surfaces. No new flag unless we want to gate meetings separately; the existing gate is enough.

**Backout**
- If issues arise, setting `default_meeting_organizer_upn = NULL` instantly hides the toggle and disables new meeting creation, without requiring a deploy. Existing appointments with stored URLs continue to work.

## Open Questions

1. Should `verifyMeetingOrganizer` also check that an Application Access Policy exists, or just that the user exists? Graph doesn't expose policy membership directly; a working test-call is the only true check. **Tentative answer:** the Verify button performs a dry-run `POST /users/{upn}/onlineMeetings` with a throwaway meeting and deletes it if successful. Heavier but truthful. If rejected, show the Azure admin runbook link.
2. When reschedule fires, should we also update `subject` or only times? **Tentative answer:** only times. If the approver wants to change the subject they can do it in Teams.
3. Do we need to update the EE edition check module, or does `ee/packages/microsoft-teams` have an existing ambient export that CE can safely call (returning no-op)? **Verify before implementation.**

## Acceptance Criteria (Definition of Done)

- [ ] Both migrations applied; columns present in dev + staging DBs.
- [ ] `createTeamsMeeting`, `updateTeamsMeeting`, `deleteTeamsMeeting` helpers return correctly shaped results against a fixture tenant (manual QA).
- [ ] `getTeamsMeetingCapability` returns `{ available: false, reason: 'not_configured' }` for a tenant with no `teams_integrations` row; returns `{ available: false, reason: 'no_organizer' }` when UPN is null; returns `{ available: true }` when all prerequisites are met.
- [ ] Approval form toggle is hidden when capability is unavailable and visible (default ON) when available.
- [ ] Approving a request with the toggle on creates a Teams meeting, stores the three columns, injects the join URL into the approval email, and adds it to the ICS file.
- [ ] Approval still succeeds if Graph returns a 403/404/5xx; warning toast is shown; appointment is approved without meeting columns populated.
- [ ] Rescheduling an appointment with `online_meeting_id` patches the Graph meeting; times on the join link match the new time.
- [ ] Cancelling/declining an appointment with `online_meeting_id` deletes the Graph meeting; confirmation dialog warns about the deletion.
- [ ] Client-portal detail page shows the "Join Teams Meeting" button for appointments with a URL.
- [ ] Availability Settings → Teams Meetings tab appears only when `install_status = 'active'`; organizer UPN can be saved and verified.
- [ ] CE builds pass (`npm run build` without `ee`).
- [ ] EE builds pass (`npm run build:ee`).
- [ ] Translation validator (`node scripts/validate-translations.cjs`) reports 0 errors after pseudo-locale regeneration.
- [ ] Azure admin runbook exists at `docs/integrations/teams-meetings-setup.md`.