Material Master Sync in Practice: Code Mapping and Phased Scheduling from Jushuitan to Kingdee Cloud Sky

What This Strategy Solves

Syncing material master data from the e-commerce front end (Jushuitan) to the ERP back end (Kingdee Cloud Sky) sounds like a simple "product master sync," but in practice inconsistent codes, mismatched units, and divergent category systems will quietly drift the two sides apart within three months. This tutorial walks through how we used the Qeasy data integration platform to carry that master sync and clearly separate "how the source queries, how the middle layer maps, and how the target writes."

Data Flow and Field Mapping

The overall flow is Jushuitan → Qeasy integration platform (middle layer) → Kingdee Cloud Sky. The middle layer is not a mere messenger — it owns code mapping, field completion, and deduplication.

Key field reference (abbreviated; real projects have more fields):

Note that Kingdee's query interface executeBillQuery uses the upper-case F-prefixed fields like FNumber and FMATERIALID, while Jushuitan uses camelCase. You must standardize once in the middle layer — never pass them through directly.

How to Configure It on Qeasy

We used Qeasy to handle this, and the configuration typically splits into three parts:

1. Source connector (Jushuitan): Configure the Jushuitan open-platform product query with cursor pagination (StartRow + Limit 2000) so the source system is not overwhelmed by a single full-table pull.
2. Middle layer (Qeasy integration platform): This is actually a "write no-op" placeholder strategy. The real work happens in the platform's built-in integration flow orchestration — code mapping, unit conversion, and category normalization all live here. Two patterns we frequently see among Qeasy customers: first, maintain all code mappings in a single "mapping table" so adding a new store only requires editing the table, not the flow; second, push header fields (code, name, unit) and body fields (extended attributes, SKU dimensions) in two phases — get the master data flowing first, then enrich.
3. Target write (Kingdee Cloud Sky): Call Kingdee's save-type interface to write the material. The critical point is treating FNumber as an idempotency key — rerunning with the same code must not produce duplicate materials.

The source-side metadata contains crontab: 3-59/5 * * * *, which looks like a cron schedule but is really a constraint rhythm on the source side: at most one call every five minutes, to avoid triggering the upstream rate limiter.

Implementation Steps

We like to split master-data sync into three phases for stability:

Phase 1: Incremental starting point First, run a one-time full sync to push all existing Jushuitan products into Kingdee as the baseline. Trigger this manually — do not put it into an automated schedule.

Phase 2: Daily increment Once the baseline is complete, switch to incremental mode. The starting point is the modify_time at the end of the baseline; thereafter, roll forward by modification time. A scheduling interval of every 5–10 minutes typically matches Kingdee's write capacity. For larger customers, we relax this to 15 minutes and run a dual track on Qeasy — increment during the day, plus a reconciliation-style full sync once a week in the early morning as a safety net.

Phase 3: Reconciliation and repair Once a week, pull a code-by-code comparison between the two sides and route differing entries through a dedicated repair flow. Do not mix this into the daily sync, or the logs become unreadable.

Pitfalls Revisited

These are all things we have actually tripped over on site:

1. Passing codes through transparently, drifting within three months. A typical mistake is letting the original Jushuitan code become Kingdee's FNumber. Once the source side allows business users to edit codes, master data falls apart. The safe approach is to maintain a unified code in the Qeasy middle layer and treat the source code only as a query condition.
2. Ignoring the meaning of idCheck=true. The source metadata defaults idCheck to true, meaning "deduplicate by primary key before writing." If the middle layer does not map Jushuitan's i_id to Kingdee's FMATERIALID, deduplication silently breaks and duplicate materials appear.
3. Hard-coding pagination parameters. Kingdee's Limit + StartRow must increment with each loop. Some newcomers write StartRow=0 as a constant, so every call returns only the first 2000 rows.
4. Skipping unit conversion. Jushuitan's "piece" and Kingdee's "base unit" are often not 1:1. You need a unit conversion table, not a raw string pass-through.
5. Bumping straight into the rate limiter. Jushuitan enforces call frequency limits; the source-side crontab already suggests a "once every five minutes" rhythm. Do not compress that interval further, or the source system will lock the IP.

When It Fits and When It Doesn't

Fits: Multi-store, multi-channel retail or distribution companies that need to consolidate e-commerce product master data into the ERP; cases where code systems must be unified in the middle layer; daily change volume within the tens of thousands.

Doesn't fit: Source-side codes are frequently edited by business users with no stable primary key; the two category systems are fundamentally incompatible (forced mapping will distort the data); real-time, second-level inventory sync is required (that is a separate real-time inventory strategy, not master-data sync).