Syncing Item Master Data from ERP to E-Commerce Mid-Platform: A Practical Breakdown of a Supply Chain Integration Strategy

What This Strategy Solves (Scenario & Value)

In retail and distribution scenarios, one retail company keeps its item master data in the ERP (Kingdee Cloud), while stores, e-commerce, and warehousing run on Jushuitan. When both systems write independently for months, you eventually face SKU count drift, inconsistent brand fields, and unit chaos.

This article focuses on a single strategy: syncing item master data from Kingdee Cloud to Jushuitan's jushuitan.itemsku.upload API on an incremental basis. It is neither a full migration nor a bidirectional sync—it is a one-way flow with the ERP as the single source of truth and Jushuitan as the downstream consumer.

Data Flow & Field Mapping

The flow is unidirectional: Kingdee Cloud (source) → Qeasy Data Integration Platform (middleware for mapping & scheduling) → Jushuitan (target). Qeasy does not store data here; it only fetches, transforms, and pushes.

The source calls Kingdee's executeBillQuery, retrieving the item view by FMasterId and FNumber. Key fields:

Source Field (ERP)	Meaning	Target Field (Jushuitan)	Meaning
`FNumber`	Item code	`sku_id` / `i_id`	Item code / style code
`FName`	Item name	`name` (template)	Item name
`FBaseUnitId.FName`	Base unit	`unit`	Unit
`FSpecification`	Specification	`properties` (template)	Specification
`F_XC_ASSISTANT.FDATAVALUE`	Brand (auxiliary)	`brand`	Brand
`F_XC_DECIMAL`	Wholesale price	`price` (template)	Price
`F_XC_Integer`	Shelf life (days)	`shelf_life`	Shelf life

The target calls jushuitan.itemsku.upload, using Jushuitan's id as the idempotency key (idCheck: true). The shelf_life field is also wrapped in a lightweight expression: case when '{{F_XC_Integer}}' = 0 then '' else '{{F_XC_Integer}}' end, which treats 0 as empty.

How to Configure on Qeasy

When setting this up at a customer site, we typically organize the work into four modules:

1. Source connector. Pick the official Kingdee Cloud connector, fill in the tenant address and account set info (desensitized), and test executeBillQuery connectivity. We recommend saving a field snapshot in Qeasy for future troubleshooting.

2. Target connector. Pick the Jushuitan connector, bind the merchant authorization, and confirm jushuitan.itemsku.upload is available under that tenant. Note that idCheck must be enabled, otherwise duplicate pushes will create dirty data.

3. Field mapping. Complete the mappings above in Qeasy's mapping canvas. Common pitfalls: brand is an auxiliary data field, requiring .FDATAVALUE instead of the raw ID; unit is a base data field and must use a chained path like FBaseUnitId.FName. A common pattern among Qeasy customers is to centralize these special-field rules in a "mapping constants table" for reuse across items, customers, and vendors.

4. Scheduling & orchestration. The source crontab is set to */15 7-23 * * * (every 15 minutes) and the target to */6 7-23 * * * (every 6 minutes). Both share the same time window so fetching always leads pushing. Qeasy chains the two schedules into a pipeline and auto-retries on failure.

Implementation Steps

Stage 1: Initialize the incremental starting point. Before the first run, use FMasterId snapshot in the ERP as the incremental anchor. Subsequent runs only fetch records with FMasterId > lastMaxId, avoiding a full pull on day one.

Stage 2: Full-volume trigger (optional). When historical data is missing or during large-scale initialization, switch to full mode and backfill in batches. We recommend 1,000–2,000 records per batch, then switch back to incremental.

Stage 3: Routine scheduling. Run incremental + scheduled mode in parallel—source every 15 minutes, target every 6 minutes. A safe approach: configure "source completion → target execution" as a serial dependency in Qeasy, so any failure on one side pauses the other, preventing missing or duplicate records.

Stage 4: Exception handling. Jushuitan rejects items with empty code or brand, so validation must be done up front on the Qeasy side. Failed records should be written back to logs and re-pushed after manual correction.

Post-Mortem: Lessons from the Field

Brand field pulled as ID. Brand in the ERP is auxiliary data; pulling F_XC_ASSISTANT.FNumber would push a system code to Jushuitan that operations cannot read. Always use .FDATAVALUE for the display value.
Shelf life 0 treated as valid. When shelf life is unset, the ERP defaults to 0. Without handling, Jushuitan will display items with "0-day shelf life". The case when expression mentioned above exists exactly for this case.
Unit field pulled as ID instead of name. FBaseUnitId is an object; pulling it directly yields the primary key, which Jushuitan cannot accept. Use the chained path FBaseUnitId.FName.
Mismatched scheduling frequency. Initially both sides ran at 15-minute intervals, causing the push side to fall behind. Switching to source 15 min / target 6 min balanced the load.
No deduplication on repeat pushes. idCheck is off by default. Without enabling it, the same SKU gets overwritten repeatedly. Idempotency check must be explicitly turned on.

When This Applies & When It Doesn't

Applies: ERP is the single source of truth for item master; e-commerce or distribution mid-platform is the downstream consumer; near-real-time (minute-level) sync is sufficient; business is dominated by inserts and updates with no reverse write-back needed.

Does not apply: Bidirectional sync is required (e.g., writing SKU status back to ERP), images or attachments need syncing, or sub-second latency is required—these cases call for more complex designs.