Customer Master Data Incremental Update: A Practical Guide to Syncing Kingdee Cloud Cosmic to Sihua MES via updateCustomer

What This Strategy Solves

A retail enterprise runs Kingdee Cloud Cosmic as its ERP and Sihua Smart Manufacturing MES on the shop floor. Once a customer record is renamed, has its code changed, or has contact details updated, relying on manual edits in MES means the customer numbers in the two systems drift apart within a couple of months. Downstream order delivery and shipping checks start failing.

The Kingdee Customer to MES Customer _Update strategy does exactly one thing: it pushes audited customer changes from Kingdee to MES via the updateCustomer API, performing a positional update rather than an insert. In the source material this strategy is paired with a create strategy: create handles "first time," this one handles "change." Together they close the full customer master-data loop. On the Qeasy data integration platform, we keep the customer update path as a separate strategy so new customers and modified ones never mix in a single flow, which would otherwise break idempotency.

Data Flow and Field Mapping

The flow is straightforward: Kingdee Cloud Cosmic (BD_Customer) → Qeasy integration hub → Sihua MES (Customer). The source is pulled via executeBillQuery and the target is updated through /api/updateCustomer.

Key field mapping:

Note that customerNo is bound to FCUSTID, not FNumber. The reason is that even if the customer code is renamed in Kingdee, as long as the internal ID is stable, MES can still locate the same record. Otherwise, the moment someone edits the code, the row becomes orphaned.

How to Configure on Qeasy

Inside Qeasy's strategy editor we keep all encoding mappings in a single place. This particular strategy does not use _findCollection; it relies entirely on direct mapping and constant fallbacks, which actually makes it more stable. Configuration highlights:

1. Source side: protocol WebAPI, effect = QUERY, endpoint executeBillQuery, primary key FCUSTID, document number FNumber, idCheck off (this is a query semantics, no target-side existence check needed).
2. Target side: protocol WebAPI, effect = EXECUTE, endpoint /api/updateCustomer, idCheck must be true. This is the heart of the strategy. Only when idCheck is on will the platform verify whether the target record exists by customerNo and update only if found, skipping or alerting otherwise — no duplicate creates.
3. Field mapping: bind fields per the table above. For blank fields use empty-string constants, not null; some MES APIs are sensitive to null.
4. Incremental variable: the FilterString should be FApproveDate>='{{LAST_SYNC_TIME|datetime}}', the standard Qeasy placeholder that auto-resumes from the last successful run.

Implementation Steps

We usually roll this out in three phases, which is the most reliable approach in our customer projects:

Phase 1, incremental starting point. At first go-live, run the create strategy (P3-089 in the source material) once for a full load so all existing customers exist in MES. This is the foundation; skipping it and running update directly will flood the log with "target not found" alerts.

Phase 2, enable this strategy. Once create is solid, hook the update strategy into the scheduler. Trigger it manually first and verify that one changed customer row updates correctly in MES, then promote it to a schedule.

Phase 3, scheduling frequency. Per the source material's * 7-22 * * *, run at every hour from 07:00 to 22:00. Customer master data does not require second-level sync; hourly is sufficient. Stopping after 22:00 leaves a window for MES to run its own nightly batch. This "header incremental + daytime high-frequency" pattern is one of the most common deployments we see on Qeasy.

Pitfall Retrospective

Pitfall 1: Mixing create and update. Early on we tried to combine insert and modify into a single strategy with if-else branches. After three months in production, half the logs were dirty: the MES create API rejects duplicate customerNo, while update cannot overwrite a brand-new customer. Splitting them into two strategies — create uses createCustomer, update uses updateCustomer — fixed it.

Pitfall 2: Forgetting to enable idCheck. When idCheck on the target side is left off, the platform blindly calls updateCustomer. Some MES implementations interpret this as "create if not exists," which produced mystery records in MES. The safe default is idCheck = true so the platform validates first.

Pitfall 3: Using FNumber as the lookup key. Some teams set customerNo = {{FNumber}} for convenience. The day a customer code is renamed in Kingdee, that record becomes unreachable. Always use a business-stable ID field such as FCUSTID as the lookup key.

Pitfall 4: Running 24x7. One customer asked for "as real-time as possible" and we went to 5-minute intervals. It conflicted with MES nightly jobs and tripped rate limits. Switching to hourly during working hours satisfied timeliness while avoiding the MES peak.

Pitfall 5: Leaving fields blank. In the source material, contactPhone and addressDetail do have source counterparts (FADDRESS, FTEL) but are mapped to empty strings for now. Three months later the business asked, "Why are phones blank in MES?" The lesson: short-term laziness becomes long-term debt. Use _function with case when to provide a fallback, or just finish the mapping.

When to Use and When Not to

Use when: Kingdee is the master-data source for customers, changes need to flow into a manufacturing MES that exposes an ID-based update endpoint, and a create strategy already exists as the upstream step.

Do not use when: this is a first-time master-data load (use create instead); MES lacks ID-based lookup and can only do full overwrite; or changes arrive at sub-second frequency, in which case a message queue is the right answer, not a scheduled sync.