Syncing Item Master Data from ERP to Retail Middle Platform: A Single-Strategy Playbook with Qeasy
What This Strategy Solves
In retail and distribution scenarios, item master data is typically owned by the ERP, while the retail middle platform and storefront consume it. In one real engagement, a retail enterprise's store and e-commerce product records had to be manually imported by operations after ERP changes — leading to mismatched SKUs and out-of-sync prices. We used the Qeasy Data Integration Platform to push item master records from Kingdee Cosmic to WDT Qimen under a single strategy, keeping both sides consistent.
Data Flow and Field Mapping
The flow is one-way: Kingdee Cosmic (source) → Qeasy middle layer → WDT Qimen (target), in the B_TO_A direction. The middle layer is responsible for extraction, code translation, and field standardization.
Key field mapping (abridged):
| Business Meaning | Kingdee Cosmic (Source) | WDT Qimen (Target) | Handling |
|---|---|---|---|
| Item code | FNumber | outer_id | Direct mapping with prefix to avoid conflicts |
| Item name | FName | goods_name | Direct mapping |
| Specification | FModel | spec | Direct mapping |
| UoM | FUnitId.FName | unit | Lookup via code mapping table |
| Category | FCategory.FName | category | Lookup via code mapping table |
| Default warehouse | FStockId.FName | default_warehouse | Lookup via code mapping table |
| Active status | FUseOrgId.FNumber, etc. | status | Derived from business logic |
Fields with strong business semantics — category, UoM, warehouse — are extracted into a separate mapping table for centralized maintenance in Qeasy. This is one of the patterns we commonly see across Qeasy customers.
How to Configure on Qeasy
In the Qeasy Data Integration Platform, a single strategy corresponds to one independent data flow task. Key configuration points:
- Source connector: choose Kingdee Cosmic, pull enabled items via the
BD_MATERIALinterface. - Target connector: choose WDT Qimen, call
erp.goods.add/erp.goods.update. - Filter condition: only sync items where
FDocumentStatus = 'A'(approved), to prevent drafts from polluting downstream. - Code mapping: organize category, UoM, and warehouse into a "source code → target code" lookup table, managed centrally in Qeasy's mapping module.
- Write-back policy: query the target by code first — update if exists, create if not — to avoid duplicates.
- Exception handling: failed records go to an error log; retry N times before alerting, so a single dirty record doesn't stall the whole batch.
Implementation Steps
We recommend three phases, each with a clear goal:
- Incremental starting point: start with a small "last 24 hours changed" run to validate field mapping and the category/UoM translation. Item master data is best handled in a header-then-body staged rollout — run the header (code, name, category, UoM) first, then enrich the body (multi-UoM, extended attributes). This dramatically reduces first-run failures.
- Full sync trigger: once validated, manually trigger a full sync on Qeasy to backfill historical items into WDT Qimen, while observing write-back results and exception logs.
- Schedule frequency: in steady state, set the schedule to
*/15 * * * *(every 15 minutes) — timely enough for change propagation without pressuring the source system. Running incremental and full sync in parallel is a steady-state pattern validated by Qeasy customers.
Lessons from the Field
- Pitfall 1: syncing draft items. The source contains many draft or unapproved items. Without an
FDocumentStatusfilter, invalid data flows downstream and becomes very expensive to clean up later. - Pitfall 2: hardcoded category/UoM. Hardcoding Kingdee's category names into WDT fields causes dictionary mismatches. The safer approach is a dedicated mapping table maintained by the business; Qeasy only does the lookup.
- Pitfall 3: ignoring multi-UoM and extended attributes. Item master often carries multiple units (box, bottle, pallet). Syncing only the base UoM leads to unit errors when stores place orders. After the header is stable, dedicate a second phase to multi-UoM and extended attributes.
- Pitfall 4: missing dependencies. Items depend on customers, suppliers, and warehouses. If those upstream records aren't synced first, item sync fails on missing foreign keys. In Qeasy, mark upstream strategies as prerequisites in the "depends on" field so the platform enforces execution order.
- Pitfall 5: overly aggressive schedule. Item interfaces usually return large payloads; too-frequent schedules can cause IO spikes on the ERP database. A 15-minute incremental cadence is the common sweet spot.
When to Use and When Not to
Use it when: item master is owned by ERP and consumed by retail/e-commerce/storefront; coding rules are stable on the source side with a clear approval workflow. Don't use it when: both ERP and the retail middle platform independently maintain items with irreconcilable conflicts, or when item master changes are extremely frequent across multiple systems requiring merged modeling.