Master Data Sync in Practice: Querying Departments from Kingdee YXC and Landing Them on the Integration Platform

What This Strategy Solves

Without synchronized master data, business documents are castles in the air. In one real project at a retail enterprise's supply-chain integration, the first step to connect the ERP and the store-side system was not to sync sales orders, but to incrementally pull department master data from Kingdee YXC into the integration platform as a reference for downstream writes. This strategy does only one thing: incrementally query department data from the Kingdee YXC V2 API and land it on the Qeasy integration platform, so that downstream strategies (materials, customers, orders) can reference departments by code.

Data Flow and Field Mapping (Source → Middle Layer → Target)

The source is Kingdee YXC V2's /jdy/v2/bd/department API, type QUERY, HTTP GET. The target is the "empty-write" WebAPI on the Qeasy platform (internal registration purpose, POST).

Key request parameters (source-side filter):

Response identification fields: number (department code), id (internal ID). The target is internal registration without concrete business fields, so the key is to persist number and id as the "ID card" for downstream reference.

How to Configure on Qeasy

When using Qeasy (the data-integration platform) to host this, the essence is a QUERY_ONLY internal strategy: incremental pull from the source, land on the platform's own intermediate storage.

Configuration points:

• Source platform: select the Kingdee YXC V2 adapter, API /jdy/v2/bd/department, method GET, type=QUERY, effect=QUERY.
• Incremental time window: bind modify_start_time and modify_end_time to platform variable functions ({{LAST_SYNC_TIME}} and {{CURRENT_TIME}}), so Qeasy maintains the cursor automatically—no manual updates.
• Pagination: enable the page loop, starting at page=1 and incrementing per response until empty or has_more=false.
• Deduplication key: idCheck=true, using department id as the unique key to avoid duplicate writes.
• Target platform: choose the Qeasy platform instance, API "empty write" (internal registration).
• Centralized code mapping: pre-register the number field in Qeasy's code-mapping module so that material and customer strategies can share one source of truth—avoiding the common pattern where each downstream maintains its own.

Implementation Steps (Incremental Start / Full Trigger / Schedule Frequency)

1. Initial full backfill: set modify_start_time to a very early timestamp (e.g., 0 or business go-live date) and modify_end_time to the current time. Run once to pull all historical departments onto the platform.
2. Establish the time cursor: after the first successful run, Qeasy automatically records LAST_SYNC_TIME; subsequent runs advance at millisecond granularity.
3. Schedule frequency: the source strategy cron is 0 8 5,15,28 * * (08:00 on the 5th, 15th, and 28th of each month)—suitable for low-frequency master data like departments. If the customer's organization changes more frequently, switch to daily. The target cron 23 2 * * * serves as an internal reconciliation window.
4. Verification & reconciliation: use Qeasy's run logs and impact counters under "Strategy Monitoring" to verify new and updated rows.
5. Dependency orchestration: this strategy is depends_on for downstream material-sync and sales-order strategies, and Qeasy's dependency scheduler guarantees upstream runs before downstream.

Pitfalls and Lessons Learned

• Timestamp unit mismatch: the Kingdee V2 API requires milliseconds, but platform variables default to seconds. The safe approach is to apply _function {{LAST_SYNC_TIME}}*1000 directly in the source parameter—otherwise the first run pulls nothing.
• Skipping the initial full load: a typical mistake is going straight into incremental mode after go-live, only to find some historical departments missing. Always run a full backfill first, then switch to incremental.
• Mixing id and number: a common on-site issue is using number (code) as the dedup key, but codes can be edited, causing the same department to be recorded twice. Fix: always use id (internal ID) as the primary key, and treat number as a display field.
• Cross-page data loss: when pagination parameters aren't looped, only the first page is fetched, and monthly reconciliation shows obviously less data. Qeasy auto-pages by page_size, but you must confirm the API supports it and that the response exposes total or has_more.
• Downstream reference too early: material-sync strategies have no depends_on on this department query, so new materials can't find a valid department. Master-data strategies should always be orchestrated as dependencies for their downstream.

When to Use and When Not to Use

Use when: the retail or manufacturing enterprise has a stable org structure with monthly changes, and you need to centralize ERP department master data on the integration platform as a reference for downstream business documents; multiple systems share one set of department codes. Do not use when: the org structure changes too frequently or requires real-time (sub-minute) synchronization—switch to event-driven or streaming APIs instead; also not suitable for small business systems without a department concept.