Querying Kingdee YXC Materials: A Practical Master Data Pull Strategy on Qeasy
What This Strategy Solves
In retail and trading supply chains, master data is often scattered across multiple systems. In real projects, we have seen this exact situation: the e-commerce team maintains product data in the front-end system while the finance and supply chain teams maintain material records in Kingdee YXC. Once the two sides stay out of sync for three months, you end up with mismatched codes, inconsistent units, and diverging statuses — and reconciliation becomes a nightmare.
The "Query Kingdee YXC Materials" strategy pulls material master data from Kingdee YXC into the Qeasy Data Integration Platform using an incremental time window. It does not write back to the source business system; instead, it brings the data in first, leaving room for downstream code mapping, unit conversion, and status filtering.
Data Flow and Field Mapping
The flow is straightforward: the source is Kingdee YXC's material open API, the middle layer is the Qeasy Data Integration Platform, and the target is again inside the platform, marked with a no-op write placeholder, waiting for downstream strategies to consume.
Key source-side fields are shown below:
| Source Field | Meaning | Note |
|---|---|---|
| modify_start_time | Modification start timestamp (ms) | Taken from the last sync time |
| modify_end_time | Modification end timestamp (ms) | Taken from the current time |
| page | Current page | Defaults to 1 |
| page_size | Page size | Defaults to 20 |
The start timestamp is auto-injected by Qeasy as {{LAST_SYNC_TIME}}000, and the end timestamp as {{CURRENT_TIME}}000. This is the core of incremental pulling — a millisecond-level sliding window fetches only materials modified within the window, avoiding full table scans.
The configuration also reserves a detailAPI pointing to the material detail endpoint. When the paginated list response is not enough, you can add a detail call in Qeasy to retrieve specifications and auxiliary attributes.
How to Configure in Qeasy
In the Qeasy Data Integration Platform, this is a typical "query-only" synchronization strategy. There are several key configuration points:
- Source platform selection: Kingdee YXC V2, using its WebAPI access mode, method GET, effect QUERY.
- Request parameters: Configure the four pagination and time-window fields, leaving
{{LAST_SYNC_TIME}}and{{CURRENT_TIME}}placeholders for Qeasy's runtime. - Detail API reservation: Attach a
detailAPIinotherRequestso it can be enabled on demand. - Target-side placeholder: The target API is set to a "write no-op", effect EXECUTE, method POST. This acts as a landing anchor, forming a complete "source — platform" loop in the scheduling graph, so downstream strategies can subscribe to its output.
- Auto-fill response: Enable
autoFillResponseon the source so Qeasy auto-parses the response structure. Engineers focus only on field mapping instead of writing parsers manually.
In Qeasy customer projects, this "query + no-op write" combination is common — the platform essentially serves as a transit hub for the master data center.
Implementation Steps
We recommend a three-phase rollout to avoid hitting the source system with high-frequency calls from day one.
Phase 1: Initialize the incremental starting point. On the first run, set LAST_SYNC_TIME to a clear historical anchor (e.g., midnight on the project go-live date) and run a full backfill. After that, Qeasy persists the timestamp and automatically slides forward incrementally.
Phase 2: Full-trigger verification. After the full load, compare the material count in Qeasy against the total in Kingdee YXC. A discrepancy within 1% is normal. If it is larger, first check the code mapping and filter conditions, then check source-side permissions and pagination limits.
Phase 3: Converge scheduling frequency. The source-side crontab is */10 7-23 * * *, meaning every 10 minutes during business hours, stopped overnight to reduce pressure on the source. The target-side placeholder runs at 23 2 * * *, once a day at 02:23, mainly for tail-end processing and log archival.
The core idea behind phased scheduling is: start at low frequency, stabilize, then increase; leave overnight maintenance windows for the source system.
Pitfalls and Lessons Learned
Pitfall 1: Forgetting to append the millisecond digits. Timestamp variables must be suffixed with 000 to convert to milliseconds. Missing this causes the source system to filter at second precision, leading to data gaps.
Pitfall 2: Setting page_size too high and triggering rate limiting. The default 20 is safe; some engineers push it to 200 or 500 for speed, only to be rate-limited by the source and trigger massive retries on Qeasy. The stable approach is to load-test before adjusting.
Pitfall 3: No centralized code mapping. Mismatched codes across the two systems are the norm. We recommend maintaining a dedicated "code mapping table" in Qeasy, managed by its own strategy, while material strategies only reference it. One fix then propagates everywhere.
Pitfall 4: Detail API toggle confusion. detailAPI is a reserved switch. Some projects enable full detail calls from day one, doubling QPS. We suggest keeping detail calls off when the list response is sufficient, and triggering them per material code only when specification fields are missing.
Pitfall 5: Ignoring the "incremental and full dual-track" approach. Keep a "full reload" entry point during early go-live. If source timestamps ever get corrupted, a one-click backfill can save the day — do not wait until things break to build it.
When to Use and When Not to Use
This strategy fits: supply chain integration scenarios where Kingdee YXC is the material master source, incremental sync by modification time is required, and multiple downstream systems share the master data. It does not fit: scenarios requiring real-time reflection of material changes to the front-end business system — in that case, switch to event-driven or message-queue architectures; nor light scenarios with very few materials (below hundreds) — a one-time full initialization is sufficient.