Material Master Sync from Kingdee Cloud Xingchen to WDT: A Practical Walkthrough of an Incremental Strategy

What This Strategy Solves

Syncing material master data from a source system to a target looks simple. But if code mapping is not designed properly, the numbers on both sides drift apart within three to five months. In a real retail supply chain integration project, one customer's material codes in Kingdee Cloud Xingchen were 12-digit serial numbers, while WDT required them to carry a warehouse prefix; the brand, category, and unit systems did not fully overlap across the two platforms. The biggest problem caused by this master data inconsistency was that downstream orders, purchasing, and inventory all went off in the wrong direction. We used the Qeasy Data Integration Platform to own this work, turning material→goods into a single, isolated sync strategy. First get the "single source of truth" main line running, then talk about orders and inventory.

Data Flow and Field Mapping

Overall flow: Kingdee Cloud Xingchen V2 → Qeasy intermediate layer → WDT Enterprise. The intermediate layer only does code conversion and field alignment; it does not persist business data.

Core field mapping (only the main path is listed; extended fields are not expanded):

Target (WDT goods_push.goods_list[])	Source (Kingdee /jdy/v2/bd/material)	Mapping Type	Notes
goods_no	number	DIRECT	Material code used directly as goods number
goods_name	name	DIRECT	Material name
spec_no	number	DIRECT	Equals material code in single-spec scenarios
spec_name	model	DIRECT	Specification model
barcode	barcode → barcode_entity	TRANSFORM	Prefer barcode, fall back to barcode_entity
unit	base_unit_name	DIRECT / COLLECTION	DIRECT when systems agree, otherwise code map
brand_code	brand_id	COLLECTION	Brand must be mapped, centrally managed in Qeasy
class_code / cate_code	fetch_category_id / parent_id	DIRECT / COLLECTION	DIRECT only when category systems align

The source list API does not return description, weight, volume, price, safety stock, and similar fields. If the business needs them, the safe approach is to enable detailAPI (/jdy/v2/bd/material_detail) to fetch by id, then write back to the target. Trying to do everything in one shot easily gets out of control; the recommendation is staged delivery: main fields first, expanded fields in a second round.

How to Configure on Qeasy

Configure the source as a QUERY type GET interface /jdy/v2/bd/material, enable autoFillResponse, use number as the primary key, set idCheck to false. The incremental parameter modify_start_time is {{LAST_SYNC_TIME}}000 and modify_end_time is {{CURRENT_TIME}}000. System variables are second-level timestamps, so append three zeros to convert to milliseconds; this is a fixed requirement of the Kingdee Cloud Xingchen V2 API. Filter condition enable=1, so disabled materials never enter the pipeline.

Configure the target as an EXECUTE type POST interface goods_push, with idCheck=true and number set to id. This way existing goods auto-update and missing goods auto-insert. The request body wraps a goods_list array; each entry maps to SPU attributes.

Centralized code mapping management is the most common pattern among Qeasy customers: maintain three separate mapping tables for unit, brand, and category in a single location, and let both source and target field mappings reference the same set of code tables to avoid scattered maintenance that leads to inconsistency.

Implementation Steps

Step 1: Incremental starting point. For the first sync, do a full import by setting modify_start_time to a very early timestamp to push all currently enabled materials in one shot. Once landed, immediately switch to incremental mode: use the last successful sync time as the start point, pull every 10 minutes.

Step 2: Full sync trigger. Do not run full sync routinely. Trigger one manually when the code system is upgraded, fields are extended, or categories are rebuilt. Stop incremental tasks before re-pushing, to avoid concurrent writes from both sides.

Step 3: Scheduling frequency. Source uses */10 7-23 * * *, running every 10 minutes during the day and stopping at night to reduce load. Target does not set crontab and is triggered by upstream data. If sync issues cause backlog, first stretch the source interval to 30 minutes or even 60 minutes, wait until the pipeline digests the load, then restore; do not let the backlog snowball.

Lessons from the Trenches

Forgetting the 000 on timestamps. This is the easiest place to crash. The system variable provides a second-level timestamp, Kingdee Cloud Xingchen requires milliseconds; without the 000, the API returns nothing, the sync looks alive but ships zero data. The safe approach is to write {{LAST_SYNC_TIME}}000 directly in the source parameter and not rely on downstream assembly.
Brand and category share names but differ in meaning. A typical mistake is seeing the same name on both sides and using DIRECT. One customer had "own brand" entries on both sides with the same name but completely different ID systems, and three months later reconciliation found only 60% of material brands correct, the rest mismatched. Force a COLLECTION mapping table, and route materials that cannot be mapped to an exception queue.
Disabled materials still got synced. Without the enable=1 filter, a pile of disabled goods ended up in WDT, and downstream purchasing staff kept placing wrong orders. The source filter condition must be written, and ideally a second check is added in the intermediate layer.
Single-spec and multi-spec were not separated. Most materials are single-spec, so spec_no=number works fine; but for kits and bundles, applying this directly causes spec number conflicts. The recommendation is to first confirm whether a material carries is_multi_unit or is_asst_attr flags, and route those through a separate channel rather than mixing them in the same pipeline.
Trying to sync every field in one shot. Fields like description, weight, volume, price, and safety stock are not returned by the source list API and require detailAPI to fetch. In the first phase, we forced everything open and ran into timeouts, misaligned data, and hard troubleshooting. Split into two phases: phase one only ships main fields; phase two opens a separate detailAPI extension strategy to fill in the rest.

When to Use and When Not to Use

Use this approach when a single, clearly identified source of material master data flows one-way into a single target, the source provides a modification timestamp, and the target supports insert/update by business key. Do not use it for scenarios that require splitting master data by organization across multiple orgs or books; complex product models where the target strictly requires SPU+SKU multi-spec separation; or scenarios where the source has no change timestamp and can only be identified through full comparison.