Material Master Data Sync in Practice: Deep Breakdown of the Kingdee Cloud "Old Material Code" Backfill Strategy

What This Strategy Solves

When a retail enterprise unified ERP and WMS master data, a typical problem surfaced: historical material codes were scattered across multiple legacy systems. Kingdee Cloud only kept the new code FNumber, while the WMS legacy data and customer historical documents still queried by the old code FOldNumber. If you push only the new code across, within three months the two sides' inventory and reports will not reconcile. That is exactly what the "old material code backfill" strategy addresses: pull FOldNumber out of the source system, land it in the intermediate layer of the Qeasy Data Integration Platform, then write it back to the target system via batchSave, so the code mapping is centralized and traceable in one pass.

Data Flow and Field Mapping

The whole link is a one-way "query → intermediate layer → writeback" three-stage flow. The source is Kingdee Cloud, the intermediate layer is the Qeasy platform, and the target is written back to Kingdee Cloud through Qeasy.

Source side (QUERY direction, API executeBillQuery, POST) returns the following fields: FMATERIALID (entity primary key, required), FNumber (code, required), FName (name, required), FSpecification (specification model, optional), FOldNumber (old material code, optional), FBARCODE (barcode). Among them, FMATERIALID and FNumber are the key fields for subsequent matching and writeback.

Target side (EXECUTE direction, API batchSave, POST) accepts fields: FName, FNumber, FDescription, FCreateOrgId (default 100), FUseOrgId (default 100), and SubHeadEntity (basic header) and other extension fields. The most critical step in this strategy is to map the source-side FOldNumber to the target-side FDescription or a custom extension field, completing the centralized management of code mapping.

How to Configure on Qeasy

In the strategy canvas of the Qeasy Data Integration Platform, the typical configuration points for this strategy are as follows:

Source data source: create a Kingdee Cloud connection, select executeBillQuery as the query API, write the filter condition as FOldNumber IS NOT NULL, and only pull records that need backfilling to avoid full-table scans dragging down the source system.
Intermediate layer landing: directly land the three columns FMATERIALID, FNumber, FOldNumber returned from the source into the Qeasy intermediate table. This step is the foundation for subsequent centralized code mapping management — land the fields as-is without conversion.
Target writeback: use batchSave for batch writeback, with FNumber as the unique key (idCheck=true). When writing, concatenate FOldNumber into FDescription or a custom extension field, ensuring the old code is queryable somewhere.
Scheduling strategy: source cron */10 * * * * (query for increments every 10 minutes), target cron 23 2 1 1 1 (trigger batch writeback at 02:23 every Monday), forming a "high-frequency probing + low-frequency writeback" dual-track rhythm of incremental and full loads.

Implementation Steps

Stage 1: Incremental starting point. First pull records whose FMATERIALID is greater than the maximum value of the last sync as the incremental starting point; simultaneously store a last_sync_id in Qeasy's state store, and continue from it next time.

Stage 2: Full-load trigger. Run a "full-load compensation" task in Qeasy to pull all historical FOldNumber records and land them in the intermediate table. Never run this step during production hours — the safe approach is to schedule it for late Sunday night.

Stage 3: Scheduling frequency. The source probes for increments every 10 minutes; the target batch-writes back once a week. After writeback completes, trigger a reconciliation to compare the count of FNumber in Kingdee Cloud against FOldNumber in the Qeasy intermediate table, and alert if the difference exceeds the threshold.

Pitfall Retrospective

Pitfall 1: Full select * takes down the source system. In a real project, an engineer started with select * and Kingdee Cloud's response timed out immediately. The safe approach is pagination + required-field filtering, pulling only rows where FOldNumber is not null.

Pitfall 2: Mixing FMATERIALID and FNumber as primary keys. A classic mistake is matching FMATERIALID with FNumber during writeback, causing the same code to be written multiple times. The safe approach is to use FMATERIALID as the unique key when pulling from the source, and also use FMATERIALID as the primary key of the Qeasy intermediate table.

Pitfall 3: FOldNumber overwriting FNumber. This is the most fatal class of error: treating the old code as the new code and writing it back, polluting customer master data. Code mapping must go through Qeasy's centralized intermediate-layer management; source fields and target fields must be strictly one-to-one mapped, and "lazy merging" is not allowed.

Pitfall 4: Cron schedule does not avoid business peaks. Once target-side batchSave runs during the day, it conflicts with Kingdee Cloud's daily transactions and causes severe table locking. We later moved it to 23 2 1 1 1 (02:23 every Monday), and it became much more stable.

Pitfall 5: No reconciliation loop. Without reconciliation after completion, it took three months to discover the two sides' numbers did not match. The safe approach is to perform an FNumber ↔ FOldNumber difference comparison after each writeback, and alert immediately if the difference exceeds the threshold.

Applicable and Non-Applicable Scenarios

Applicable: supply-chain master data sync scenarios where the ERP and WMS/OMS code systems are not unified and historical code mapping needs to be backfilled; projects where the source is Kingdee Cloud and the target needs to retain old code traceability.

Not applicable: scenarios where the source system has no FOldNumber field, or where the business side explicitly allows only new codes; as well as real-time inventory-type sync that requires real-time joint queries rather than batch writeback.