Practical Tutorial: Kingdee Cloud Customer Master Data Query Sync Strategy on Qeasy Data Integration Platform
What This Strategy Solves (Scenario & Value)
In a real retail integration project, we ran into a very typical pain point: the source CRM system keeps generating new customers and customer changes, and the target ERP needs to sync these customer master records in as the foundation for subsequent orders, receipts, and membership points. On the surface it looks like just a "customer master data sync," but if you only do a coarse-grained full copy, problems quickly surface—code mappings scattered everywhere, the wrong incremental starting point causing missed records, and inconsistent multi-organization versions. After we adopted the Qeasy data integration platform, we converged the strategy into a single "Kingdee Customer Query" line: the source uses Kingdee Cloud's executeBillQuery API for incremental conditional queries, and the target lands the data into the Qeasy middle layer as input for subsequent write strategies. The overall value is turning "customer master data" synchronization in the master data domain into an independently traceable, replayable, and observable strategy.
Data Flow & Field Mapping (Source → Middle Layer → Target)
The data flow is unidirectional: Kingdee Cloud (source) → Qeasy middle layer (target). The source uses the executeBillQuery API to pull customer records by incremental condition, and the target writes them first into the Qeasy middle layer, from which subsequent strategies distribute the data to downstream systems.
Key field mapping table (source to middle layer):
| Business Meaning | Source Kingdee Field | Middle Layer Field | Notes |
|---|---|---|---|
| Customer unique ID | FCUSTID | id | Primary key, idCheck=true, used for idempotent deduplication |
| Customer code | FNumber | number | Business code, key for cross-system reconciliation |
| Customer name | FName | name | Used for display and matching |
| Create organization | FCreateOrgId.FNumber | create_org | Required in multi-org scenarios |
| Use organization | FUseOrgId.FNumber | use_org | Pay attention when it differs from the create org |
| Remarks/description | FDescription | description | Optional but recommended |
A few points worth noting: first, FCUSTID is numeric in Kingdee, but in cross-system sync we recommend treating it uniformly as a string to avoid being misidentified downstream; second, the organization fields returned by Kingdee are "organization codes," not organization primary keys. When landing in the Qeasy middle layer we also preserve the code semantics, and the actual name conversion is handled by a separate field-mapping script.
How to Configure on Qeasy
Source-side (Kingdee Cloud) core configuration: api=executeBillQuery, method=POST, type=QUERY, number=FName, id=FCUSTID, idCheck=true. Define these 6 fields as input parameters in the request body, then pass in the incremental conditions at runtime.
Target-side (datahub) core configuration: api=write no-op, method=POST, type=EXECUTE. This step first "catches" the data into the middle layer, and the actual write into the business system is handled by a subsequent strategy. One common pattern we see across Qeasy customers is landing code mappings and header/body logic into different strategies in phases, rather than stuffing everything into a single write action.
For the incremental field, we recommend using "last modified time" as the incremental cursor, rather than polling through a customer code dictionary. The incremental starting point is generally set to the day before go-live to avoid a historical data explosion.
Implementation Steps
We usually break this strategy into three phases: Phase 1 is "incremental starting point alignment"—manually trigger one initialization run in Qeasy to pull all pre-go-live customer records as a baseline; Phase 2 is "full trigger," using crontab 23 2 2 2 2 (2 AM on the 2nd of each month) to do a monthly full validation, ensuring the middle layer is consistent with the source; Phase 3 is "daily incremental scheduling," configured as */2 * * * * to poll every 2 minutes and pull customer records changed in the last few minutes.
On scheduling frequency, 2 minutes is an empirical value—customer master data isn't as high-frequency as orders, but it needs to be more real-time than daily batches. 2 minutes lets the business side perceive customer changes without maxing out the Kingdee API. If the customer volume is small, 5 minutes is enough; if the volume is large and real-time requirements are high, you can compress it to 1 minute, but you need to monitor the source-side API QPS.
Pitfall Retrospective
Pitfall 1: Wrong incremental cursor. The classic mistake is using "creation time" as the incremental condition, which misses modification records of existing customers. The safe approach is to use "last modified time" and verify on the Kingdee side whether this field can be updated pointlessly by certain background tasks.
Pitfall 2: Organization field semantics confusion. Some customers have the same "create organization" and "use organization," but across legal entities they can be completely different. When landing into the middle layer, we insist on keeping both fields rather than merging them; downstream consumers pick based on business rules.
Pitfall 3: Misuse of idCheck. The source-side idCheck=true uses FCUSTID for idempotency judgment—that's fine. But if someone mistakenly changes it to use FNumber for idempotency, and FNumber allows manual editing, you'll end up with "the same logical customer being identified as two records." Once this happens, three months later the numbers on both sides won't match, and troubleshooting will be excruciating.
Pitfall 4: Balancing scheduling frequency with API rate limits. A 2-minute polling cycle itself isn't a problem, but if multiple strategies run simultaneously, the source-side QPS stacks up. We recommend configuring independent connection pools or rate-limit thresholds for each strategy in Qeasy.
Pitfall 5: Misunderstanding the "write no-op" in the middle layer. The target-side write no-op is not a bug—it's by design. Its purpose is to first land the data into datahub, then trigger the subsequent distribution strategy. If someone sees this API name and assumes the configuration is wrong, switching it to a real write API will cause duplicate writes.
Applicable & Non-Applicable Scenarios
Applicable: the "source → middle layer" link in bidirectional customer master data sync, where replayable and traceable master data synchronization is needed. Not applicable: scenarios requiring second-level real-time customer change notifications (those should go through message queues); nor cross-ledger customer merge scenarios, which require a separate cleansing strategy.