Qeasy Cloud
Get Started

Supplier Account Query Sync: A Practical Walkthrough from Dingtalk to Qeasy Middle Layer

· 陈洁琳· Integration Solutions· 26 views· 4 min read
Kingdee CloudDingTalk供应商主数据钉钉集成轻易云Incremental Sync供应链集成策略教程

What This Strategy Solves (Scenario & Value)

In one retail engagement, supplier account records are maintained in a Dingtalk low-code form because it's convenient for the business side. However, downstream systems such as Kingdee Cosmic and the SRM reports all rely on the same master data. What we need here is a "Supplier Account Query" strategy: pull the latest account data from Dingtalk on a schedule and land it in the Qeasy data integration platform's middle layer as the unified source for subsequent distribution. It does not write directly to business systems; instead, it stabilizes the data inside the integration platform first, so other strategies can consume it.

Data Flow & Field Mapping

The overall flow is Dingtalk → Qeasy Integration Platform. The source side is a query interface, and the target side is an empty-operation write (used for triggering/placeholder; the actual landing in the middle layer is handled by the platform itself).

DimensionSource (Dingtalk)Middle Layer (Qeasy datahub)Notes
Platform TypeDingtalk low-code formQeasy integration platformPrivate deployment
API ActionQUERY (pull instance list)EXECUTE (empty write placeholder)Used to trigger / leave a trace
HTTP MethodPOSTPOSTBoth sides use POST
PaginationpageNumber / pageSize=100—Default 100 per page
Primary KeyformInstId0 (placeholder)Source side idCheck=true
Business Numbertitle0 (placeholder)Used as the business document number
Incremental FieldmodifiedToTimeGMT—Controls the time window
Schedule20 1-3 * * * (20th minute of every hour)1 1 1 1 1 (placeholder)Source side drives

There is one design detail worth expanding on: the target-side api is literally "Empty Write Operation," with empty arrays for both request and response, and number and id set to 0. This is not a misconfiguration — it's a typical "target-side placeholder" pattern. The strategy's real write target is the Qeasy integration platform's middle layer, and the source-side form instances simply land as they are.

How to Configure It on Qeasy

Step 1: Register two platform connections inside Qeasy: Dingtalk (code: Dingtalk) as the source and Qeasy Integration Platform (code: datahub) as the target. In a private deployment, fill in each platform's service endpoint and credentials respectively.

Step 2: Create a new strategy and select the "Supplier Account Query" template. For the source side, pick WebAPI, set effect to QUERY, paste the source api path, and map the request fields one by one: appType and formUuid as constants, pageNumber and pageSize as built-in pagination variables, and leave modifiedToTimeGMT for the incremental script to inject. For the target side, set effect to EXECUTE, leave the api as the "Empty Write Operation" identifier, and keep request/response empty.

Step 3: Attach the script. The incremental time window is the key to this strategy — the script reads the last successful run time, converts it into a GMT string, and writes it into modifiedToTimeGMT. After each run, Qeasy writes the current time back to a cursor table, implementing rolling pull by modification time.

Implementation Steps

Phase 1: Incremental Starting Point Run an initial full backfill first: set modifiedToTimeGMT to a very early timestamp inside Qeasy to trigger the first run, and wait until the middle-layer data volume stabilizes.

Phase 2: Full Trigger Then manually run a full pull and verify that the middle-layer record count matches the Dingtalk form instance count. The goal here is not to go live, but to establish the mental baseline that "both sides agree."

Phase 3: Schedule Frequency The source-side cron is set to 20 1-3 * * *, i.e., the 20th minute of every hour, to avoid peak load on the hour. A pattern commonly seen among Qeasy customers is the "dual track of incremental and full": incrementals run hourly, full pulls run once at night, so any drift on one side can be caught by the other side's overwrite logic.

For the first week after going live, manually sample 20 records every day to verify; from the second week onward, switch to exception-driven alerts.

Pitfalls & Lessons Learned

Pitfall 1: Hard-coding pagination parameters as constants. pageNumber must use Qeasy's built-in pagination variable. If you hard-code 0, you only get the first page. This is a classic place to fall over — a typical mistake is the first full pull returning only 100 records.

Pitfall 2: idCheck not enabled. Source-side idCheck=true is the key to idempotency. Disable it, and you will see duplicate formInstId entries in the Qeasy middle layer, which will trip up any downstream SRM reconciliation.

Pitfall 3: No timezone conversion on the incremental time window. The Dingtalk field is GMT, but if the script fills it in with local time directly, it will not pull new records. The safe approach is to compute everything in UTC inside the script.

Pitfall 4: Treating the target side as a real write and configuring fields for it. This strategy's target side is an empty placeholder — spending effort configuring request/response fields is wasted.

Pitfall 5: Underestimating the value of centralized code mapping. Supplier codes are strings on Dingtalk but may need a prefix appended on the Kingdee side. A common Qeasy customer pattern is to centralize this kind of mapping in Qeasy's "Code Mapping" module rather than scattering it across every strategy's script.

Applicable vs. Not Applicable Scenarios

Applicable: The source is a Dingtalk low-code form, maintenance frequency is high, account-class master data needs to be stabilized in the middle layer before distribution, and the real-time requirement is at the hourly level.

Not applicable: Scenarios requiring minute-level real-time sync (those should use event/message triggers, not cron pulls); and field-level bidirectional sync — this strategy only handles one-way backfill.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-kingdee-cloud-dingtalk-9365-n6c8cb3e5-c90e4622

Comments