Material Master Sync to WMS: A Practical Guide to Pushing Kingdee Cloud Items to Wangdian Tong

What This Pattern Solves

Pushing material master data from an ERP (here, Kingdee Cloud) to a WMS/ecom backbone (here, Wangdian Tong) looks like a single table copy, but if the code mapping, units, or forbidden flags are even slightly off, the numbers drift apart within three months. On customer sites, the most common complaint is: "The warehouse says the material does not exist, but it does in ERP," or "Ecom is still selling a material that ERP disabled months ago." We break this into a single sync strategy on Qeasy, the lightweight data integration platform. The goal is straightforward — keep item code, unit, spec, and forbidden status aligned between the two systems in the long run.

Data Flow and Field Mapping

The flow is one-way: B (source) = Kingdee Cloud → A (target) = Wangdian Tong Enterprise Qimen. The source pulls material masters through executeBillQuery; the target writes through wdt.goods.push under the goods node.

The table below shows the field mapping we configure in Qeasy. Only the key fields are listed; in real projects we typically add 5–8 extended fields (barcode, dimensions, shelf life, etc.).

One key design choice: keep the code mapping centralized in the middle layer of Qeasy instead of scattering it across source or target. We have seen too many projects hardcode mapping in SQL, then have to rebuild everything when the source system changes.

How to Configure It on Qeasy

Open the Qeasy data integration platform, create a new "Data Integration Strategy," and configure as follows:

1. Source connection: select Kingdee Cloud, interface executeBillQuery, HTTP POST, primary key FMATERIALID, and check "idempotency check by code."
2. Target connection: select Wangdian Tong Enterprise Qimen, interface wdt.goods.push, request body root goods_list, with the skus array underneath (typical header-body structure, covered in pitfalls later).
3. Field mapping: drag the source fields to the middle layer one by one, then map them to the target. Fields where the two ends "have it but with different semantics" — unit, forbidden flag, tax rate — must go through a converter, not pass-through.
4. Scheduling: strategy-level cron */5 8-22 * * * (every 5 minutes during working hours). Target platform access cron 3-59/5 8-22 * * *, offset by 3 minutes, to avoid contention.

Implementation Steps

We usually proceed in three phases rather than jumping straight into a full load.

Phase 1: Baseline (full load, manual intervention)

• Before the first sync, manually trigger a "full" run in Qeasy to push all non-forbidden materials from the source table to the target at once.
• Disable auto-scheduling during the full-load phase and run a 1:1 manual check afterward.
• Check indicators: code 1:1, unit semantics, forbidden status, multi-units (base, inventory, sales).

Phase 2: Incremental start line (last-modified timestamp as the start line)

• After the full-load check passes, set the "incremental start" in Qeasy to that moment's timestamp, then pull only new and changed records.
• Once this timestamp is set, do not change it lightly — changing it causes duplicate pushes or missed pushes.

Phase 3: Steady-state scheduling (incremental + full dual track)

• Run incremental every 5 minutes during working hours.
• Run a full reconciliation once a week (recommended Saturday early morning) as a safety net.
• On the Qeasy dashboard, run both "time-window pull" and "primary-key dedup" in parallel — any error on either side surfaces within 5 minutes.

Pitfall Recap

1. Code as primary key, internal ID as primary key? Using FMATERIALID as the primary key looks safest, but downstream documents refer to FNumber externally. If upstream changes FMATERIALID (e.g., cross-org migration), the entire chain breaks. The safe practice is dual keys: FMATERIALID for dedup, FNumber for business reconciliation.

2. Multi-units flattened to one. In ERP, a material has base, inventory, and sales units; the WMS goods node accepts only one main unit. A typical error is writing the inventory unit directly, so quantities are multiplied by 1,000×1,000 at outbound. The safe practice is to add a "unit converter" in the middle layer, make explicit which unit is the master, and document the conversion factor in notes.

3. Forbidden flag not transmitted. When a material is disabled upstream, if FForbiddenStatus (or the equivalent) is not pushed, the target keeps selling it. The WMS/ecom side is most sensitive to "disabled" — this must be its own mapping line, never buried in remarks.

4. Header and body pushed together, too many rows truncated. wdt.goods.push accepts only a limited number of skus per call; the excess is silently truncated by the server without an error. The safe practice is to slice the payload in Qeasy's batching stage, 200 per batch, with automatic retry on failure.

5. Cross-org materials overwriting each other. The source has "group materials + org materials" as two sets; the target has only one. A typical error is pushing the org material, overwriting the group material. The safe practice is to add an FUseOrg filter in the source query, and record "which org pushed which code" in the middle layer.

Where This Fits and Where It Doesn't

Fits: single legal entity or clearly bounded organizational material master pushes; scenarios where coding rules are clear, unit semantics are unified, and change frequency is controllable.

Does not fit: complex scenarios with multi-org shared + multi-version materials (group, org, store) coexisting, or scenarios requiring two-way sync (any edit on either side flows back). The latter usually needs two independent strategies plus a reconciliation table — not a single one-way push.