docs(teams): split meetings setup from operator runbook

2026-05-11 03:31:55 +00:00 · 2026-05-07 17:27:11 +03:00 · 2026-05-07 17:27:11 +03:00 · b79ef8827f
commit b79ef8827f
parent 1997b3baf8
4 changed files with 429 additions and 1 deletions
--- a/website/docs/guides/operate-teams-meeting-pipeline.md
+++ b/website/docs/guides/operate-teams-meeting-pipeline.md
@ -0,0 +1,193 @@
+---
+title: "Operate the Teams Meeting Pipeline"
+description: "Runbook, go-live checklist, and operator worksheet for the Microsoft Teams meeting pipeline"
+---
+
+# Operate the Teams Meeting Pipeline
+
+Use this guide after you have already enabled the feature from [Teams Meetings](/docs/user-guide/messaging/teams-meetings).
+
+This page covers:
+- operator CLI flows
+- routine subscription maintenance
+- failure triage
+- go-live checks
+- rollout worksheet
+
+## Core Operator Commands
+
+### Validate the config snapshot
+
+```bash
+hermes teams-pipeline validate
+```
+
+Use this first after any config change.
+
+### Inspect token health
+
+```bash
+hermes teams-pipeline token-health
+hermes teams-pipeline token-health --force-refresh
+```
+
+Use `--force-refresh` when you suspect stale auth state.
+
+### Inspect subscriptions
+
+```bash
+hermes teams-pipeline subscriptions
+```
+
+### Renew near-expiry subscriptions
+
+```bash
+hermes teams-pipeline maintain-subscriptions
+hermes teams-pipeline maintain-subscriptions --dry-run
+```
+
+### Inspect recent jobs
+
+```bash
+hermes teams-pipeline list
+hermes teams-pipeline list --status failed
+hermes teams-pipeline show <job-id>
+```
+
+### Replay a stored job
+
+```bash
+hermes teams-pipeline run <job-id>
+```
+
+### Dry-run meeting artifact fetches
+
+```bash
+hermes teams-pipeline fetch --meeting-id <meeting-id>
+hermes teams-pipeline fetch --join-web-url "<join-url>"
+```
+
+## Routine Runbook
+
+### After first setup
+
+Run these in order:
+
+```bash
+hermes teams-pipeline validate
+hermes teams-pipeline token-health --force-refresh
+hermes teams-pipeline subscriptions
+```
+
+Then trigger or wait for a real meeting event and confirm:
+
+```bash
+hermes teams-pipeline list
+hermes teams-pipeline show <job-id>
+```
+
+### Daily or periodic checks
+
+- run `hermes teams-pipeline maintain-subscriptions --dry-run`
+- inspect `hermes teams-pipeline list --status failed`
+- verify the Teams delivery target is still the correct chat or channel
+
+### Before changing webhook URLs or delivery targets
+
+- update the public notification URL or Teams target config
+- run `hermes teams-pipeline validate`
+- renew or recreate affected subscriptions
+- confirm new events land in the expected sink
+
+## Failure Triage
+
+### No jobs are being created
+
+Check:
+- `msgraph_webhook` is enabled
+- the public notification URL points to `/msgraph/webhook`
+- the client state in the subscription matches `MSGRAPH_WEBHOOK_CLIENT_STATE`
+- subscriptions still exist remotely and are not expired
+
+### Jobs stay in retry or fail before summarization
+
+Check:
+- transcript permissions and availability
+- recording permissions and artifact availability
+- `ffmpeg` availability if recording fallback is enabled
+- Graph token health
+
+### Summaries are produced but not delivered to Teams
+
+Check:
+- `platforms.teams.enabled: true`
+- `delivery_mode`
+- `incoming_webhook_url` for webhook mode
+- `chat_id` or `team_id` plus `channel_id` for Graph mode
+- Teams auth config if Graph posting is used
+
+### Duplicate or unexpected replays
+
+Check:
+- whether you manually replayed a job with `hermes teams-pipeline run`
+- whether the sink record already exists for that meeting
+- whether you intentionally enabled a resend path in your local config
+
+## Go-Live Checklist
+
+- [ ] Graph credentials are present and correct
+- [ ] `msgraph_webhook` is enabled and reachable from the public internet
+- [ ] `MSGRAPH_WEBHOOK_CLIENT_STATE` is set and matches subscriptions
+- [ ] transcript subscription is created
+- [ ] recording subscription is created if STT fallback is required
+- [ ] `ffmpeg` is installed if recording fallback is enabled
+- [ ] Teams outbound delivery target is configured and verified
+- [ ] Notion and Linear sinks are configured only if actually needed
+- [ ] `hermes teams-pipeline validate` returns an OK snapshot
+- [ ] `hermes teams-pipeline token-health --force-refresh` succeeds
+- [ ] a real end-to-end meeting event has produced a stored job
+- [ ] at least one summary has reached the intended delivery sink
+
+## Delivery-Mode Decision Guide
+
+| Mode | Use when | Tradeoff |
+|------|----------|----------|
+| `incoming_webhook` | you only need simple posting into Teams | simplest setup, less control |
+| `graph` | you need channel or chat posting through Graph | more control, more auth and target config |
+
+## Operator Worksheet
+
+Fill this out before rollout:
+
+| Item | Value |
+|------|-------|
+| Public notification URL | |
+| Graph tenant ID | |
+| Graph client ID | |
+| Webhook client state | |
+| Transcript resource subscription | |
+| Recording resource subscription | |
+| Teams delivery mode | |
+| Teams chat ID or team/channel | |
+| Notion database ID | |
+| Linear team ID | |
+| Store path override, if any | |
+| Owner for daily checks | |
+
+## Change Review Worksheet
+
+Use this before changing the deployment:
+
+| Question | Answer |
+|----------|--------|
+| Are we changing the public webhook URL? | |
+| Are we rotating Graph credentials? | |
+| Are we changing Teams delivery mode? | |
+| Are we moving to a new Teams chat or channel? | |
+| Do subscriptions need to be recreated or renewed? | |
+| Do we need a fresh end-to-end verification run? | |
+
+## Related Docs
+
+- [Teams Meetings setup](/docs/user-guide/messaging/teams-meetings)
+- [Microsoft Teams bot setup](/docs/user-guide/messaging/teams)