Kingdee YXC – Query Material Info: A Practical Guide on Qeasy Datahub

What This Strategy Solves (Scenario & Value)

When integrating Jushuitan with Kingdee YXC for supply-chain scenarios, the material master is the foundation for every downstream document — sales orders, purchase receipts, and inventory. In one real project, we ran into a recurring issue: store operators kept editing specs, names, and auxiliary attributes directly in YXC, while downstream distribution, e-commerce, and finance all depended on the same SKU codes. After three months, the two sides drifted apart by hundreds of SKUs.

The "YXC – Query Material Info" strategy treats YXC as the authoritative source for material master data. It pulls incremental changes into the Qeasy Datahub on a time window and lets subsequent strategies distribute them to Jushuitan and other systems. It answers a simple but critical question: who moves first, who is right, and who is the fallback.

Data Flow & Field Mapping

The data flow is straightforward: Kingdee YXC → Qeasy Datahub, single direction, upstream only.

Typical field mapping: number ↔ material code; name ↔ material name; category ↔ category; unit ↔ base UoM; price ↔ reference price; modify_time ↔ last modified.

How to Configure on Qeasy

On the Qeasy Datahub we split the configuration into three blocks:

1. Source connector. Pick Kingdee.YXC, GET, effect QUERY. Set modify_start_time to {{LAST_SYNC_TIME}}000 and modify_end_time to {{CURRENT_TIME}}000. These placeholders are runtime variables that Qeasy resolves on every schedule tick.
2. Pagination and detail. Set page_size to 20, disable idCheck, disable buildModel, enable autoFillResponse. For each page, use otherRequest.detailAPI = /jdy/v2/bd/material_detail to pull specs, auxiliary units, and images by primary key.
3. Target landing. Pick datahub (Qeasy), mark the API as a "write no-op", effect EXECUTE, POST, number=0, id=0, idCheck=true. This looks odd at first, but it is a very common pattern in Qeasy rollouts — centralised code-mapping management. The place-holder strategy handles only the upstream pull; actual writes into target systems are handled by downstream distribution strategies (such as "Qeasy → YXC – Material") so the same master record is never written twice.

When training customer teams, we always stress one rule: this strategy is responsible for accuracy, not completeness. Downstream strategies that depend on it carry the burden of full delivery.

Implementation Steps

We recommend a three-phase rollout, which is also the typical "dual-track incremental + full" approach seen across Qeasy customers:

• Step 1: Calibrate the incremental starting point. Before going live, do a manual full export from YXC and confirm the SKU count. Then run an empty-window pull (start and end both pointing to an early historical moment) to seed Qeasy with all existing records. Do not skip this step — otherwise the incremental window will start at "deployment day" and everything before will be missing.
• Step 2: Full trigger and reconciliation. Enable the schedule */10 7-22 * * * (source, every 10 minutes) and */11 7-22 * * * (target, every 11 minutes). The 1-minute offset avoids resource contention. Run for 24 hours, then produce a cross-system reconciliation report and confirm code, name, and category are aligned.
• Step 3: Steady-state incremental. After reconciliation, the strategy only pulls records whose modify_time falls inside the window. When business users complain "this SKU didn't sync", first check whether LAST_SYNC_TIME rolled back, then check whether someone rewrote modify_time manually in YXC.

Lessons Learned

1. Wrong timestamp unit. The YXC API expects millisecond timestamps, but many engineers pass seconds by default — causing either massive duplicate pulls or a window shrunk by 1000x. The safe practice is to always append 000 in the Qeasy placeholder.
2. page_size too high triggers rate limits. YXC's actual ceiling is not public; we hit rate limits after raising page_size to 200. Twenty is the conservative value most Qeasy customers settle on.
3. modify_time overwritten. Operators sometimes rewrite timestamps when bulk-pricing, which silently skips records. Add a version-number fallback in Qeasy: only update when the pulled content actually differs from what Qeasy already holds.
4. Detail API never called. Pulling only the list loses specs and aux attributes, and downstream distribution cannot use them. Always wire up detailAPI and deduplicate by primary key.
5. Header and body mixed into one strategy. Material sync should split header (master info) and body (specs, aux properties, multi-units) into two strategies. A common Qeasy pattern is two sequential strategies where the second declares depends_on on the first's id.

When It Fits and When It Doesn't

Fits: YXC is the authoritative master source and downstream consumers need incremental updates; SKU volume below several hundred thousand; there is a high-frequency change window during business hours. Does not fit: YXC is only a distribution endpoint and the real master lives in another ERP or PIM; real-time (sub-second) inventory sync is required; cross-entity or cross-book multi-org sync is involved.