Skip to content

Commit b79ef88

Browse files
dlkakbsteknium1
dlkakbs
authored and
teknium1
committed
docs(teams): split meetings setup from operator runbook
1 parent 1997b3b commit b79ef88

4 files changed

Lines changed: 429 additions & 1 deletion

File tree

‎website/docs/guides/operate-teams-meeting-pipeline.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: "Operate the Teams Meeting Pipeline"
3+
description: "Runbook, go-live checklist, and operator worksheet for the Microsoft Teams meeting pipeline"
4+
---
5+
6+
# Operate the Teams Meeting Pipeline
7+
8+
Use this guide after you have already enabled the feature from [Teams Meetings](/docs/user-guide/messaging/teams-meetings).
9+
10+
This page covers:
11+
- operator CLI flows
12+
- routine subscription maintenance
13+
- failure triage
14+
- go-live checks
15+
- rollout worksheet
16+
17+
## Core Operator Commands
18+
19+
### Validate the config snapshot
20+
21+
```bash
22+
hermes teams-pipeline validate
23+
```
24+
25+
Use this first after any config change.
26+
27+
### Inspect token health
28+
29+
```bash
30+
hermes teams-pipeline token-health
31+
hermes teams-pipeline token-health --force-refresh
32+
```
33+
34+
Use `--force-refresh` when you suspect stale auth state.
35+
36+
### Inspect subscriptions
37+
38+
```bash
39+
hermes teams-pipeline subscriptions
40+
```
41+
42+
### Renew near-expiry subscriptions
43+
44+
```bash
45+
hermes teams-pipeline maintain-subscriptions
46+
hermes teams-pipeline maintain-subscriptions --dry-run
47+
```
48+
49+
### Inspect recent jobs
50+
51+
```bash
52+
hermes teams-pipeline list
53+
hermes teams-pipeline list --status failed
54+
hermes teams-pipeline show <job-id>
55+
```
56+
57+
### Replay a stored job
58+
59+
```bash
60+
hermes teams-pipeline run <job-id>
61+
```
62+
63+
### Dry-run meeting artifact fetches
64+
65+
```bash
66+
hermes teams-pipeline fetch --meeting-id <meeting-id>
67+
hermes teams-pipeline fetch --join-web-url "<join-url>"
68+
```
69+
70+
## Routine Runbook
71+
72+
### After first setup
73+
74+
Run these in order:
75+
76+
```bash
77+
hermes teams-pipeline validate
78+
hermes teams-pipeline token-health --force-refresh
79+
hermes teams-pipeline subscriptions
80+
```
81+
82+
Then trigger or wait for a real meeting event and confirm:
83+
84+
```bash
85+
hermes teams-pipeline list
86+
hermes teams-pipeline show <job-id>
87+
```
88+
89+
### Daily or periodic checks
90+
91+
- run `hermes teams-pipeline maintain-subscriptions --dry-run`
92+
- inspect `hermes teams-pipeline list --status failed`
93+
- verify the Teams delivery target is still the correct chat or channel
94+
95+
### Before changing webhook URLs or delivery targets
96+
97+
- update the public notification URL or Teams target config
98+
- run `hermes teams-pipeline validate`
99+
- renew or recreate affected subscriptions
100+
- confirm new events land in the expected sink
101+
102+
## Failure Triage
103+
104+
### No jobs are being created
105+
106+
Check:
107+
- `msgraph_webhook` is enabled
108+
- the public notification URL points to `/msgraph/webhook`
109+
- the client state in the subscription matches `MSGRAPH_WEBHOOK_CLIENT_STATE`
110+
- subscriptions still exist remotely and are not expired
111+
112+
### Jobs stay in retry or fail before summarization
113+
114+
Check:
115+
- transcript permissions and availability
116+
- recording permissions and artifact availability
117+
- `ffmpeg` availability if recording fallback is enabled
118+
- Graph token health
119+
120+
### Summaries are produced but not delivered to Teams
121+
122+
Check:
123+
- `platforms.teams.enabled: true`
124+
- `delivery_mode`
125+
- `incoming_webhook_url` for webhook mode
126+
- `chat_id` or `team_id` plus `channel_id` for Graph mode
127+
- Teams auth config if Graph posting is used
128+
129+
### Duplicate or unexpected replays
130+
131+
Check:
132+
- whether you manually replayed a job with `hermes teams-pipeline run`
133+
- whether the sink record already exists for that meeting
134+
- whether you intentionally enabled a resend path in your local config
135+
136+
## Go-Live Checklist
137+
138+
- [ ] Graph credentials are present and correct
139+
- [ ] `msgraph_webhook` is enabled and reachable from the public internet
140+
- [ ] `MSGRAPH_WEBHOOK_CLIENT_STATE` is set and matches subscriptions
141+
- [ ] transcript subscription is created
142+
- [ ] recording subscription is created if STT fallback is required
143+
- [ ] `ffmpeg` is installed if recording fallback is enabled
144+
- [ ] Teams outbound delivery target is configured and verified
145+
- [ ] Notion and Linear sinks are configured only if actually needed
146+
- [ ] `hermes teams-pipeline validate` returns an OK snapshot
147+
- [ ] `hermes teams-pipeline token-health --force-refresh` succeeds
148+
- [ ] a real end-to-end meeting event has produced a stored job
149+
- [ ] at least one summary has reached the intended delivery sink
150+
151+
## Delivery-Mode Decision Guide
152+
153+
| Mode | Use when | Tradeoff |
154+
|------|----------|----------|
155+
| `incoming_webhook` | you only need simple posting into Teams | simplest setup, less control |
156+
| `graph` | you need channel or chat posting through Graph | more control, more auth and target config |
157+
158+
## Operator Worksheet
159+
160+
Fill this out before rollout:
161+
162+
| Item | Value |
163+
|------|-------|
164+
| Public notification URL | |
165+
| Graph tenant ID | |
166+
| Graph client ID | |
167+
| Webhook client state | |
168+
| Transcript resource subscription | |
169+
| Recording resource subscription | |
170+
| Teams delivery mode | |
171+
| Teams chat ID or team/channel | |
172+
| Notion database ID | |
173+
| Linear team ID | |
174+
| Store path override, if any | |
175+
| Owner for daily checks | |
176+
177+
## Change Review Worksheet
178+
179+
Use this before changing the deployment:
180+
181+
| Question | Answer |
182+
|----------|--------|
183+
| Are we changing the public webhook URL? | |
184+
| Are we rotating Graph credentials? | |
185+
| Are we changing Teams delivery mode? | |
186+
| Are we moving to a new Teams chat or channel? | |
187+
| Do subscriptions need to be recreated or renewed? | |
188+
| Do we need a fresh end-to-end verification run? | |
189+
190+
## Related Docs
191+
192+
- [Teams Meetings setup](/docs/user-guide/messaging/teams-meetings)
193+
- [Microsoft Teams bot setup](/docs/user-guide/messaging/teams)

‎website/docs/user-guide/messaging/index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -427,5 +427,6 @@ Each platform has its own toolset:
427427
- [QQBot Setup](qqbot.md)
428428
- [Yuanbao Setup](yuanbao.md)
429429
- [Microsoft Teams Setup](teams.md)
430+
- [Teams Meetings Pipeline](teams-meetings.md)
430431
- [Open WebUI + API Server](open-webui.md)
431-
- [Webhooks](webhooks.md)
432+
- [Webhooks](webhooks.md)

0 commit comments

Comments
 (0)