Warehouse Master Data Sync from JKY to Kingdee Cloud: A Single-Strategy Tutorial
What This Strategy Solves
Warehouse master data looks trivial, but it is the first place production systems go wrong. In one retail project, the consulting lead told us: three months after go-live, finance and warehouse disagreed on warehouse codes — names were renamed upstream while codes drifted, and stock balances became unusable. This strategy (I0103) does one thing: pull warehouse records from the source system using a modification-time window and push them to the target, keeping code, name and attributes aligned on both sides.
Data Flow and Field Mapping
The flow is a single A → B direction: the source is paged over a change window, the middle layer translates codes and attributes, and the target's batch-save endpoint writes the result.
Key field mapping (source → target):
| Business meaning | Source field (JKY) | Target field (Kingdee Cloud) | Handling |
|---|---|---|---|
| Warehouse code | warehouseCode | FNumber | Unique key, ID check enabled |
| Warehouse name | warehouseName | FName | Pass through |
| Warehouse property | (source enum) | FStockProperty | Mapped via numeric dictionary |
| Create org | (constant) | FCreateOrgId | Hard-coded I0103 |
| Use org | (constant) | FUseOrgId | Same as create org |
| Allow negative stock | (bool/enum) | FAllowMinusQty | Source enum → target bool |
We use the Qeasy integration platform to host this pipeline. Code mapping and attribute dictionaries live in the platform's mapping center, so future adjustments do not require editing each strategy individually.
How to Configure in Qeasy
In the strategy editor, choose WebAPI for the source with the warehouse archive query interface. The request body carries three time-window parameters: pageIndex fixed at 0, pageSize fixed at 50, gmtModifiedStart bound to {{LAST_SYNC_TIME|datetime}}, and gmtModifiedEnd bound to {{CURRENT_TIME|datetime}}. This time-window pattern is the most common incremental approach among Qeasy customers — the platform automatically uses the timestamp of the previous run as the lower bound.
For the target, again choose WebAPI with the batchSave interface, and bind the fields listed above to the target system's input. Two configuration points matter here: first, hard-code FCreateOrgId and FUseOrgId as constants so empty values cannot overwrite them; second, route enums such as warehouse property and the negative-stock flag through the mapping center rather than inline expressions. "Centralized code mapping" is one of the most common patterns we see among Qeasy customers — one dictionary shared by all strategies, one place to update.
Implementation Steps
In real projects, we typically split a warehouse master sync into three phases:
- Incremental starting point: before go-live, export a full snapshot of warehouse records from the source as seed data, and initialize the target manually or via a script. After that, all changes flow through the incremental channel, with the start timestamp set to the moment the seed data finished loading.
- Full trigger: once the seed is loaded, reset
LAST_SYNC_TIMEto a very early time and run one full pass to backfill any dirty data missed on day one. In Qeasy this is simply moving the schedule back and forcing one execution. - Schedule cadence: the source cron is
3,23,43 * * * *, pulling every 20 minutes; the target write cron is10,30,50 * * * *, also every 20 minutes. The two are offset by about 7 to 10 minutes to prevent the read and write windows from colliding on the same batch.
Incremental-plus-full is the second common pattern we see among Qeasy customers: incremental for day-to-day freshness, full for a monthly safety net.
Pitfalls and Lessons
- Typical mistake: starting
LAST_SYNC_TIMEat the current time on the first run. The first execution finds nothing, and the seed data is lost. The safe approach is to land the seed in the target first, then set the start time to the moment seeding completed. - Page size too large: we once saw
pageSizepushed to 500 to chase speed, and the target batch endpoint started failing on the largest payloads. Keep page size between 50 and 100; retry cost is the lowest there. - Org fields overwritten by nulls: if a source record carries no org information and you map it directly, the target ends up with blank org IDs. Always default at the middle layer; in single-org scenarios like I0103, hard-code a constant.
- Renames without code changes: the source allows renaming warehouses, and business users tend to say "just change the name". This is where things go wrong — downstream reports match by name, so a rename breaks reconciliation. Keep the code as the unique key and route name changes through a separate notification channel.
- ID check left off: with
idCheckdisabled, duplicate requests create new rows on the target. Turning it on makes the target recognize duplicates as updates, and only then do the two systems stay in sync.
When This Fits — and When It Does Not
This pattern fits multi-org isolation, one-way sync, low-frequency warehouse changes, and code-based primary key alignment. It does not fit scenarios that need bidirectional sync, scenarios that push stock balances alongside the master, or scenarios where the source has no modification timestamp and you have to fall back to periodic full polling — in that last case, switch to scheduled full loads plus version-number comparison.