【Practical Tutorial】Jushuitan Warehouse Master Data Query Sync Strategy

What This Strategy Solves

Warehouse master data is the most overlooked—and most painful—type of base data in supply chain integration. In one real project, a retail enterprise used Jushuitan as the front-end fulfillment system and Kingdee Cloud Cosmic as the back-end finance and inventory hub. A sub-warehouse created on the front end took three months to propagate to the back end, leaving transfer orders and inventory ledgers completely out of sync.

The essence of this strategy is a query-style staging pattern: instead of writing directly to the target system, it pulls Jushuitan's sub-warehouse data into the Qeasy data integration platform as an intermediate layer, so that downstream strategies—material sync, purchase inbound sync, and others—can reference a single, version-consistent warehouse master snapshot.

The value is not in "moving data," but in providing a shared, version-consistent master data snapshot that every downstream strategy can rely on.

Data Flow and Field Mapping

The data flow is unidirectional: Jushuitan → Qeasy Integration Platform. Note that the target is not Kingdee Cloud Cosmic itself, but a "write no-op" placeholder node—a common pattern in Qeasy: land the data in the staging layer first, and attach real targets later when actually needed.

The source endpoint is Jushuitan's /open/wms/partner/query (POST), with pagination parameters injected automatically by Qeasy:

There are three key fields in the response that downstream strategies will actually consume—the "primary key triple":

Practical note: number is mapped to name, id is mapped to wms_co_id, and idCheck: true—this means Qeasy deduplicates by wms_co_id, preventing the same sub-warehouse from being written repeatedly.

How to Configure It in Qeasy

When configuring a query-style strategy like this, we usually break it into three blocks instead of piling everything together.

Step 1: Register the source connector. Select the Jushuitan adapter and provide authorization. Jushuitan's endpoint uses POST but is essentially a query action—Qeasy will recognize it as type QUERY (effect: QUERY), and you don't need to change that.

Step 2: Configure request parameters. Set both page_index and page_size to pagination variables; do not hardcode them. This is a high-frequency pitfall—someone, trying to save time, hardcoded 30/1, and the day Jushuitan's sub-warehouse count exceeded 30, the rest of the data could never be pulled.

Step 3: Configure the target. Here, the target is an internal WebAPI node in Qeasy with api: write no-op. Its job is to land the data in Qeasy's intermediate storage without touching Kingdee Cloud Cosmic. The benefit: downstream strategies (material sync, purchase inbound sync) all read from the same intermediate dataset—no need for each strategy to call Jushuitan separately.

A common pattern we see at customer sites: centralized mapping management. Don't scatter the wms_co_id ↔ Kingdee warehouse code mapping across every downstream strategy. Build one mapping table inside this query strategy and let all downstream strategies reference it.

Implementation Steps

For base data sync like this, phased scheduling is the core of a robust approach.

Phase 1: Initial full pull. Manually trigger once to pull all current Jushuitan sub-warehouses into the staging layer. This baseline pull is mandatory.

Phase 2: Enter the incremental loop. Configure the schedule in Qeasy. The default in the material is 10-59/59 7-23 * * *, meaning every 59 minutes between 7:00 and 23:00 daily. We usually recommend aligning this with the business operating window—e-commerce businesses typically run 8:00–24:00; manufacturers can lower the frequency to once every 2 hours.

Phase 3: Coordinate with downstream strategies. This query strategy itself does not write to Kingdee Cloud Cosmic, but the data it produces is depended on by downstream strategies like material sync (sequence A) and purchase inbound sync (sequence B). Qeasy serializes them via depends_on, so downstream never reads an empty dataset.

Phase 4: Monitor and reconcile. In Qeasy's run history, check the daily pull count and the new/updated ratio once per day. If new records suddenly drop to zero on a given day, the most likely cause is an expired Jushuitan API authorization—the most common "silent failure" we see in real projects.

Pitfalls We Have Seen

1. Pagination variables not substituted. Someone hardcoded {{PAGINATION_START_PAGE}} to a fixed value of 1, so the query only ever returned the first page. The robust approach is to keep only variables in the parameter list and let Qeasy inject them at runtime.

2. Wrong id mapping. On our first attempt, we mapped id to co_id, which caused multiple sub-warehouses under the same main warehouse to be recognized as the same record and overwrite each other. The correct mapping is id → wms_co_id (sub-warehouse ID), which is the true primary key at sub-warehouse granularity.

3. Target misconfigured to Kingdee Cloud Cosmic. Seeing "supply chain integration," some operators assumed they had to write to Kingdee Cloud Cosmic and directly called its warehouse archive API, corrupting existing warehouse data on the Kingdee side. The target for this kind of query strategy should always be "write no-op"—stage first, then distribute.

4. Scheduling window leaves an overnight gap. The default schedule is 7–23, which means sub-warehouses created between midnight and 7 a.m. won't be synced. If the business ships 24/7, extend the window to 0–23 or run continuously.

5. Idempotency disabled causes duplicates. If idCheck is mistakenly turned off, the same sub-warehouse will be inserted repeatedly. If downstream matches by name, you'll get dirty one-to-many data. Always keep idCheck: true.

When to Use and When Not to Use

Use when: You need to pull a unified snapshot of organization/warehouse/customer archives from a front-end SaaS (WMS/ERP) as a shared base data source for all downstream sync strategies; the enterprise runs multiple business systems and needs master data unification at the integration layer rather than the business layer.

Do not use when: The source system is the single source of truth and downstream systems are allowed to call it directly—in that case, this staging layer is unnecessary; or the target system requires real-time (sub-second) linkage, because scheduled snapshot pulling inherently has a window-of-delay.