Syncing Warehouse Master Data from Jiky to Kingdee Cloud Stellar: A Single-Strategy Walkthrough

What this strategy solves

In a supply-chain integration for a retail enterprise, warehouse master data is the "foundation" that every downstream document (purchase receiving, sales shipping, real-time inventory, transfers) relies on. If the foundation is shaky, the entire upper layer has to be reworked. Our job here is to push warehouse records from the source system into the target ERP as a stable, repeatable piece of the base-data sync pipeline.

Data flow and field mapping

The flow is straightforward: source system (Jiky) → Qeasy data integration platform → target system (Kingdee Cloud Stellar).

Key field mapping (derived from the strategy metadata):

The source side pulls incrementally by a modified-time window with pageIndex / pageSize pagination. The target side calls batchSave to submit multiple records at once.

How to configure it in Qeasy

In Qeasy, we treat this strategy as a standard reference for "base-data sync." The configuration falls into four parts:

1. Source interface: WebAPI erp.warehouse.get, POST request, pagination parameters pageIndex and pageSize, incremental window uses gmtModifiedStart / gmtModifiedEnd, with time placeholders {{LAST_SYNC_TIME|datetime}} and {{CURRENT_TIME|datetime}}.
2. Target interface: WebAPI batchSave, POST request, the primary key FNumber is mapped directly from the source warehouseCode.
3. Code mapping: Constants like FCreateOrgId and FUseOrgId should be maintained centrally in Qeasy's field mapping instead of scattered in scripts. This is one of the most common practices we recommend to customers — when you switch organizations later, you change it in one place.
4. Response handling: Enable autoFillResponse so Qeasy auto-recognizes whatever fields the source returns; you don't have to manually build the schema field by field, which reduces misconfiguration risk.

Implementation steps

We recommend phasing the rollout into three stages to stay safe:

• Stage 1: Full initialization. Trigger a manual run to push all current warehouse records from the source to the target. Verify that codes and names match on both sides; once the "baseline" is confirmed, enable the scheduled jobs.
• Stage 2: Incremental start. Initialize LAST_SYNC_TIME to the timestamp when the full sync finished, then enable the schedule 3,23,43 * * * * (three pulls per hour on the source side). Stagger the target-side schedule by a few minutes (10,30,50 * * * *) so the two sides don't collide in the same second.
• Stage 3: Steady-state operation. Monitor success rate, error count, and detailed failures returned by the target side. Run a full reconciliation every weekend as a "safety net" for the incremental sync.

This is what we call "incremental + full dual-track": incremental carries day-to-day traffic, while the weekly full sync acts as a safety net. When the numbers disagree, you immediately know whether it's a window miss or a code drift.

Pitfalls from real projects

• Pitfall 1: On first configuration, someone hard-codes FCreateOrgId to a specific organization on the target side. Later, switching the org means global find-and-replace. The safe approach is to manage it through a variable or mapping table in Qeasy, so a single change applies everywhere.
• Pitfall 2: The incremental window uses gmtModifiedStart with no upper bound. Across time zones, a "future time" can slip in and the target side errors out directly. What we do is always have gmtModifiedEnd equal to current time minus one minute, leaving room for source-side transactions to commit.
• Pitfall 3: pageSize=50 is the default, but one customer once bulk-edited several hundred warehouses. The single response far exceeded expectations and stressed memory. We recommend exposing batch size as a tunable parameter in Qeasy — start with 50, then scale up based on the scenario.
• Pitfall 4: When batchSave fails on the target side, Qeasy rolls back the batch by default, but the source-side watermark has already advanced, so the next incremental run misses that batch. The safe approach is to enable "do not advance watermark on target failure" in Qeasy, or auto-rerun the current window on failure.
• Pitfall 5: Warehouse codes contain special characters (slashes, spaces). The source accepts them but the target's validation rejects them. We recommend adding a "cleaning rule" at the code-mapping layer — not changing business data, but detecting and alerting.

When this fits — and when it doesn't

Fit: multi-org, multi-book supply-chain integrations where base data needs to be pushed one-way into the target ERP as a prerequisite for downstream documents.

Does not fit: scenarios requiring bi-directional sync, frequent deletions/edits, or where the source system itself is constantly refactoring its master-data model. In those cases, we recommend governing the source side first before talking about sync.