Skip to content

Commit d290222

Browse files
pijiang3pijiang3
committed
add best practices docs
1 parent 39dd756 commit d290222

6 files changed

Lines changed: 510 additions & 2 deletions

File tree

‎docs.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,14 @@
283283
]
284284
}
285285
]
286+
},
287+
{
288+
"group": "最佳实践",
289+
"icon": "lightbulb",
290+
"pages": [
291+
"zh/on-call/practices/dynamic-dispatch-with-external-data",
292+
"zh/on-call/practices/wecom-bot-mention"
293+
]
286294
}
287295
]
288296
},
@@ -1225,6 +1233,14 @@
12251233
]
12261234
}
12271235
]
1236+
},
1237+
{
1238+
"group": "Best Practices",
1239+
"icon": "lightbulb",
1240+
"pages": [
1241+
"en/on-call/practices/dynamic-dispatch-with-external-data",
1242+
"en/on-call/practices/wecom-bot-mention"
1243+
]
12281244
}
12291245
]
12301246
},

‎en/on-call/integration/alert-integration/alert-sources/aws-eventbridge.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
---
22
title: "AWS EventBridge Alert Events"
33
description: "Sync AWS EventBridge alert events to Flashduty via webhook for automated alert noise reduction"
4-
date: "2024-08-20T10:00:00+08:00"
5-
url: "https://docs.flashcat.cloud/en/flashduty/aws-eventbridge-integration-guide"
64
---
75

86
Sync AWS EventBridge alert events to Flashduty via webhook for automated alert noise reduction.

