Material Master Data Sync in Practice: A Deep Dive into One Strategy from Kingdee Cloud to the Business System

What This Strategy Solves

Pushing material master data from an ERP to a downstream business system looks like "just moving some numbers," but anyone who has run it in production knows: if the codes are not aligned, the incremental anchor is wrong, or the schedule timing is off, reconciliation breaks within three months. On a real customer site we worked on, the requirement was clear — once a material is created and approved in the ERP, the business system must see an accurate product record as soon as possible, and inventory quantities must not be mixed into the master data push. The strategy below exists for exactly that: it only syncs material attributes, leaves inventory to a dedicated inventory strategy, maps fields one-to-one, and runs on a schedule.

Data Flow and Field Mapping

The data flow is unidirectional: Kingdee Cloud → the business system. There is no intermediate landing for transformation; the mapping is done directly on the Qeasy integration platform via source read and target write configurations.

One detail is easy to miss: FBaseUnitId is a nested object on the Kingdee side, so the source request must use FBaseUnitId.FNumber for pre-extraction. The target then receives the flattened FBaseUnitId_FNumber and maps it to unit.

How to Configure It on Qeasy

On the Qeasy data integration platform, configuring this strategy is straightforward. The typical steps are:

1. Source data source: pick Kingdee Cloud, use the executeBillQuery interface, set FormId to BD_MATERIAL, tick the fields listed in the table above, and use the platform variables {{PAGINATION_PAGE_SIZE}} and {{PAGINATION_START_ROW}} for pagination.
2. Filter condition: set FilterString to FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and FDocumentStatus='C' and FUseOrgId.FNumber=100. This combination determines which materials are eligible: must be approved, must belong to the specified use organization, and must be incremental by approval date.
3. Target data source: pick the business system, use /Kingdee/EditMaterial, POST, and bind target fields to source fields using {{}} expressions.
4. Centralized code-mapping management: although this strategy has no cross-strategy lookups, we typically recommend maintaining all enum values (product type, machine type, sales mode, etc.) in a single code-mapping table so adding new enums only requires editing the table, not the strategy.
5. idCheck: enable on both sides — the platform checks whether the target productId already exists; if yes, update; if not, create.

Implementation Steps

A phased rollout is the safe approach we use on customer sites:

1. Full trigger (initialization): on first go-live, push {{LAST_SYNC_TIME}} back to a very early timestamp and run one full pull to backfill the target. Do this during off-peak hours, then reconcile the material code counts between the two systems.
2. Incremental anchor: once the full run is successful, anchor LAST_SYNC_TIME to the completion timestamp, and from then on push only records with FApproveDate at or after that point.
3. Schedule frequency: source */10 7-22 * * * (every 10 minutes, 7 a.m. to 10 p.m.), target */10 * * * * (every 10 minutes, all day). A subtle point: source pulls first, target writes later; leave a 2–3 minute window between them to avoid the source still pulling while the target has already started writing the previous batch.
4. Pilot and rollback: one week before cutover, set the strategy to "trial run" so it only pulls without writing, then manually sample and verify; when switching to live writes, retain 7 days of replayable logs.

Post-Mortem: Common Pitfalls

• Pitfall 1: treating approval date as modification date. FApproveDate is the approval date, not the modification date. If a material is un-approved and re-approved, the approval date refreshes, which is usually fine; but field changes made while un-approved will not be pushed. The safe approach is to add FModifiedDate as a fallback in the filter, or require the business side to re-approve after any field change.
• Pitfall 2: forgetting to pre-extract nested objects. If FBaseUnitId is mapped directly, the target will receive an object like {"FNumber":"kg"} rather than the string "kg". Always write the source request as FBaseUnitId.FNumber.
• Pitfall 3: stuffing inventory quantity into the material strategy. To save effort, some engineers map the inventory field too, but the material has just been approved while inventory hasn't moved yet, so the business system shows a wrong number. In this strategy inventoryQty is intentionally left null — inventory must be handled by a dedicated inventory strategy.
• Pitfall 4: misaligned custom-field enums. The Kingdee BOS custom fields F_CY_* and F_WDZN__CY_* carry manually maintained enums, while the target business system has its own enum set. Misalignment causes "empty display" or "write failure." Build an enum alignment table before go-live; fixing it after the fact is painful.
• Pitfall 5: reversed schedule timing. Both sides using */10 without a window leads to dirty data — one batch still being pulled while the previous is half-written. We typically suggest running source during 7-22 and target around the clock, which creates a natural gap; or offsetting the two schedules by 3 minutes.

When to Use This and When Not To

Use it when: the ERP is the master data source and the business system is a downstream consumer; material master data is synced one-way; filtering by organization and approval status is needed; fields are mostly direct mappings with no complex lookups.

Do not use it when: inventory quantities must be synced together (use a dedicated inventory strategy); source-side enum conversion or cross-strategy lookups are required (this strategy has no _findCollection / _mongoQuery — complex logic needs a separate strategy); bi-directional sync is required (this strategy is one-way only).