Querying Kingdee Customers: A Single-Strategy Playbook for Pulling Customer Master Data from Kingdee Cloud
What This Strategy Solves
The first step of any supply chain integration is to align customer and material master data. In one private deployment for a manufacturing enterprise, if codes, organizations, and names diverge between the source CRM and the target ERP, every downstream document flows through carrying the same disease. The "Query Kingdee Customers" strategy does only one thing: on a schedule, it pulls customer records from Kingdee Cloud using a fixed schema and lands them in the Qeasy data integration platform, where they become the source of truth for downstream write strategies. It never touches the target system directly; it is a classic "QUERY_ONLY" precursor action.
Data Flow and Field Mapping
The source is Kingdee Cloud, accessed through its query interface executeBillQuery (POST), which retrieves customer records by field. The target is the Qeasy integration platform itself (a no-op WebAPI write), whose role is to persist data into the intermediate layer and trigger dependent downstream strategies.
Key field mapping table:
| Business Meaning | Kingdee Cloud Field | Direction | Qeasy Intermediate Field |
|---|---|---|---|
| Customer unique ID | FCUSTID | → | customer_id |
| Customer code | FNumber | → | customer_code |
| Customer name | FName | → | customer_name |
| Creating organization | FCreateOrgId.FNumber | → | create_org_code |
| Using organization | FUseOrgId.FNumber | → | use_org_code |
| Description / remark | FDescription | → | remark |
On the source side, idCheck=false and autoFillResponse=false mean this strategy does not rely on pre-assigned upstream IDs; the platform uses the FCUSTID returned by Kingdee as the authoritative key.
How to Configure in Qeasy
In the Qeasy data integration platform, four configuration points deserve attention:
- Source platform: select Kingdee Cloud, choose API
executeBillQuery, method POST, and fill the fields from the table above into the request list. Note that fields in the formOrganization.Code(for exampleFCreateOrgId.FNumber) must be written verbatim — Qeasy passes them back to Kingdee as-is. - Target platform: select Qeasy integration platform, choose the "no-op write" API, and leave the request list empty. It does not write to any third-party system; it only lands data in the intermediate store so that downstream strategies can pick it up.
- Data filtering: it is recommended to add a filter on the source side, for example
FDocumentStatus='C'(approved), to block draft customers and keep dirty data out of the CRM. - Dependencies: this strategy has
strategy_type=QUERY_ONLY. Any downstream "sync customer to CRM" write strategy should setdepends_onto point at it, ensuring the source is ready before any write happens.
In real projects, a common pattern we see among Qeasy customers is centralized management of code mappings: all cleansing logic for customer codes and organization codes is placed in the intermediate layer once, then reused by every downstream strategy so each one does not have to re-implement the mapping.
Implementation Steps
The rollout proceeds in three phases:
- Incremental starting point: on day one, run a full pull as the baseline. After it completes, record the maximum
FCUSTIDand the latest modification time inside Qeasy. - Full pull trigger: typically scheduled in the early-morning low window. The material shows the target's crontab as
23 2 * * *(02:23 daily) — this is a safety net, ensuring that even if an incremental run is missed, the next morning's run restores completeness. - Scheduling frequency: the source strategy in the material shows
*/3 7-23 * * *, polling every 3 minutes between 07:00 and 23:00 — a high-frequency incremental sweep; the target lands data at a much lower frequency. This pattern of "high-frequency polling on the source + low-frequency consolidation on the target" is the dual-track (incremental + full) approach often used by Qeasy customers: high-frequency polling captures increments, low-frequency runs guarantee completeness, and timestamps deduplicate in between.
Lessons Learned
- Do not misread "no-op write". The target is a no-op, not "write to a system." It lands data into the platform's intermediate store. On one site, an engineer treated it as a write API to the target system, and the downstream strategy never received any data.
- Organization fields need the
.FNumbersuffix.FCreateOrgIdis an internal ID;FCreateOrgId.FNumberis the business code. Get this wrong and the CRM displays garbled organization numbers. */3does not mean "every 3 hours". In crontab syntax,*/3in the hour position means every 3 hours, but in the minute position it means every 3 minutes. Polling every 3 minutes between 07:00 and 23:00 produces several hundred requests per day — watch Kingdee's QPS ceiling.- Do not sync unapproved customers. Draft customers in Kingdee have
FDocumentStatusnot equal to 'C'. Without a filter, the CRM ends up with rows like "New Customer 2024-01-01" — obvious test data. - The cost of
idCheck=false. Disabling ID check on the source means the platform accepts whatever Kingdee returns. If someone manually changes an FCUSTID association in Kingdee, the platform accepts it as-is. We recommend adding a diff script in Qeasy that compares against the previous pull and raises an alert whenever an FCUSTID no longer matches its code.
Applicable and Non-Applicable Scenarios
Applicable: Kingdee is the authoritative source of customer master data; downstream CRM / marketing / e-commerce systems need to align customers by organization and code; frequent drift checks on downstream codes are required.
Not applicable: scenarios where customer records originate in the CRM and flow back to Kingdee (use a "CRM → Kingdee" write strategy instead); and very large customer bases (millions) where latency matters and polling every 3 minutes against the Kingdee interface becomes a bottleneck — in those cases, switch to database log capture or change notifications.