Customer-Material Mapping Query Sync: Incremental Practice from Kingdee Cloud to a WMS

What This Strategy Solves

In a real supply-chain integration project for a pharmaceutical distributor, the first pain point was not transactional documents but master data — the customer-material mapping table. On the ERP side, every customer is mapped to a set of materials, price groups, and authorization flags, while on the WMS side this mapping was maintained manually for a long time. After three months the two systems drifted apart and picking errors surged. On the surface, "material master sync" looks like a simple data migration; the real difficulty is incremental maintenance of the mapping. This strategy pulls the customer-material mapping from the ERP incrementally and makes it the authoritative source for the downstream WMS.

Data Flow and Field Mapping

The flow is unidirectional: Kingdee Cloud (source) → Qeasy data integration platform (intermediate layer) → WMS (target). The intermediate layer does not persist an entity table; it only handles four responsibilities — filtering, mapping, version control, and downstream invocation.

The source side uses Kingdee Cloud's executeBillQuery API to pull a bill view under incremental conditions. Key request fields:

After the intermediate layer receives the raw fields, typical mapping logic includes: converting the customer code from FCustomerId.Fnumber to the WMS internal customer key; centrally managing organization code mapping on Qeasy via a unified lookup table; keeping only the C (approved) status.

How to Configure on Qeasy

On the Qeasy data integration platform, the source action of this strategy is configured as a "query action" and the target action as a "WebAPI write" (POST). Key points:

• Source action: API is executeBillQuery, method POST, incremental field bound to FModifyDate, advancing from the last maximum modification time.
• Filter conditions: FDocumentStatus = C and FSaleOrgId is not empty; prune invalid records at the source.
• Intermediate layer: no entity persistence, only field mapping and lightweight validation. A common pattern among Qeasy customers is centralized code mapping management, where customer, organization, and material codes are maintained in one unified table, so that a change happens in one place instead of many.
• Target action: a placeholder "write no-op" for now; replace with the actual WMS customer-material mapping write API in production.
• idCheck: enabled, to prevent duplicate writes.

Implementation Steps

We typically split this strategy into three phases:

1. First full-volume trigger: on go-live day, set the FModifyDate watermark to the system initialization time and run a one-shot full pull to push all historical mappings down. This step must be triggered manually and must not be placed into the scheduled job.
2. Switch to incremental scheduling: after the full pull completes and reconciliation passes, reset the watermark to the maximum modification time of this run and enable the cron-based incremental scheduling. Note that the source materials show two cadences, */10 * * * * (every 10 minutes) and 1 1 1 1 1 (weekly), and in real projects we typically use the every-10-minutes cadence — the exact choice depends on how much latency the business can tolerate.
3. Steady-state operations: run a daily reconciliation between ERP and WMS on the customer-material count and raise an alert if the divergence exceeds a threshold.

The dual-track pattern of incremental plus full volume is common among Qeasy customers: full volume as a safety net, incremental for timeliness — the two cannot replace each other.

Pitfalls and Lessons

1. Status field not filtered properly. The first full pull included drafts and in-review records, producing ghost mappings on the WMS. The safe approach is to add the FDocumentStatus = C filter at the source rather than relying on downstream deduplication.
2. Incremental watermark lost. After the schedule is restarted or the strategy is republished, if the FModifyDate watermark variable is not persisted, you risk duplicate or missed pulls. On Qeasy, the maximum modification time is stored in a built-in state variable that survives across schedule restarts.
3. No centralized organization mapping. Every integration point maintained its own organization lookup; changing one meant editing six or seven places — a typical crash pattern. Keep code mappings centralized and maintain them in only one place.
4. Customer code carries a prefix. The source FCustomerId.Fnumber has a business prefix (e.g. C001.01), while the target only needs the pure code C001. Strip the prefix during mapping; otherwise the two sides look identical but differ by one character, which is extremely painful to debug.
5. WMS side is not idempotent. Re-pushing the same mapping creates duplicate records on the WMS. Always enable idCheck on the target action, or use a customer+material composite key as a uniqueness constraint.

Applicable and Non-applicable Scenarios

Applicable: ERP and WMS need to share customer-material mappings; mappings change frequently and cannot be maintained manually; permission isolation is required by sales organization and customer.

Not applicable: mappings rarely change and are maintained only on the WMS side; the relationship is one-to-many and the business does not require real-time consistency; the upstream ERP does not expose an incremental pull interface such as executeBillQuery and only supports full table dumps.