PSA/ee/docs/plans/2026-05-29-teams-diagnostics-test-message/PRD.md

PRD: Teams Admin Diagnostics and Proactive Test Message

Plan slug: 2026-05-29-teams-diagnostics-test-message Owning area: EE / Microsoft Teams addon (ee/packages/microsoft-teams) + packages/integrations settings UI Related plans:

• .ai/teams_improvements/microsoft-teams-addon-competitive-parity-plan.md (Phase 1: "Setup Wizard, Diagnostics, and Test Message")
• ee/docs/plans/2026-05-24-teams-observability-loop/ (completed, PR #2562, F001–F050) — built the teams_notification_deliveries, teams_audit_events, and teams_conversation_references tables this plan consumes.

Problem Statement

The Teams addon is a functional v0 (bot, message extension, quick actions, meetings, package generation, entitlement gating, and — as of the observability loop — persisted delivery/audit records). But an admin still has no way to confirm a tenant is correctly wired up except by reading server logs. There is no diagnostics surface and no test-message path. This is the gating blocker for charging: a non-developer admin cannot self-verify that profile, Graph token, bot credentials, user linkage, and delivery all work end-to-end.

Separately, the observability loop added teams_conversation_references (written on every inbound bot activity) and the repo already has sendBotActivity() — the full Bot Framework proactive-send primitive. Neither is consumed by anything yet. Building the test message on the proactive path lights up both, and validates the exact mechanism Phase 2 channel delivery will depend on.

User Value

• MSP admins can run one-click diagnostics and a test message to confirm Teams is working, without engineering.
• Diagnostics distinguish failure classes (missing addon, inactive integration, unready profile, missing package/base URL, missing bot credentials, missing user linkage, missing conversation reference, recent Graph delivery failure) so the fix is obvious.
• Engineers get a proven proactive-send path (the building block for Phase 2 channel notifications) exercised in production.
• Sales/demo risk drops — the addon becomes self-verifiable, which is the precondition for packaging it as paid.

Goals

1. A runTeamsDiagnostics() server action returns a structured, step-based report (pass/warn/fail/skip per check + aggregated recommendations), modeled on runMicrosoft365Diagnostics().
2. A sendTeamsTestMessage() server action delivers a synthetic message to the calling admin via the proactive bot path (sendBotActivity against the admin's stored teams_conversation_references row) and records a teams_notification_deliveries row.
3. A diagnostics + test-message panel is added to TeamsIntegrationSettings.tsx (incremental — not a full wizard rebuild).
4. A read helper for teams_conversation_references exists (the table's first consumer).
5. All new DB reads are tenant-scoped; both actions are wrapped in withAuth and gated on the same permission as saveTeamsIntegrationSettings.
6. No new migration — reuse teams_notification_deliveries (test row) and teams_conversation_references (lookup).

Non-Goals (Explicit)

• No teams_channel_mappings, channel routing, or channel delivery. (Phase 2.)
• No expanded notification categories (ticket_created, etc.). (Phase 2.)
• No teams_user_preferences / quiet hours / mention-only. (Phase 2.)
• No full 4-step setup wizard restructure — only add a diagnostics/test panel to the existing settings page.
• No 402/403 entitlement-response standardization. (Open Decision, separate PR.)
• No configurable channel tab, no trial flow, no metering.
• No LLM/fuzzy bot intent, no SSO token exchange.
• No new metrics export / Prometheus / log shipping.
• No change to existing notification delivery or bot reply behavior — diagnostics/test are additive read + a new send path.

Target Users

• MSP admins in Settings → Integrations → Teams.
• Engineers debugging a tenant's Teams setup in staging/production.

Primary Flows

Flow A: Run diagnostics

1. Admin clicks "Run diagnostics" in Teams settings.
2. runTeamsDiagnostics() executes ordered checks, each producing {status: pass|warn|fail|skip, detail, data?, error?}:
   • addon entitlement active (getTeamsAvailability)
   • integration row exists + install_status = 'active'
   • capabilities include personal_bot + activity_notifications
   • selected Microsoft profile exists, not archived, has client secret ref
   • package metadata present + base URL resolvable
   • bot connector credentials configured (isBotConnectorConfigured)
   • calling admin's Microsoft user linkage present
   • conversation reference present for that admin
   • recent delivery health: most recent success + most recent failure (tenant-scoped read of teams_notification_deliveries)
3. Report aggregates overallStatus (fail if any fail; warn if any warn; else pass) and a deduped recommendations list.
4. UI renders the step list with status badges + recommendations.

Flow B: Send test message (proactive)

1. Admin clicks "Send test message".
2. sendTeamsTestMessage() resolves availability → admin Microsoft link → latest personal conversation reference.
3. If addon inactive / integration inactive / bot not configured / no linkage / no conversation reference → returns a skipped result with an actionable reason (e.g. "message the bot once first") and records a skipped delivery row.
4. Otherwise builds a test activity and calls sendBotActivity({serviceUrl, conversationId, activity}).
5. Records a teams_notification_deliveries row (status sent/failed, destination_type = 'bot_test', category = 'test', actor metadata, idempotency key with attempt nonce).
6. UI shows success or the mapped skip/failure reason.

Data Model / Integration Notes

• No schema migration. Reuse:
  • teams_notification_deliveries — category is nullable, no CHECK; status CHECK ∈ {skipped,sent,delivered,failed}; destination_type is free text NOT NULL. Test rows use category='test', destination_type='bot_test', status ∈ {skipped,sent,failed}.
  • teams_conversation_references — PK (tenant, microsoft_user_id, conversation_id); columns include service_url, conversation_type, last_activity_at. Reader selects newest personal row per (tenant, microsoft_user_id).
• Transport already exists: teamsBotConnector.ts::sendBotActivity() (token via client-credentials → https://api.botframework.com/.default; trusted-serviceUrl suffix check; POST to /v3/conversations/{id}/activities). Credentials from env TEAMS_BOT_APP_ID / TEAMS_BOT_APP_TENANT_ID / TEAMS_BOT_APP_PASSWORD (already in helm/templates/{deployment,secret}.yaml).
• PSA-user → Microsoft-user mapping (VERIFIED): resolveTeamsRecipientLink(tenant, userId) returns {providerAccountId}, and providerAccountId is the AAD oid. Conversation references are keyed by microsoft_user_id = activity.from.aadObjectId (teamsConversationReferences.ts:48-50). nextAuthOptions.ts:881-882 deliberately stores claims.oid as the Microsoft link's provider_account_id because it equals aadObjectId (explicit comment at 878-883). The bot's existing resolveTeamsLinkedUser already relies on this. So the test message can feed providerAccountId straight into the conversation-reference reader — no normalization helper needed. Known edge (pre-existing, not introduced here): the admin bulk backfill flow (ssoActions.ts:308) stores provider_account_id = lowerEmail; Microsoft links created that way won't match a bot conversation reference (the bot already can't resolve them). Diagnostics should surface this (F021/F022 warnings), not fix it.
• Diagnostics report shape: mirror Microsoft365DiagnosticsReport / ...Step (shared/services/email/providers/MicrosoftGraphAdapter.ts:745+) — step id/title/status/durationMs/data/error, recommendations: string[], overallStatus.
• Action wiring: mirror teamsObservabilityActions.ts (export const x = withAuth(impl)). Rebuild the package (tsup → dist) so the server picks up new exports (prior loop F045).

UX / UI Notes

• New Card in TeamsIntegrationSettings.tsx below the existing config/package cards: title "Diagnostics & Test Message".
• "Run diagnostics" button → step list, each row: status badge (pass=green / warn=amber / fail=red / skip=grey) + title + detail; recommendations rendered as a bullet list below.
• "Send test message" button → success or friendly skip/error message; the missing_conversation_reference skip maps to "Open the Alga PSA bot in Teams and send it any message first, then retry."
• Both buttons disabled when addon missing or integration not active (reuse existing canPersist-style gating).
• All strings i18n'd with defaultValue fallbacks, mirroring existing integrations.teams.settings.* keys.

Risks / Open Questions

• Mapping risk — RESOLVED (verified in code): provider_account_id (Microsoft) = AAD oid = microsoft_user_id by design (nextAuthOptions.ts:881-882 + teamsConversationReferences.ts:48-50). No normalization needed. Residual edge is the email-backfill linking path, which diagnostics surfaces rather than fixes.
• Bot credentials in dev: isBotConnectorConfigured() is false without env creds, so test message is a no-op locally — diagnostics must report this clearly rather than appearing broken.
• Permission gate: confirm the exact permission saveTeamsIntegrationSettingsImpl enforces and reuse it.
• Idempotency for repeated tests: include an attempt nonce in the test delivery idempotency key so each click records a distinct row (the table has a UNIQUE on (tenant, idempotency_key)).

Acceptance Criteria / Definition of Done

• runTeamsDiagnostics() returns all listed checks with correct pass/warn/fail/skip classification and an accurate overallStatus + recommendations; tenant-scoped; permission-gated; covered by unit tests.
• sendTeamsTestMessage():
  • on a healthy tenant, sends via sendBotActivity and records a sent delivery row;
  • on each unhealthy precondition, returns the correct skip reason and records a skipped row;
  • on transport failure, records a failed row;
  • all writes tenant-scoped; covered by unit/integration tests.
• The reader returns the newest personal conversation reference per (tenant, microsoft_user_id), tenant-scoped, null-safe.
• Settings panel renders diagnostics steps + recommendations and the test-message result, with correct disabled states.
• No new migration; no change to existing delivery/bot-reply behavior.
• @alga-psa/microsoft-teams rebuilt so the server resolves the new exports.