Querying Kingdee Materials: A Practical Guide to Incremental Master Data Sync with Qeasy

What This Strategy Solves

Distributing material master data from Kingdee YXC to the marketing cloud looks like a simple "query + write" action, but what really troubles enterprise IT teams is never whether a single record can be written, but rather: how to set the incremental starting point, how to patch the modification time window, how to avoid missing data across pages, and how to compensate when out of sync. In one real project, we used the Qeasy data integration platform to host this link, packaging "Query Kingdee Materials" as an independently observable, rerunnable, and compensable sync strategy. Three months later, the material codes and names on both sides stayed consistent, and the operations team never came back to reconcile numbers with us.

Data Flow and Field Mapping

The overall flow is "Source System (A) → Middle Layer (Qeasy) → Target System (B)". The middle layer does not store raw data; it only handles pulling, transforming, writing, and status recording.

Key source-side fields: code (number, used as idempotent primary key), primary key (id, with idCheck enabled), modification time range (modify_start_time / modify_end_time, millisecond timestamp), pagination parameters (page, page_size, default 20). The target side only serves as a receiving placeholder in this demo. In real deployment, map number to the marketing cloud material code, map id to the external system unique key, and convert classification fields like parent_name as needed.

buildModel=false means this strategy does not rely on Qeasy's automatic modeling; the field mapping table is maintained manually by the integration engineer. This is also the common "centralized code mapping management" pattern among Qeasy customers—keeping the mapping table inside the strategy rather than scattered across script snippets.

How to Configure on Qeasy

Step 1: Register platforms. Register Kingdee YXC and the marketing cloud as external platforms in Qeasy, and note down the platform_id. All palatom references in subsequent strategies will use these two IDs. Note that platform_id is platform-level rather than tenant-level; reuse the same platform definition across tenants to reduce duplicate configuration.

Step 2: Build the source action. Create a query action, select API /jdy/v2/bd/material, method GET, and map the four request fields one by one: modify_start_time uses the variable {{LAST_SYNC_TIME}}000, modify_end_time uses {{CURRENT_TIME}}000 (append three zeros to convert a second-level timestamp to milliseconds), page is set to 1, page_size is set to 20. Make sure idCheck=true is enabled—idempotent deduplication later depends on it.

Step 3: Build the target action. In this strategy, the target side is just a "write no-op" placeholder. Fill the API as write no-op, method POST, number/id both set to 0, which is enough to get the whole link working. In real deployment, replace this with the marketing cloud material master data write API.

Step 4: Chain into a strategy and configure scheduling. Chain the two actions into one strategy, source before target. Use crontab */16 8-22 * * * for the source (every 16 minutes during business hours) and 23 2 * * * for the target as a nightly fallback write, forming a "daytime incremental + nighttime compensation" dual-track rhythm.

Implementation Steps

Phase 1: Determine the incremental starting point. Before the first run, manually initialize LAST_SYNC_TIME in Qeasy to the millisecond timestamp at the moment when the historical full import was completed, to avoid re-pulling everything.

Phase 2: Full trigger and reconciliation. Manually run a "full patch" once, then do a bidirectional comparison of material counts and codes against the marketing cloud. Resolve any differences before turning on the incremental.

Phase 3: Phased scheduling go-live. Pull incrementals during the day per */16 8-22 * * *, and run a fallback rerun at 02:23 AM. Attach the target write action to the off-peak hour window to avoid hitting rate limits on the marketing cloud during high-frequency daytime writes.

Phase 4: Monitoring and alerting. Watch three graphs in Qeasy: "rows pulled / rows written / rows failed". Alert if any of them stays at zero for more than 30 minutes, to prevent silent source-side failures.

Lessons from the Trenches

Pitfall 1: Forgetting to append zeros for millisecond timestamps. The Kingdee interface requires millisecond precision, but Date.now() in JavaScript is already in milliseconds while Math.floor(Date.now()/1000) is in seconds. Passing a second-level timestamp directly causes the interface to filter around "1970", leaving the whole window empty. This is an easy place to crash; the safe approach is to use an expression in Qeasy to append 000 uniformly.

Pitfall 2: Default page_size is 10. The material clearly states "page_size default is 10", but with a sync frequency of every 16 minutes, 100 rows per round may not even be enough when material volume is large. A typical mistake is forgetting to override the default, which doubles pages and API calls, triggers rate limits, and collapses the entire link. The recommended practice is to explicitly set 20 or higher, capped by the interface upper limit.

Pitfall 3: Deduplicating without idCheck. In incremental scenarios, the same record may be pulled multiple times (overlapping time windows, cross-page boundaries). Without deduplication, duplicate materials appear. idCheck=true is Qeasy's built-in deduplication switch—make sure it is enabled.

Pitfall 4: Crontab timezone drift. The crontab */16 8-22 * * * uses the Qeasy platform's timezone. If the Kingdee server is in a different timezone, materials in the early-morning window may be missed. The safe approach is to convert all source-side timestamps to UTC and store them in LAST_SYNC_TIME.

Pitfall 5: Target write action scheduled during the day. Writing material master data into the marketing cloud triggers downstream cache refreshes; doing this during daytime high concurrency can take the marketing cloud down. A common customer pattern is "header/body staged processing". This strategy belongs to the header (master data) and is placed in the off-peak hour, separated from the body writes of sales orders.

Applicable and Non-Applicable Scenarios

Applicable: Incremental distribution of master data such as materials, customers, and warehouses, where the source provides a query interface that filters by modification time and the target has idempotent write capability. Not applicable: Real-time inventory changes requiring second-level freshness (should use a real-time inventory sync strategy), legacy interfaces without a modification time field, and offline full initialization of large tables that the source cannot paginate (should use a separate offline batch strategy).