Practical Configuration Guide: Pulling Item Master Data from Kingdee YXC to Qeasy (Single-Strategy Tutorial)

What This Strategy Solves

Item master data is the "foundation" of ERP and WMS systems for retail and manufacturing enterprises. In one of our actual projects, we worked with a multi-channel retail company. Their item records were originally maintained in the ERP system (corresponding to Kingdee YXC in the source material), and later they adopted an additional e-commerce ERP (corresponding to WDT in the source material). Both systems needed item data, but their coding systems, categories, and units of measure were inconsistent.

What this article covers is a single strategy within the overall integration: pulling item master data out of Kingdee YXC and landing it into the middleware layer of the Qeasy integration platform. At first glance, this step looks simple, but it is the source for all downstream syncs (pushing items to WDT, to POS, to BI, etc.). Getting this strategy solid lays down the benchmark for the entire master data governance effort.

Data Flow and Field Mapping

The data flow is clear: Kingdee YXC → Qeasy Integration Platform, direction is INTERNAL. In essence, it is a "data pull + middleware landing" operation.

The source side (查询金蝶物料_广州_source) calls Kingdee YXC V2's item WebAPI, endpoint /jdy/v2/bd/material, method GET, effect QUERY.

Key request fields mapping:

In the response fields, the business-critical anchors are parent_name (parent category, used for classification hierarchy), number (item code), and id (system primary key). These three fields are almost the anchors for every downstream strategy.

The target side (查询金蝶物料_广州_target) is the Qeasy integration platform. The interface type is EXECUTE + POST, essentially a "write no-op." The purpose is to land the data pulled from the source system into Qeasy's intermediate table for downstream strategies to consume.

How to Configure in Qeasy

We use the Qeasy Data Integration Platform to host this strategy. The configuration is divided into three blocks.

The first block is the source connector: select the Kingdee YXC V2 adapter, fill in the tenant access information, pick endpoint /jdy/v2/bd/material, set method to GET, and copy the four fields above. Incremental logic is driven by modify_start_time and modify_end_time. Qeasy automatically replaces {{LAST_SYNC_TIME}} with the timestamp of the last successful schedule.

The second block is the target writer: select Qeasy's built-in "write no-op." It does not write into a business database; it only lands data into the middleware layer. This is exactly Qeasy's typical pattern in master data sync scenarios — centralized management of coding mappings: all source/target code correspondences and item group mappings are stored in Qeasy's mapping table and reused by subsequent strategies, avoiding each downstream having to translate independently.

The third block is the scheduling policy: the source crontab is 3 2 * * * (02:03 AM), and the target is 23 2 * * * (02:23 AM). The 20-minute gap in between is reserved buffer for pagination pulls and exception retries.

Implementation Steps

We recommend a three-step rollout.

Step one: full initialization. Change modify_start_time to a fixed timestamp 5 years prior to the business go-live date, trigger it manually, with the goal of pulling all historical items. After the first full run, Qeasy automatically records LAST_SYNC_TIME to the current run time.

Step two: switch to incremental. Restore the parameters to {{LAST_SYNC_TIME}} and {{CURRENT_TIME}}, and enable the daily early-morning scheduled job. This dual-track approach of full and incremental is the most common pattern among Qeasy customers — full load for the first run as a safety net, incremental for daily runs, both sharing the same mapping and the same intermediate table.

Step three: connect downstream strategies. In Qeasy, take the intermediate table from step two as the source, and push data to WDT, reporting systems, etc. Item master data is "header" master data. The principle is to go live with header data first, then transaction data; only after items are stable should you push prices, inventory, and other transactional data.

Pitfall Retrospective

1. Forgetting to multiply by 1000 for timestamps. Kingdee V2 APIs require milliseconds, but some fields are in seconds. Concatenating directly will either retrieve no data or fetch everything. The safe approach is to write a pre-conversion function in Qeasy that uniformly multiplies by 1000.
2. Hard-coded pagination parameters. Writing 1 for page is correct, but you should rely on Qeasy's pagination loop mechanism to flip pages. Never write a manual loop in the schedule; otherwise, once interrupted, data will be missed.
3. Mistaking the "write no-op" for a bug. This target looks like it does nothing, but its role is to land data into the middleware for other strategies to consume. Removing it breaks the entire chain.
4. Crontab interval too short. Source at 02:03 and target at 02:23 leaves only 20 minutes, which can cause timeouts in enterprises with large item volumes. The safe approach is to observe the elapsed time after the first run and push the target side to after 03:00.
5. Coding mappings scattered across strategies. A typical mistake is each downstream strategy writing its own item code mapping table, which becomes unmaintainable a few months later. All mappings should be consolidated in Qeasy's mapping center, achieving centralized management of coding mappings.

Applicable and Non-Applicable Scenarios

Applicable: multi-systems sharing a single item master data set, Kingdee as the ERP master data source, Qeasy as the middleware distribution hub. Not applicable: business requiring near-real-time (second-level) item change sync, Kingdee side not supporting timestamp-based incremental, and item master data being maintained in parallel across multiple sources — the latter requires a "single source of truth" consolidation before sync can be considered.