Deep Dive Tutorial on the [Linked Query] Kingdee Item Query Strategy: Time-Window Incremental Pull and Landing Design

What This Strategy Solves

In a supply chain integration at one retail enterprise, item master data is the foundation for every downstream document (sales outbound, purchase inbound, transfers). Once an item is renamed, its unit changed, or its barcode updated on the source side, those changes must be pulled back to the integration platform promptly, otherwise downstream documents drift apart and "the numbers on both sides never match."

The [Linked Query] Kingdee Item Query strategy we run on the Qeasy data integration platform aims at one specific thing: incrementally pull item master data from Kingdee Cloud Xingchen V2 by modification time, land it on the integration platform's intermediate layer, and provide clean, unified, status-bearing master data for the follow-up push to WDT.

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

The data flow is straightforward: Kingdee Cloud Xingchen V2 (source) → Qeasy integration hub (intermediate layer) → subsequent strategies push to WDT. This single strategy only covers the first two legs.

On the source side we use Kingdee Cloud Xingchen V2's /jdy/v2/bd/material API, a GET endpoint that returns the item master list, paired with /jdy/v2/bd/material_detail for line-level details. The table below shows the most important fields involved in this strategy:

One thing worth highlighting: the trailing 000 on the millisecond timestamp is mandatory. The Kingdee field is documented as a string but semantically expects milliseconds; if you pass a second-level timestamp it is silently ignored by the server.

How to Configure on Qeasy

On the Qeasy integration platform, this strategy is modeled as a "source query + landing no-op" pipeline:

1. Source platform node: select Kingdee Cloud Xingchen V2, pick /jdy/v2/bd/material, set Effect=QUERY and Method=GET.
2. Bind the incremental variables: modify_start_time to {{LAST_SYNC_TIME}}000, modify_end_time to {{CURRENT_TIME}}000. This binding is the lifeline—get it wrong and the pull returns an empty set or a full dump, and troubleshooting eats hours.
3. Linked detail hook: in otherRequest, set detailAPI to /jdy/v2/bd/material_detail. Each number/id returned by the list API will automatically trigger a detail fetch as needed.
4. Target platform node: pick the Qeasy integration hub itself, use the "write no-op" API, set Effect=EXECUTE and Method=POST. Set number/id to 0 and keep idCheck=true; its job is to land upstream data into the intermediate store.
5. Auto response modeling: with autoFillResponse=true on the source, you skip manual table building. Still, after the first successful run, go through and manually verify the detail fields once.

This is one of the most common patterns we see with Qeasy customers: centralized code mapping + header/body staged handling. First this strategy aligns the "skeleton" of the item master, then subsequent push strategies match WDT by code.

Implementation Steps (Phased Scheduling)

We recommend breaking the first cutover into three phases:

• Phase 1: full dump trigger. Manually set {{LAST_SYNC_TIME}} to the business starting point (for example, the go-live date of the retail enterprise's platform) and {{CURRENT_TIME}} to now, then run manually to pull historical master data into the intermediate layer in one go. Always do this during business off-peak hours.
• Phase 2: fix the incremental anchor. After the full dump completes, switch {{LAST_SYNC_TIME}} back to "last successful sync time" and enter incremental mode from there.
• Phase 3: scheduling cadence. Source crontab is 15 3 * * * (03:15 daily), and the target no-op crontab is 23 2 * * * (02:23 daily). The landing action runs before the next query's context update, forming a stable two-track rhythm.

If the intermediate layer requires heavier cleansing (unit conversion, multilingual names, etc.), you can insert a lightweight mapping script between the source and target nodes. This single strategy only solves the "pull back and land" leg.

Lessons Learned

1. Forgetting to multiply the timestamp by 1000. A classic mistake: someone passes a second-level timestamp directly, the server returns an empty list "without an error", and half a day is wasted on investigation. The safe approach is to concatenate the 000 suffix right inside the Qeasy request parameters and to use Postman once during self-test to eyeball the millisecond timestamp.
2. The default value of page_size gets misused. Kingdee's default page_size=10 is too small and causes too many paginated round trips. We fix it at 20, which is the sweet spot for performance and stability; going higher risks hitting server-side rate limits.
3. detailAPI is left unconfigured, leaving the body empty. Kingdee master data has a header + body structure. Only configuring the list API makes it look like "it ran fine", but the downstream push strategy ends up with an empty body. detailAPI must be explicitly written into otherRequest.
4. The first full dump accidentally triggers downstream WDT strategies. A full pull usually does not use idCheck validation, but downstream strategies still react via linkage. At the customer site we temporarily stopped downstream strategies during the full-dump phase, and only re-enabled them after the intermediate layer was verified clean.
5. LAST_SYNC_TIME jumps across the day boundary. If the schedule fires at dawn and the source side has cross-day writes, the last minute of data tends to be missed. We place the source crontab at 15 3 instead of on the hour precisely to leave a 15-minute buffer at the boundary.

When to Use and When Not to Use

Use it when item master changes occur at a moderate cadence (tens to thousands per day) and when downstream strategies (for example, pushing items to WDT) depend on a unified code on the intermediate layer. Do not use it when Kingdee-side changes are over 50,000 per day and need near real-time (minute-level) reflection—at that scale, message queues are a better fit than HTTP polling. It is also not a fit for older Kingdee APIs that lack a modify_start_time field; in that case fall back to full reconciliation.