Single-Strategy Tutorial: Incremental Pull of Item Master Data from Kingdee YXC

What this strategy solves

In retail and distribution scenarios, item master data lives in different systems: one in the e-commerce mid-platform, another in the ERP, and the encoding conventions often drift apart. In a real project, the customer reported that the item master had diverged between the two sides. Operators had to switch between two systems to look up a single SKU, and after three months the numbers no longer matched. This strategy does just one thing: pull incremental item data from the upstream ERP by modification time, centralize it, and use it as the single source of truth for the subsequent writes and distribution. It does not perform complex writes directly; it first makes sure that data is consolidated in one place.

Data flow and field mapping

The data flow is a unidirectional pull: Kingdee YXC -> Qeasy Data Integration Platform.

In the source response, number is the item code and id is the internal primary key. Both have idCheck=true enabled for idempotency and resumable transfer inside Qeasy. The intermediate layer does not perform heavy business cleansing; it simply forwards the number/id pair to the target action (Write Empty Operation, a marker), preparing the snapshot for the real downstream write strategy.

How to configure it on Qeasy

1. Source connection: Register a Kingdee YXC V2 connector in the Qeasy platform, fill in code as Kingdee.YXC, and configure the tenant and API domain.
2. Strategy modelling: Create a strategy, pick the QUERY effect, and bind the source metadata above. The source api points to /jdy/v2/bd/material, with method=GET.
3. Parameter binding: Bind the two timestamp parameters to the platform's built-in LAST_SYNC_TIME / CURRENT_TIME variables; let the Qeasy paginator handle paging automatically instead of writing loops.
4. Target connection: Pick Qeasy itself (datahub) as the target, using a placeholder execution like Write Empty Operation. The goal is to open up the data path first; subsequent real write strategies can reuse the same data snapshot.
5. Idempotency: Enable idCheck=true so the platform deduplicates on number + id. Retries after network jitter will not create dirty data.
6. Response modelling: Keep autoFillResponse=true; the platform generates fields from the first response, and you can fine-tune them later.

Implementation steps

• Initial full pull before go-live: Set LAST_SYNC_TIME to a timestamp far earlier than the system's launch time (for example, the Unix epoch) and run one full pull to bring the item baseline into the Qeasy intermediate layer in one shot. This "archive" step must come first.
• Scheduling frequency: After stabilization, run every 5 minutes (*/5 * * * *). The window is always "last successful time -> current time". Adopt a dual-track approach of incremental plus full: incremental handles daily deltas, while a full pull is manually triggered for backfill on anomalies.
• Resumable transfer: Qeasy records the end timestamp of every successful run, so retries only backfill the missing window and never re-pull duplicates.
• Monitoring: Watch the API latency, returned row count, and empty-response frequency. Empty responses usually mean the upstream has no changes and are normal; consecutive empty responses warrant a check on the timestamp format.
• Extension: When later wiring this data into a real downstream system, simply add another execution strategy that reuses the same intermediate data instead of calling the source API again.

Pitfalls from real projects

1. Forgetting the millisecond zeros: {{LAST_SYNC_TIME}}000 sounds natural, but many wrappers return second-level timestamps by default. Once the three zeros are missed, the API receives an enormous value and rejects the parameter as invalid. A safe practice is to write a fixed rule in the Qeasy variable transformer.
2. Hard-coding the page parameter to 1: Hard-coding page to 1 is fine because the Qeasy paginator takes over; however, some engineers write their own paging scripts, which bypasses the platform mechanism and is painful to debug later.
3. Duplicate data after turning off idCheck: As soon as idempotency is disabled, network jitter causes trouble. A typical mistake is thinking "the test environment doesn't need idempotency"; switching to production then produces duplicates. A common pattern among Qeasy customers is centralized encoding mapping, governed on the platform side rather than scattered across every strategy.
4. Pushing complex writes into the target: Trying to write the items to downstream systems in this step couples source pulling with business writing. A safe practice is separate header from body in phases: this strategy only handles pulling and landing into the intermediate layer, while the real writes start in another strategy.
5. Cron expression causing long empty windows: The target strategy in the source material uses 1 1 1 1 1 (at 01:01 every Monday), which suits weekly compensation; using it for daily incremental sync leads to long window accumulation. Pick the frequency based on data change volume.

Where it fits and where it does not

Fit: item master needs to be centralized from the ERP for distribution to many consumers with complex write logic, and you want to aggregate the data before fanning out; the upstream API supports querying by modification time. Not fit: sub-second real-time sync; the upstream API has no modification-time field so it can only be polled in full; or the downstream needs business-computed results in a single step.