Deep Dive into the Query Kingdee YXC Material (Fetch Unit) Strategy: End-to-End Implementation Guide

What This Strategy Solves

In Kingdee YXC and Jushuitan supply chain integration projects, material master data is the prerequisite for all downstream documents (purchasing, sales, inventory) to run smoothly. A pain point we frequently encounter on the customer site is that the "unit of measure" column in the Jushuitan product master is often empty, which causes downstream documents to fail at unit conversion and leads to inconsistent inventory units on the ERP side.

This strategy does only one thing: periodically query material master data from Kingdee YXC, including unit information, and land it in the Qeasy staging layer, providing downstream strategies that actually write to Jushuitan with a clean, unit-enriched material view. It is essentially a "data preparation + field enrichment" strategy.

Data Flow and Field Mapping (Source → Staging → Target)

The overall link is unidirectional: Kingdee YXC V2 → Qeasy Integration Platform (staging layer). Note that the target side of this strategy is a "write no-op," which is a common engineering technique on Qeasy—fetch the data back and persist it first, and leave the actual writing to the downstream strategies that depend on it.

Key field mapping:

How to Configure on Qeasy

Key configuration points for the source strategy (source.json):

1. Platform identification: Select "Kingdee YXC V2" as the source platform, with platform code Kingdee.YXC, which is the official adapter for Jushuitan and YXC integration.
2. Request body: Set effect to QUERY and method to GET. The four core inputs—modify_start_time, modify_end_time, page, page_size—should all use Qeasy variable placeholders; do not hardcode timestamps.
3. Cursor variables: Use {{LAST_SYNC_TIME}}000 for modify_start_time (convert to milliseconds) and {{CURRENT_TIME}}000 for modify_end_time. This is the soul of incremental synchronization.
4. Detail API: Configure detailAPI = /jdy/v2/bd/material_detail in otherRequest. The main list usually does not include the full description of "unit"; you must call the detail endpoint after getting the main table row ID to enrich the field.
5. Response configuration: Set autoFillResponse: true, allowing Qeasy to automatically build the table according to the response structure, saving the effort of writing schemas manually.

Key configuration points for the target strategy (target.json):

1. Platform: code: datahub, pointing to Qeasy itself.
2. Write no-op: Set api to "写入空操作" and effect: EXECUTE. The purpose is to let this strategy form a schedulable, dependency-aware node, rather than actually pushing data.
3. Dependency: In Qeasy's strategy orchestration, set the depends_on of the subsequent "material sync to Jushuitan" strategy to point to this one. In this way, the downstream write will not be triggered until the unit-enriched material has been fetched—this is the "prepare first, then land" pattern commonly used by Qeasy customers.

Implementation Steps (Phased Scheduling)

We recommend splitting the rollout into three phases:

• Phase 1: Incremental start-point alignment. Manually run one full pull, record the starting timestamp, and use it as the seed value for LAST_SYNC_TIME. This step is strongly recommended during off-peak hours to avoid impacting the production window.
• Phase 2: Full-volume fallback trigger. Manually trigger a "full rerun" on Qeasy to confirm that all historical materials can be pulled with unit_name, then switch to incremental.
• Phase 3: Scheduling frequency. Referring to the cron */5 8-20 * * * in the source material, which means every 5 minutes from 08:00 to 20:00 every day. This window covers the business peak hours of retail enterprises; the night is paused to avoid colliding with the source system's end-of-day tasks.

Each round updates LAST_SYNC_TIME on Qeasy, and the next round's window becomes "last end time → current time," naturally supporting checkpoint resumption.

Pitfall Recap

1. Forgot to multiply the timestamp by 1000. The Kingdee YXC API requires millisecond-level timestamps, while source systems often give seconds; passing it directly will pull zero data. The safe approach is to uniformly append 000 after the Qeasy variable.
2. The main list does not include the unit field. /jdy/v2/bd/material returns only the material header table, with the base unit ID rather than the name; you must call /jdy/v2/bd/material_detail again, otherwise the unit column on Jushuitan will remain empty.
3. page_size is too large and triggers rate limiting. We have seen customers set it to 1000 at once, and the entire batch fails after the Kingdee gateway rate-limits them. It is recommended to start with 50, get it working, and then gradually increase it based on the response time.
4. LAST_SYNC_TIME is not persisted, causing duplicates. If Qeasy's global variable is lost after a restart, the cursor will roll back and cause duplicate pulls. Be sure to confirm that Qeasy has variable persistence enabled (it should be enabled by default).
5. The downstream strategy did not configure depends_on. This is the easiest point to fail—the upstream has not finished fetching units, yet the downstream has already pushed, causing dirty data with "code exists, unit is empty" on the Jushuitan side.

Applicable and Non-Applicable Scenarios

Applicable: Retail, e-commerce, and trading enterprises whose material master data needs to be aligned across multiple systems, and where units/conversion rates must be enriched at the source.

Not applicable: Scenarios where the source already comes with complete unit descriptions, or where the business side does not care about unit precision at all. In such cases, a direct sync strategy is sufficient and there is no need to split out the two-stage "query + write no-op" approach.