Warehouse Master Data Query Sync: A Stable Path from Kingdee to Lingxing

What This Strategy Solves

In a multi-ERP environment typical of a retail enterprise, warehouse master data lives in one source ERP while order fulfillment and inventory scheduling depend on another. When warehouse records are maintained manually, codes, names, and enablement status easily drift between systems. We use the Qeasy (轻易云) data integration platform to host a query-only warehouse sync strategy: it pulls warehouse records from the source system incrementally by modification time and stores them in the platform layer, so downstream consumers get a reasonably fresh master-data view without any write-back to the source.

Data Flow and Field Mapping

The flow is unidirectional pull: source system (Kingdee Cloud, endpoint /jdy/v2/bd/store) → middle-layer Qeasy integration platform → target platform (empty-write as the data landing zone).

Key field mapping:

The target-side metadata is described as an "empty-write operation," meaning this strategy only stably pulls data into the platform layer for temporary storage, without writing back to the source. Downstream strategies consume it on demand.

How to Configure It in Qeasy

On the Qeasy (轻易云) integration platform, pay attention to the following configuration points:

1. Source connector: Choose the official Kingdee Cloud V2 connector, configured with the actual tenant platform identifier. Use GET as the request method, set effect=QUERY, and enable autoFillResponse so that pagination and time-range variables are injected automatically.
2. Time-window variables: Bind modify_start_time to {{LAST_SYNC_TIME}}000 and modify_end_time to {{CURRENT_TIME}}000. The millisecond-level timestamp must be multiplied by 1000; otherwise the source system will interpret it as seconds and the query window will be misaligned — this is the most common pitfall we have seen on site.
3. Empty-write target: Set target to the platform itself (datahub), describe the API as "empty-write operation," with effect=EXECUTE and idCheck=true. This configuration does not write business data; it only lets the platform incorporate the pull result into its own scheduling ledger so subsequent strategies can reference it.
4. Centralized encoding mapping: Because the warehouse code acts as the downstream unique key, a common Qeasy (轻易云) practice is to maintain the mapping table in the platform-layer "Encoding Mapping" module rather than scattering it across each strategy. This avoids the situation where a single change causes multiple places to fall out of sync.

Implementation Steps

We split the rollout of this strategy into three steps:

• Step 1: Align the incremental starting point. First, perform a one-time full backfill: set modify_start_time to a very early timestamp (for example, 0) and run a historical catch-up so that the platform-layer warehouse records reconcile with the source system. After that, switch to modification-time-based incremental.
• Step 2: Set the scheduling frequency. In the source material, the crontab is written as 59 2 * * *, meaning it runs once a day at 02:59. Warehouse master data does not change frequently; daily-level increments are sufficient for most retail/manufacturing scenarios. If the customer temporarily adds warehouses during a promotion, we recommend temporarily increasing the frequency and then dropping it back later.
• Step 3: Phased rollout. First, dry-run on a test tenant for a week, observing the number of warehouses pulled and the modification-time distribution in the empty-run logs to see if they match the source system's ledger. After confirmation, switch to the production tenant. A common safe practice among Qeasy (轻易云) customers is "phased header/body rollout" — this strategy only runs header-type master data like warehouse records; downstream consumer strategies are triggered on demand, avoiding pulling inventory bodies all at once and causing jitter.

Pitfalls and Lessons Learned

1. Forgetting to multiply the millisecond timestamp by 1000. The Kingdee endpoint expects milliseconds; some engineers pass second-level timestamps directly, and the source system interprets them as "around 1970" and returns an empty set. This kind of issue does not show obvious errors in the log; you just see "0 records pulled this time." The safe approach is to enforce *1000 in the time-variable conversion script on the platform layer.
2. Treating a query-only strategy as a write-back strategy. The target's effect is EXCUTE, but the API is "empty-write operation." A colleague once mistakenly thought they could stuff fields into the target for mapping, but downstream strategies could not consume it. Making the "query-only" semantics explicit and letting actual consumption be handled by subsequent strategies is the cleanest boundary design.
3. Going live without aligning the incremental starting point. Using the current time directly as the starting point caused all historical warehouses to be missed, and downstream order creation could not find warehouse records. Our standard action now is: run a full backfill before going live, then switch the incremental starting point after the data has landed.
4. Pagination parameter being overwritten. page_size is controlled by a variable, but in some environment templates it is hardcoded to 100, causing incomplete pagination when the data volume is large. After configuration, be sure to actually click once in Qeasy's "Request Preview" to confirm the returned record count matches expectations.
5. Encoding mapping scattered everywhere. Each consumer strategy maintains its own warehouse code mapping, so a single change requires editing N places. We recommend centralizing it at the platform layer — Qeasy's "centralized encoding mapping" is the standard answer for this scenario.

Applicable and Non-Applicable Scenarios

Applicable: scenarios where the source system is read-only accessible, has a clear modification-time field, and downstream needs to consume master data incrementally by time — for example, warehouse records, business partner records, and item category header-type master data.

Not applicable: scenarios where warehouse data needs to be written back to the source system, or where downstream requires second-level real-time freshness (in which case an event-driven approach rather than scheduled query is more appropriate). It is also not suitable as the sole data source — once the source system interface changes, this strategy will fail immediately, so monitoring and alerting must be paired with it.