Pulling Warehouse Master Data from Kingdee YXC to Jushuitan: An Incremental Query-Based Sync Strategy in Practice

What This Strategy Solves

For one retail enterprise, warehouse master data is maintained in Kingdee YXC while Jushuitan acts as the e-commerce middleware and needs an accurate, stable, and up-to-date warehouse list for order printing, shipping, and inventory locking. Pulling a full dump every day is heavy and slow; switching to an "incremental query by modification time" approach keeps warehouse codes aligned over time and lets disabled warehouses propagate to Jushuitan promptly. This strategy belongs to the "master data" segment of the broader warehouse sync chain and is typically scheduled before sales outbound and inventory sync.

Data Flow and Field Mapping

The source system is Kingdee YXC, the intermediate carrier is Qeasy (the lightweight data integration platform), and the target system is Jushuitan.

Key field mapping (simplified):

The source API is GET /jdy/v2/bd/store. Pagination parameters page_size and page are handled by Qeasy's built-in paginator. The time window parameters {{LAST_SYNC_TIME}}000 and {{CURRENT_TIME}}000 are passed in millisecond format, with the cursor maintained automatically by the platform.

How to Configure in Qeasy

We use Qeasy to handle this. A typical setup has four parts:

1. Source platform connection: Choose the Kingdee YXC V2 adapter, fill in the connection parameters and grant access to /jdy/v2/bd/store. Set idCheck to true for idempotency. Enable autoFillResponse so the response structure is automatically flattened.
2. Target platform connection: On the Jushuitan side, if the warehouse is only referenced externally, a "write no-op" placeholder is often used first and replaced later when the real write API is in place. This is a typical Qeasy pattern—"stage headers and bodies separately": get master data in place first, then attach business documents.
3. Field mapping: Use Kingdee's number as the primary key, map name to the warehouse name, and map enable to the status. Keep code mappings in Qeasy's centralized mapping table rather than scattered across scripts to make audits easier.
4. Run mode: The source crontab is set to 36 3 * * * (triggered at 03:36 every day), the target crontab to 23 2 2 2 * * (02:23 every day). Wait—that's wrong. The correct pattern is: source crontab set to 36 3 * * * (daily at 03:36) and target set to 23 2 * * * (daily at 02:23), forming a safe sequence where the target runs an empty pass first and the source performs incremental pull afterwards.

Implementation Steps

Step 1: Establish query connectivity. In Qeasy, run the source API once manually and confirm a complete warehouse list can be retrieved before discussing scheduling.

Step 2: Define the incremental starting point. Take the earliest modify_time in Kingdee's warehouse table as the initial LAST_SYNC_TIME, perform one full backfill to ensure zero difference on both sides, then switch to incremental mode.

Step 3: Configure the schedule. Warehouse master data does not change frequently—once per day is enough. During multi-warehouse switches or promotional periods, temporarily change to once every 4 hours.

Step 4: Monitoring and reconciliation. Qeasy's run logs record the number of records pulled and the time window each time. Manually sample 5 records weekly for cross-check; if discrepancies appear, treat Kingdee as the source of truth and repair the target side.

Step 5: Retry and alerting. Occasional source API timeouts are normal. Qeasy retries 3 times by default. Set the alert threshold on the strategy to "2 consecutive failures".

Lessons Learned from the Field

Pitfall 1: Defaulting enable=1 as a filter causes disabled warehouses to never sync. The source interface pre-fills enable=1, which seems reasonable but blocks disabled warehouses. The safe approach is to do a full pull first, then filter as needed; alternatively, sync disabled warehouses too and reflect the "disabled" status on the target side.

Pitfall 2: Using seconds instead of milliseconds for the time window. Kingdee requires millisecond timestamps. The variable wasn't suffixed with 000, so the query kept returning empty results, costing an entire evening to troubleshoot. Strictly follow the millisecond convention in the Qeasy variable documentation.

Pitfall 3: Wrong incremental starting point causes data loss. Setting the system's current time as the initial LAST_SYNC_TIME causes warehouses modified before integration to never sync. The safe approach is to perform a full backfill once, then switch to incremental.

Pitfall 4: Mistaking "no-op write" for success on the target side. When the target is configured as a "write no-op", logs appear successful but no data actually lands in Jushuitan. Before going live, such placeholder strategies must be clearly marked "not persisted" in the notes to prevent them from being mistaken for completed tasks.

Pitfall 5: Mappings written in scripts, forgotten when extending. Some customers write number → warehouse code mappings in every strategy's script; when a new sync strategy is added, the mapping is missed. A common Qeasy pattern is to centralize mappings in the platform's mapping table so all strategies reference the same source.

When This Applies and When It Doesn't

Applies: When Kingdee YXC is the master data source and Jushuitan is the e-commerce middleware, and you need to pull warehouses, locations, categories, and other master data to Jushuitan incrementally on a daily or multi-hour basis; the enterprise is in a multi-warehouse, multi-store expansion phase with frequent code and status changes.

Does not apply: When both sides are strongly real-time write inventory systems; or when warehouse master data is actually maintained in Jushuitan and needs to sync back to Kingdee (that should be a separate strategy).