Kingdee Cloud Skylight Document Echo to DingTalk: A Single-Strategy Closed-Loop Notification Tutorial

What This Strategy Solves

After a business document is pushed into Kingdee Cloud Skylight, approvers need immediate feedback in DingTalk—but Kingdee does not push notifications to DingTalk on its own. In one real project, the ask on-site was simple: a salesperson kicks off a request in DingTalk, once approved it lands in Kingdee Cloud Skylight, and DingTalk must show a comment on the original approval so the originator knows it reached the ERP. This strategy closes the "Kingdee → DingTalk" acknowledgment loop. Calling a comment API looks trivial, but getting the sequence, idempotency, and field mapping right is not.

Data Flow and Field Mapping

The chain is "Kingdee Cloud Skylight → Qeasy → DingTalk". Kingdee provides the signal that a document is written (usually a query result for an effective document), Qeasy acts as the relay and orchestrator, and DingTalk uses an interface of the topapi/process/instance/comment/add family to append a comment on the original approval.

Key field mapping:

Specific tenant identifiers, tenant names, and platform identifiers from the source material are intentionally omitted from this tutorial; only business fields are retained.

Configuring in Qeasy

When we use the Qeasy data integration platform (轻易云数据集成平台) to host this strategy, configuration focuses on three places.

First, the source. The source is a no-op-style QUERY against Kingdee Cloud Skylight, used to pull back the primary key of a document that has just been written. In its metadata, business_id is marked as the number field, idCheck=true, enabling idempotency.

Second, the target. The target is DingTalk's topapi/process/instance/comment/add, type EXECUTE, method POST. The request body is a nested structure wrapped in a request object containing processInstanceId and comment as the two core fields.

Third, the middle-layer assembly. This is where things go wrong: the comment body is dynamically assembled, generally composed of "document number + business date + Kingdee acknowledgment status". We recommend keeping this assembly logic inside Qeasy's field mapping / script transformation, centralized rather than scattered across Kingdee and DingTalk—this is one of the typical patterns Qeasy customers adopt: "centralized code mapping management".

Implementation Steps

We usually schedule in three phases.

Phase 1, define the incremental anchor. Use Kingdee's document creation time as the incremental cursor, write the anchor into the Qeasy scheduler, and avoid historical data being dumped in one shot.

Phase 2, full-trigger verification. Before switching to the production schedule, fire a one-off full trigger that replays the last N days of documents, primarily to verify whether the two systems can map 1:1 on process instances; mark mismatches separately.

Phase 3, daily scheduling. The target-side crontab in the source material is */7 8-22 * * *, i.e., every 7 minutes during working hours. This cadence is dense enough during office hours but does not bother anyone at night. The Kingdee source query is event-triggered after the upstream document is persisted, following the common pattern of "incremental and full-load dual track".

Pitfall Recap

Pitfall 1: the comment API is rate-limited. DingTalk's approval comment API has a frequency ceiling; a full trigger can saturate it in an instant. The safe approach is to put a throttle on the Qeasy side, capping each tenant at N calls per second.

Pitfall 2: Kingdee internal id ≠ DingTalk process instance id. The two systems use entirely different numbering schemes. A mapping table must live on the Qeasy side, joining by the Kingdee document number (e.g., a business-prefixed code) to the DingTalk process instance. We have seen projects push this mapping into a DingTalk custom field, only to have the field edited by an approver, breaking the echo path.

Pitfall 3: garbled content in comments. If Kingdee returns a document title with special characters, DingTalk will pass them straight through to its lightweight app surfaces. The safe approach is to sanitize HTML / special characters inside Qeasy.

Pitfall 4: failed retries cause duplicate comments. DingTalk's comment API is not strongly idempotent—each retry posts a new comment. Our approach is to rely on Qeasy idCheck + document internal id for dedup; if a record already exists, retries skip it.

Pitfall 5: the approval has already finished. DingTalk does not allow appending comments to ended processes; the API returns an error. The handling is to query the process state on the Qeasy side first, and if it has ended, write only a log and skip the API call.

Applicable and Non-Applicable Scenarios

Applicable: approvals originate in DingTalk, archive in Kingdee, and require the ERP acknowledgment to be reflected back on the original flow—a lightweight collaboration scenario. Not applicable: scenarios that require passing attachment receipts, or integrating with a third-party financial system; and high-throughput scenarios where Kingdee produces very large document volumes (tens of thousands per day) unsuitable for per-document comment channels. In the latter case, route through a unified messaging bus instead.