Skip to content

Commit e086d78

Browse files
mtojekmtojek
authored
docs: enable Microsoft Teams Notifications (coder#14781)
1 parent c127d90 commit e086d78

File tree

2 files changed

+168
-1
lines changed

2 files changed

+168
-1
lines changed

‎docs/admin/notifications/teams.md

+160
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Microsoft Teams Notifications
2+
3+
[Microsoft Teams](https://www.microsoft.com/en-us/microsoft-teams) is a widely
4+
used collaboration platform, and with Coder's integration, you can enable
5+
automated notifications directly within Teams using workflows and
6+
[Adaptive Cards](https://adaptivecards.io/)
7+
8+
Administrators can configure Coder to send notifications via an incoming webhook
9+
endpoint. These notifications appear as messages in Teams chats, either with the
10+
Flow Bot or a specified user/service account.
11+
12+
## Requirements
13+
14+
Before setting up Microsoft Teams notifications, ensure that you have the
15+
following:
16+
17+
- Administrator access to the Teams platform
18+
- Coder platform with notifications enabled
19+
20+
## Build Teams Workflow
21+
22+
The process of setting up a Teams workflow consists of three key steps:
23+
24+
1. Configure the Webhook Trigger.
25+
26+
Begin by configuring the trigger: **"When a Teams webhook request is
27+
received"**.
28+
29+
Ensure the trigger access level is set to **"Anyone"**.
30+
31+
2. Setup the JSON Parsing Action.
32+
33+
Next, add the **"Parse JSON"** action, linking the content to the **"Body"**
34+
of the received webhook request. Use the following schema to parse the
35+
notification payload:
36+
37+
```json
38+
{
39+
"type": "object",
40+
"properties": {
41+
"_version": {
42+
"type": "string"
43+
},
44+
"payload": {
45+
"type": "object",
46+
"properties": {
47+
"_version": {
48+
"type": "string"
49+
},
50+
"user_email": {
51+
"type": "string"
52+
},
53+
"actions": {
54+
"type": "array",
55+
"items": {
56+
"type": "object",
57+
"properties": {
58+
"label": {
59+
"type": "string"
60+
},
61+
"url": {
62+
"type": "string"
63+
}
64+
},
65+
"required": ["label", "url"]
66+
}
67+
}
68+
}
69+
},
70+
"title": {
71+
"type": "string"
72+
},
73+
"body": {
74+
"type": "string"
75+
}
76+
}
77+
}
78+
```
79+
80+
This action parses the notification's title, body, and the recipient's email
81+
address.
82+
83+
3. Configure the Adaptive Card Action.
84+
85+
Finally, set up the **"Post Adaptive Card in a chat or channel"** action
86+
with the following recommended settings:
87+
88+
**Post as**: Flow Bot
89+
90+
**Post in**: Chat with Flow Bot
91+
92+
**Recipient**: `user_email`
93+
94+
Use the following _Adaptive Card_ template:
95+
96+
```json
97+
{
98+
"$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
99+
"type": "AdaptiveCard",
100+
"version": "1.0",
101+
"body": [
102+
{
103+
"type": "Image",
104+
"url": "https://coder.com/coder-logo-horizontal.png",
105+
"height": "40px",
106+
"altText": "Coder",
107+
"horizontalAlignment": "center"
108+
},
109+
{
110+
"type": "TextBlock",
111+
"text": "**@{replace(body('Parse_JSON')?['title'], '"', '\"')}**"
112+
},
113+
{
114+
"type": "TextBlock",
115+
"text": "@{replace(body('Parse_JSON')?['body'], '"', '\"')}",
116+
"wrap": true
117+
},
118+
{
119+
"type": "ActionSet",
120+
"actions": [@{replace(replace(join(body('Parse_JSON')?['payload']?['actions'], ','), '{', '{"type": "Action.OpenUrl",'), '"label"', '"title"')}]
121+
}
122+
]
123+
}
124+
```
125+
126+
_Notice_: The Coder `actions` format differs from the `ActionSet` schema, so
127+
its properties need to be modified: include `Action.OpenUrl` type, rename
128+
`label` to `title`. Unfortunately, there is no straightforward solution for
129+
`for-each` pattern.
130+
131+
Feel free to customize the payload to modify the logo, notification title,
132+
or body content to suit your needs.
133+
134+
## Enable Webhook Integration
135+
136+
To enable webhook integration in Coder, ensure the "notifications" experiment is
137+
activated by running the following command:
138+
139+
```bash
140+
export CODER_EXPERIMENTS=notifications
141+
```
142+
143+
Then, define the POST webhook endpoint created by your Teams workflow:
144+
145+
```bash
146+
export CODER_NOTIFICATIONS_WEBHOOK_ENDPOINT=https://prod-16.eastus.logic.azure.com:443/workflows/f8fbe3e8211e4b638...`
147+
```
148+
149+
Finally, go to the **Notification Settings** in Coder and switch the notifier to
150+
**Webhook**.
151+
152+
## Limitations
153+
154+
1. **Public Webhook Trigger**: The Teams webhook trigger must be open to the
155+
public (**"Anyone"** can send the payload). It's recommended to keep the
156+
endpoint secret and apply additional authorization layers to protect against
157+
unauthorized access.
158+
159+
2. **Markdown Support in Adaptive Cards**: Note that Adaptive Cards support a
160+
[limited set of Markdown tags](https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format?tabs=adaptive-md%2Cdesktop%2Cconnector-html).

‎docs/manifest.json

+8-1
Original file line numberDiff line numberDiff line change
@@ -516,7 +516,14 @@
516516
"title": "Notifications",
517517
"description": "Learn how to configure notifications",
518518
"path": "./admin/notifications.md",
519-
"icon_path": "./images/icons/info.svg"
519+
"icon_path": "./images/icons/info.svg",
520+
"children": [
521+
{
522+
"title": "Microsoft Teams Notifications",
523+
"description": "Learn how to setup Microsoft Teams notifications",
524+
"path": "./admin/notifications/teams.md"
525+
}
526+
]
520527
}
521528
]
522529
},

0 commit comments

Comments
 (0)