‎en/on-call/practices/dynamic-dispatch-with-external-data.mdx‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: "Dynamic dispatch with external data"
3+
description: "Automatically route alerts to the right responders using label mapping and dynamic dispatch, without frequently updating escalation rules"
4+
---
5+
6+
## Why dynamic dispatch
7+
8+
In enterprise operations, you often manage thousands of monitored objects (hosts, services, databases, etc.), and the responsible responders change frequently as the organization evolves. Maintaining separate escalation rules for each object is both costly and error-prone.
9+
10+
**Dynamic dispatch** solves this problem: you configure a single escalation rule as a "template", and the system automatically replaces the notification targets based on specific labels carried by the alert. This way, whenever responders change, you only need to update the label data — no need to modify the escalation rule itself.
11+
12+
## How it works
13+
14+
The core flow of dynamic dispatch consists of three steps:
15+
16+
<Steps>
17+
<Step title="Alert enters the channel">
18+
After being ingested through an integration, the alert enters a channel and matches a configured escalation rule.
19+
</Step>
20+
21+
<Step title="System reads dynamic labels">
22+
The system detects that the alert carries a specific label (e.g., `layer_person_reset_0_emails=bob@corp.com`) and automatically replaces the notification targets in level 1 of the escalation rule with Bob.
23+
</Step>
24+
25+
<Step title="Dispatch based on the updated rule">
26+
The system dispatches notifications according to the updated escalation rule. After dispatch completes, these control labels are automatically removed to keep the alert details page clean.
27+
</Step>
28+
</Steps>
29+
30+
<Warning>
31+
Dynamic dispatch does not work independently — it depends on an existing escalation rule in the channel. You need to configure an escalation rule in advance as a "template". Dynamic labels only replace the notification targets (responders, teams, or chat bot) within the rule; other settings (notification methods, timeout, escalation levels, etc.) remain unchanged.
32+
33+
For the full label parameter reference, see [Dynamic dispatch](/en/on-call/advanced/dynamic-notifications).
34+
</Warning>
35+
36+
## How to generate dynamic labels
37+
38+
The key to dynamic dispatch is ensuring alerts carry the correct labels. The following two approaches can achieve this — choose whichever fits your situation.
39+
40+
### Approach 1: Add labels directly in the monitoring system
41+
42+
If you have configuration access to your monitoring system and it supports custom labels (e.g., Prometheus, Nightingale, Zabbix), simply add the label to your alert rules:
43+
44+
- **Label key**: `layer_person_reset_0_emails`
45+
- **Label value**: `bob@corp.com`
46+
47+
<Tip>
48+
This approach requires minimal configuration and works well when responders rarely change. However, you'll need to update the alert rules in your monitoring system whenever personnel changes occur.
49+
</Tip>
50+
51+
### Approach 2: Auto-generate via label mapping
52+
53+
If you cannot modify the monitoring configuration, or prefer to centrally manage the "monitored object → responder" mapping (e.g., synced from a CMDB, configuration platform, or any external data source), use the **label mapping** feature.
54+
55+
This approach creates a mapping table that automatically "translates" existing basic labels in alerts (such as `host`) into dynamic dispatch labels, without modifying the monitoring system.
56+
57+
<Steps>
58+
<Step title="Prepare mapping data">
59+
Compile the mapping between monitored objects and responders. For small datasets, you can enter data manually on the page; for large datasets, prepare a CSV file.
60+
61+
<Note>
62+
The target column name in the CSV must use the dynamic dispatch parameter name (e.g., `layer_person_reset_0_emails`).
63+
</Note>
64+
65+
| host (source label) | layer_person_reset_0_emails (target label) |
66+
| :--- | :--- |
67+
| web-server-01 | bob@corp.com |
68+
| db-server-02 | alice@corp.com |
69+
70+
You can source this data from anywhere — CMDB, configuration management platforms, operations systems, or Excel spreadsheets — as long as it follows the format above.
71+
</Step>
72+
73+
<Step title="Create a mapping table">
74+
Import the data into the system to create a reusable mapping "dictionary".
75+
76+
1. Go to **Integration Center → Label Mapping**.
77+
2. Click **Create Label Mapping**.
78+
3. Enter data:
79+
- **Upload file**: Upload a CSV file for bulk operations.
80+
- **Manual input**: Add entries one by one on the page for small-scale maintenance.
81+
4. After saving, you'll have a mapping table ready to be referenced by integrations.
82+
83+
<Tip>
84+
To keep the mapping in sync with external systems in real time, use the [Flashduty API](https://developer.flashcat.cloud/flashduty/enrichment/mapping-data-upsert) to update the mapping table automatically, achieving fully unattended configuration sync.
85+
</Tip>
86+
</Step>
87+
88+
<Step title="Configure label enhancement rules">
89+
Reference the mapping table in your alert integration so the system automatically populates dynamic labels during alert ingestion.
90+
91+
1. Go to **Integration Center → Label Enhancement**.
92+
2. Find your target alert integration (e.g., Zabbix integration) and open its details.
93+
3. Select the **Label Enhancement** tab, and set the action type to **Label Mapping**.
94+
4. **Select mapping table**: Choose the mapping table created in the previous step.
95+
5. **Configure mapping**:
96+
- **Source label**: Select `host`.
97+
- **Target label**: Select `layer_person_reset_0_emails`.
98+
99+
Once configured, the system will automatically look up the `host` value in the mapping table during alert ingestion and generate the corresponding dynamic dispatch label.
100+
</Step>
101+
102+
<Step title="Configure a template escalation rule">
103+
Configure an escalation rule in the target channel. The notification targets in this rule can be set to any value (e.g., a default team) — it serves only as a "template". During actual dispatch, the notification targets will be replaced by the dynamic labels.
104+
105+
Other settings in the rule (notification methods, timeout escalation, etc.) will function normally.
106+
107+
For detailed configuration, see [Escalation rules](/en/on-call/channel/escalation-rule).
108+
</Step>
109+
</Steps>
110+
111+
## Verify the result
112+
113+
After completing the configuration, trigger a test alert to verify:
114+
115+
1. **Check the dispatch process**: In **Incident Details → Timeline**, you'll see a log entry similar to: "Based on dynamic labels, responders have been reset to bob@corp.com".
116+
2. **Check alert labels**: On the alert details page, you will **not** see `layer_person_reset_xxx` labels — these control directives are automatically cleaned up after taking effect.
117+
118+
## Further reading
119+
120+
<CardGroup cols={2}>
121+
<Card title="Dynamic dispatch" icon="shuffle" href="/en/on-call/advanced/dynamic-notifications">
122+
View the full dynamic label parameter reference and push examples
123+
</Card>
124+
<Card title="Label enhancement" icon="tags" href="/en/on-call/integration/alert-integration/label-enhancement">
125+
Learn how to auto-generate new labels based on existing ones
126+
</Card>
127+
</CardGroup>

‎en/on-call/practices/wecom-bot-mention.mdx‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: "WeCom bot @ mention for responders"
3+
description: "Configure WeCom group chat bots to @ mention responders when pushing alert notifications, ensuring critical alerts are not overlooked"
4+
---
5+
6+
## Why @ mention
7+
8+
In busy WeCom group chats, responders can easily miss alert notifications. By enabling **@ mention**, the bot automatically @ mentions the corresponding responders when pushing incident notifications, ensuring they are alerted immediately.
9+
10+
Flashduty supports two approaches for WeCom bot @ mention. Here's how they compare:
11+
12+
| Comparison | Default (phone number matching) | Mapping table (user_id matching) |
13+
| :--- | :--- | :--- |
14+
| **Matching logic** | Matches WeCom members by the phone number bound to their Flashduty account | Matches via email-to-WeCom user_id mapping table |
15+
| **@ mention position** | Displayed separately at the bottom of the notification | Displayed inline within the notification content |
16+
| **Maintenance effort** | No extra maintenance — just keep phone numbers consistent | Requires maintaining the email-to-user_id mapping table |
17+
| **Best for** | Phone numbers are consistent between Flashduty and WeCom | Phone numbers differ, or you prefer inline @ mentions within the notification |
18+
19+
## Approach 1: Default (phone number matching)
20+
21+
This is the simplest approach with no extra configuration required. The system automatically matches WeCom members using the phone number bound to their Flashduty account.
22+
23+
### Prerequisites
24+
25+
- The phone number bound in Flashduty must **exactly match** the phone number on the WeCom account
26+
27+
### Configuration steps
28+
29+
<Steps>
30+
<Step title="Verify phone number consistency">
31+
Ensure Flashduty member phone numbers match their WeCom account phone numbers. You can view and edit member phone numbers in **Platform Management → Member Management**.
32+
</Step>
33+
34+
<Step title="Enable @ mention">
35+
Go to the target channel's **Escalation Rules**, find the WeCom bot notification channel, expand **Advanced Configuration**, and enable the **@ Mention** toggle.
36+
</Step>
37+
</Steps>
38+
39+
<Tip>
40+
With this approach, if a member's phone number differs between the two platforms, the @ mention will not work. Always verify phone number consistency first.
41+
</Tip>
42+
43+
## Approach 2: Mapping table (user_id matching)
44+
45+
If member phone numbers differ between the two platforms, or you prefer @ mentions to appear inline within the notification content, use the mapping table approach.
46+
47+
This approach requires you to maintain a mapping table between Flashduty member emails and WeCom user_ids.
48+
49+
### Prerequisites
50+
51+
- You have obtained the WeCom user_ids for your members (available from the WeCom admin console or API)
52+
53+
### Configuration steps
54+
55+
<Steps>
56+
<Step title="Obtain WeCom user_ids">
57+
Log in to the [WeCom admin console](https://work.weixin.qq.com/wework_admin/frame#contacts), go to **Contacts**, click on a member to view their details, and find the **Account** field — this is their user_id.
58+
59+
You can also obtain user_ids in bulk via the WeCom API.
60+
</Step>
61+
62+
<Step title="Create a mapping table">
63+
1. Go to Flashduty **Platform Management → Mapping Table Management**.
64+
2. Click **Create Mapping Table**, and select the **WeCom** type.
65+
3. Enter the Flashduty member emails and their corresponding WeCom user_ids:
66+
67+
| email | wecom_userid |
68+
| :--- | :--- |
69+
| bob@corp.com | bob_wecom |
70+
| alice@corp.com | alice_wecom |
71+
72+
</Step>
73+
74+
<Step title="Configure escalation rule and link the mapping table">
75+
Go to the target channel's **Escalation Rules**, find the WeCom bot notification channel:
76+
77+
1. Expand **Advanced Configuration** and enable the **@ Mention** toggle.
78+
2. In the **User Info Mapping Table** dropdown, select the mapping table created in the previous step.
79+
</Step>
80+
</Steps>
81+
82+
<Warning>
83+
You are responsible for maintaining the mapping table. When team members change, update the mapping table promptly — otherwise new members will not be @ mentioned.
84+
</Warning>
85+
86+
## Verify the result
87+
88+
After completing the configuration, trigger a test alert to verify that @ mention works:
89+
90+
1. Confirm the target channel has a WeCom bot configured as a group chat notification channel.
91+
2. Trigger a test alert and check the notification message in the WeCom group chat.
92+
3. Verify that the responders are correctly @ mentioned.
93+
94+
If @ mention is not working, refer to the following troubleshooting checklist:
95+
96+
<AccordionGroup>
97+
<Accordion title="Default approach: @ mention not working">
98+
- Confirm the **@ Mention** toggle is enabled
99+
- Confirm the member's phone number in Flashduty **exactly matches** their WeCom account phone number (including country code)
100+
- Confirm the member is in the group chat where the bot is configured
101+
</Accordion>
102+
103+
<Accordion title="Mapping table approach: @ mention not working">
104+
- Confirm the **@ Mention** toggle is enabled and the correct **User Info Mapping Table** is selected
105+
- Confirm the email-to-user_id mappings in the table are correct
106+
- Confirm the WeCom user_ids are accurate (verify in the WeCom admin console under Contacts)
107+
- Confirm the member is in the group chat where the bot is configured
108+
</Accordion>
109+
</AccordionGroup>
110+
111+
## Further reading
112+
113+
<CardGroup cols={2}>
114+
<Card title="Notification channel configuration" icon="bell" href="/en/on-call/configuration/notifications">
115+
Learn about all bot types, configuration methods, and advanced options
116+
</Card>
117+
<Card title="Escalation rules" icon="route" href="/en/on-call/channel/escalation-rule">
118+
Learn about notification methods and group chat configuration in escalation rules
119+
</Card>
120+
</CardGroup>

0 commit comments

Comments
 (0)