Customer Master Data Query Sync from Kingdee Cloud to Qeasy: A Practical Strategy Walkthrough

What This Strategy Solves

Pushing customer master data from Kingdee Cloud to downstream systems looks like a simple "query + write" job. But in retail and distribution scenarios with multiple organizations and encoding schemes, the moment customer codes lose a single source of truth on the integration layer, every downstream order, receivable, and loyalty record goes out of alignment. In a recent project, we used the Qeasy data integration platform to periodically pull customer master records from Kingdee Cloud and land them on the platform side, forming a stable "baseline customer pool" for downstream order, inventory, and reconciliation strategies.

Data Flow and Field Mapping

The overall flow is: Kingdee Cloud (source) → Qeasy integration platform (target / middle layer), one-way inbound, no write-back to the source system.

The source uses executeBillQuery (POST, QUERY type), with FNumber as the business key and FCUSTID as the internal key. The platform side enables idCheck to prevent duplicate creation when the same code is pulled multiple times.

How to Configure on Qeasy

In the Qeasy strategy editor, first create the source system connection (pointing to the Kingdee Cloud open platform), then the target system connection (pointing to the platform's own datahub write interface). A common pitfall at customer sites is "the connection works but the wrong tenant is selected" — multi-organization customers usually have multiple books in Kingdee Cloud at the same time, so the target book ID must be locked in the connection configuration.

For the source, choose executeBillQuery as the pull action, and add FNumber, FName, FCUSTID, FCreateOrgId.FNumber, FUseOrgId.FNumber, FDescription and other fields into the request body. For the target, use batchSave (POST, EXECUTE type) with id as the primary key. Two patterns are common among Qeasy customers: first, centralized encoding mapping management — in the Qeasy mapping table, only direct Kingdee → platform mappings are kept, with no business rules mixed in, so they can be reused for future cross-system integration. Second, staged header and line data — this strategy only syncs header master data; contacts, addresses, and bank accounts under the customer go into a separate strategy, so each strategy stays fast and easy to troubleshoot.

Implementation Steps

Step 1: Align the incremental starting point. Customer environments often already have a batch of historical customers, so you cannot start with a full overwrite right away. The recommended approach is to first pull an incremental set with a creation time after a certain timestamp from Kingdee as the baseline for the initial run, and then run a full backfill later.

Step 2: Trigger the full backfill. Once the incremental run is stable, manually trigger a full backfill to fill in any customers that fell outside the incremental window. Schedule the full action during business off-peak hours, such as 2:00–5:00 AM.

Step 3: Scheduling frequency. The crontab from the source material is */20 * * * *, meaning one run every 20 minutes. For low-change data such as customer master records, this frequency is actually a bit aggressive. A safer approach is to run every 20 minutes for one week and observe the change volume from the source. If the daily increment is only a few dozen records, you can relax it to hourly or even every 4 hours, reducing source-side pressure and making failure retries easier.

Step 4: Result verification. After each run, compare the total record count from the source BD_Customer table with the deduplicated count by the platform-side id key, and trigger an alert if the difference exceeds a threshold (for example, 0.5%).

Field-Tested Lessons

1. Organization field type mismatch. The source FCreateOrgId is a reference-type field with the path FCreateOrgId.FNumber. Many engineers simply write FCreateOrgId, and the API returns null, so after the run, every organization column is empty. The safe approach is to strictly follow the reference path defined in the source metadata.
2. idCheck accidentally disabled. For data like customer master records where same names with different codes are allowed, if idCheck is not enabled, customers with the same name will be created repeatedly, and after a few months you will end up with seven or eight rows of "Beijing XX Trading." idCheck must stay enabled.
3. Mixing null and required values. On the target side, FCreateOrgId and FUseOrgId are marked is_required=false, but on the source they are required; conversely, FDescription is optional on the source and optional on the target. For this kind of "asymmetric required-ness" between the two sides, the platform mapping must explicitly allow "source null → target null allowed," and should not hard-code a default value.
4. Over-aggressive scheduling causes source throttling. With a */20 frequency, when bulk calls are made across many organizations, the Kingdee open platform triggers throttling, which manifests as the second half of the requests returning 429. The safe approach is to start with a low frequency and gradually increase it.
5. No separation between "customer query" and "customer change." The strategy type in this material is QUERY_ONLY, which only performs a full snapshot query. Real incremental changes should go through another strategy (with timestamp filtering). When the two strategies share one target table, you must perform an upsert by FNumber before writing, otherwise you will end up with dirty data caused by "query full + incremental change" fighting each other.

Applicable and Non-Applicable Scenarios

Applicable: Multi-organization groups that need a unified view of customer master data; downstream order, reconciliation, and loyalty systems that need a stable middle layer unaffected by frequent source interface changes; low customer master change frequency with minute-level latency being acceptable.

Not applicable: Customer master records that change frequently (added, deleted, or updated) within a single day and require second-level consistency; or cases where the source and target are simply not network-reachable to each other and cannot use a direct platform connection, in which case the network layer must be addressed first.