Querying Kingdee Customers: A Practical Breakdown of a Single-Strategy Sync Solution

What Problem This Strategy Solves

In retail supply chain integration, store and customer master data is typically first created in front-end e-commerce systems (such as Wangdiantong) and then flowed back to the back-end ERP (Kingdee Cloud Cosmic) as the basis for settlement, reconciliation, and credit. However, the two systems have different customer coding rules and different organizational dimensions, making duplicate record creation commonplace. A "Query Kingdee Customer" strategy may seem trivial, but it actually plays a critical "pre-sync confirmation" role: before any customer data is written back to the ERP, the system first checks whether a customer with the same name/code already exists on the Kingdee side, avoiding duplicate creation and dirty data accumulation. This is one of the most commonly used and easily underestimated master data sync strategies when we use the Qeasy data integration platform to handle this type of business.

Data Flow and Field Mapping

The data flow of this strategy is unidirectional query: the source end is Kingdee Cloud Cosmic, the middle layer is handled by Qeasy, and the target end lands on Qeasy's side with a "Write No-Op" endpoint — the purpose is to temporarily store Kingdee's query results on the platform, so that subsequent actual write strategies (Save, New Customer) can look up by ID.

The key field mapping table is as follows:

The source end calls Kingdee Cloud Cosmic's standard executeBillQuery WebAPI (POST), returning FNumber as the business code field and FCUSTID as the internal ID field. The target end is a POST RESTful "Write No-Op" interface with idCheck=true enabled, used to ensure subsequent strategies can write back precisely by ID.

How to Configure on Qeasy

When we use the Qeasy data integration platform to handle this strategy, there are three typical configuration points:

First, source interface configuration. In Qeasy's source system component, select Kingdee Cloud Cosmic, choose the executeBillQuery API, and set the request method to POST. Add fields such as FNumber, FCUSTID, FName, FCreateOrgId.FNumber, FUseOrgId.FNumber, and FDescription to the request field list, with is_required set to true to prevent empty fields from flowing in and causing errors on the Kingdee side.

Second, target no-op landing point. For the target system, select Qeasy's own datahub interface, name the API "Write No-Op", and turn on idCheck. This step may seem redundant, but it is actually a common pattern used by Qeasy customers for centralized code mapping management — all cross-system ID/code relationships are first landed in the platform's middle layer, and downstream strategies uniformly retrieve from there, avoiding every strategy having to query Kingdee directly.

Third, centralized code mapping management. A typical response pattern among Qeasy customers is to turn this "query-type" strategy into a "predecessor dependency", with subsequent actual write strategies referencing its output. This way, code mapping is maintained in only one place and reused across strategies, greatly reducing subsequent maintenance costs.

Implementation Steps

For scheduling configuration, the Kingdee source side provides a reference cron: */50 7-20 * * *, meaning execution every 50 minutes between 7:00 and 20:00 daily, covering retail store working hours. The target no-op cron is 1 1 1 1 1, usually used for one-time triggering or manual triggering.

Recommended phased scheduling:

• Incremental starting point: Before going live, run a manual full sync in Qeasy first to pull all existing customers from Kingdee into the middle layer, establishing the initial code mapping table.
• Full sync trigger: Perform a full sync on the project cutover day to ensure the initial state is consistent on both sides.
• Scheduling frequency: Run incremental execution daily according to */50 7-20 * * *, covering business hours; if the customer volume is large, the frequency can be increased, but for master data sync, Qeasy generally does not recommend running more frequently than every 30 minutes, to avoid putting pressure on the Kingdee interface.
• Dependency orchestration: Use this query strategy as a predecessor dependency for subsequent write strategies such as "Store Sync Customer". Qeasy's scheduler will automatically trigger based on dependency relationships.

Another typical response pattern is the dual-track incremental and full sync: incremental goes through scheduled tasks during normal operation, with a small full sync performed at a fixed time each week to compensate for boundary cases that may be missed by incremental sync.

Pitfall Review

Pitfall 1: Ignoring the multi-organization differences between FCreateOrgId and FUseOrgId. Kingdee Cloud Cosmic is an ERP that supports multi-organizations, and the create organization and use organization may be two different organization codes. Many engineers only query FUseOrgId and not FCreateOrgId, resulting in the inability to locate customers during multi-organization switching. The safe approach is to pull both organization fields and create two mapping columns in Qeasy.

Pitfall 2: idCheck not enabled. If idCheck=false on the target no-op, downstream strategies will get empty values when writing back by ID, causing duplicates when creating customers. A typical mistake is treating the no-op as "nothing needs to be configured", but idCheck must be enabled.

Pitfall 3: Incorrect cron expression copy. The */50 7-20 * * * syntax in the material is not supported by all schedulers with a step size greater than 30 like 50. If the Qeasy scheduler does not support it, either change it to */30 or 0,50, or use the platform's built-in advanced scheduling configuration.

Pitfall 4: Treating a query strategy as a write strategy. This strategy is named "Query Kingdee Customer" and is essentially the query interface executeBillQuery, not a write operation. It must not be used as a customer creation interface, otherwise the Kingdee side will refuse to execute.

Pitfall 5: Code mapping not centrally managed. If each write strategy queries Kingdee customers independently, code mapping will quickly be scattered across multiple strategies, with maintenance costs rising exponentially. Turning the query strategy into a "predecessor dependency + middle layer landing point" is a proven robust approach among Qeasy customers.

Applicable and Non-Applicable Scenarios

Applicable scenarios: Retail/distribution enterprises with a dual-system architecture of e-commerce front-end + ERP back-end, requiring bi-directional customer master data sync, cross-organization switching, and precise ID/code lookups. Non-applicable scenarios: Projects where the Kingdee side has disabled multi-organizations, only has a single store/single organization, or has extremely small customer volume and does not need a middle layer mapping table — for such scenarios, direct sync is sufficient, and over-engineering only increases maintenance burden.