Practical Tutorial for DingTalk Message Detail Query and Bot Notification Strategy
What Problem Does This Strategy Solve?
In one manufacturing supply-chain integration running in a public cloud, operations staff needed timely visibility into failed document-processing tasks. A summary saying only that a strategy had failed still required users to inspect each system. By the time the business reported the issue, a backlog could already have grown.
This strategy connects message-detail retrieval with a DingTalk robot notification. It queries exception details by strategy name or business-document number, then sends the strategy name, tenant or business context, document number, response time, problem summary, and response content into a notification flow. The value is not merely sending a message; it creates a traceable, assignable, and reviewable incident loop. Qeasy is used to keep both stages in one manageable integration flow rather than scattering them across scripts.
Data Flow and Field Mapping (Source → Middleware → Target)
The strategy chains two WebAPI actions. The first action queries message details for a recent 300-second window and can filter by strategy name or record number. The second action transforms the query results into a robot message. Secret-bearing values should be stored through the platform credential or secure-variable mechanism and must not be pasted directly into a strategy configuration.
| Source field | Meaning | Target field | Configuration guidance |
|---|---|---|---|
| strategy_name | Synchronization strategy name | name | Pass through; preserve the original value when empty |
| lessee_name | Tenant or business context name | lessee_name | Use an approved display name or masked value |
| number | Business document number | number | Treat as the primary troubleshooting index |
| response_at | Response time | response_at | Preserve the source format and normalize the time zone separately |
| problem | Exception summary | problem | Pass through; truncate only when necessary and retain a detail reference |
| response_content | Response or exception detail | response_content | Check for sensitive data and sanitize it before notification |
| strategy_id | Strategy identifier | Internal correlation field | Use for internal tracing, not ordinary group display |
The middleware layer fixes the query window, validates required parameters, combines query results, and prepares context for the notification template. The target message should be organized as “strategy—document—time—problem—detail,” allowing recipients to assess impact quickly.
How to Configure It in Qeasy
We use the Qeasy data integration platform to connect retrieval and notification, rather than leaving the logic in separate scripts.
First, configure the query API in the source connection. Use POST, pass strategy_name or number as the main lookup value, and enable duplicate checking. Set recentSeconds to 300 by default. The ids field is suitable for querying several explicitly known numbers; do not treat it as a conflicting condition together with the strategy name. Map strategy_name, strategy_id, number, response_at, problem, response_content, and other response fields into the response model.
Second, configure the robot detail execution API in the target connection. Map name from strategy_name, lessee_name from the tenant or business context, and map number, response_at, problem, and response content individually. Generate the message body with a template. Keep the full response in a collapsed or lower-priority section so that a single incident does not create an excessively long message.
Third, enable credential references and sensitive-field protection. The robot access credential should be injected by an authorized administrator; the configuration should contain only the variable reference. If the response contains account, internal-address, or other business-sensitive information, sanitize it in the middleware layer.
A common field-governance pattern is to maintain strategy names and document numbers in a centralized mapping area. Another common approach is to send a header-level alert first and include the full response only when it is needed. These patterns reduce template drift and make follow-up troubleshooting easier.
Implementation Steps (Incremental Start / Full Trigger / Schedule)
1. Incremental start. Start with a fixed recent 300-second query window so newly generated errors enter the notification chain. If the historical range is unknown at initial launch, begin with a smaller window and expand it only after confirming the platform retention behavior.
2. Full trigger. “Full” here should not mean resending the entire historical message set. It should be a one-time query over a specified time range with a batch or quantity limit. Before backfilling, validate number format, time boundaries, and the deduplication key to prevent duplicate alerts.
3. Schedule frequency. The supplied business window is 9:00–21:00, with both query and notification running every five minutes on offset schedules. Do not make both stages start at the same minute: reserve execution time for the query and allow time for notification retries.
4. Go-live validation. Test four scenarios: successful retrieval, no matching details, timeout, and sensitive content. Use a clearly identifiable test strategy or test document before enabling production notifications. After launch, monitor message delay, duplication rate, API response, and failure queues. A dual-track mode of incremental plus full backfill can be used when history must be recovered, but the full task must remain bounded by a time window and batch limit.
Lessons from the Field
- Do not trust number validation absolutely. A typical error is relying only on front-end validation, without handling spaces, case differences, and special characters. Keep the original value and generate a normalized value for comparison.
- Keep the query window aligned with the schedule. If a task runs every five minutes but queries only a fixed 60-second period, boundary-period incidents can be missed. Query the recent 300 seconds and allow a small time overlap to improve completeness.
- Do not publish raw responses without inspection. The response may contain internal information. Add sensitive-field checks, length limits, and truncation guidance in the middleware layer.
- Prevent duplicate alerts during retries. The robot may have received the message even though the platform timed out before confirming it. A retry can therefore send it again. Use a deduplication key composed of strategy identifier, document number, response time, and a normalized problem summary.
- Avoid identical phase scheduling. If notification starts before the query finishes, records returned near the boundary can be missed. Offset the two schedules and add a dependency or an appropriate waiting window.
Suitable and Unsuitable Scenarios
This strategy suits public-cloud environments where integration exceptions, interface responses, and business numbers must be delivered quickly to operations or business teams, especially for on-call monitoring and rapid troubleshooting. It is not a replacement for a business-data archive, complex approval workflow, or large-volume detail transport. High-frequency log analysis belongs in a logging platform; use this strategy when you need an alert trigger, a follow-up notification, and a traceable incident loop.