Querying Kingdee Items: A Single-Strategy Playbook for Pulling Item Master Data
What This Strategy Solves
Keeping item master data consistent between an ERP and the marketing cloud is the foundation for downstream orders, inventory, promotions, and pricing to behave correctly. A retail enterprise we worked with keeps its item master in Kingdee Cloud X星辰, while the marketing cloud needs the latest catalog for store assortment, promotion binding, and campaign review. The "Query Kingdee Items" strategy implemented on the Qeasy Data Integration Platform does exactly that: it pulls records incrementally by modification time and writes them into the marketing cloud, preventing SKU drift, duplicate maintenance, and scattered code mappings.
Data Flow and Field Mapping
Flow: Kingdee Cloud X星辰 (source) → Qeasy (middleware) → Marketing cloud (target).
The source is Kingdee's material WebAPI (GET). It queries by modification-time window and pagination. Typical request fields:
| Field | Meaning | Value |
|---|---|---|
| modify_start_time | Start timestamp (ms) | {{LAST_SYNC_TIME}}000 |
| modify_end_time | End timestamp (ms) | {{CURRENT_TIME}}000 |
| page | Current page | Default 1 |
| page_size | Page size | 20–50, tune by load test |
The middleware layer does two things: it binds millisecond timestamps to platform time variables, and it treats the Kingdee id as the business primary key (the source explicitly sets idCheck=true). Nested response fields such as parent_name are flattened for downstream dispatch.
The target points to the marketing cloud's item-write endpoint, where Qeasy writes the prepared item records.
How to Configure It in Qeasy
The strategy consists of three artifacts: source metadata, target metadata, and a scheduling policy.
In the source metadata, point to Kingdee's material query API. Inject modify_start_time and modify_end_time from platform time variables. Set number to Kingdee's material code, and use id as the idempotency key. Enable autoFillResponse=true so the platform pre-maps returned fields into readable names.
In the target metadata, point to the marketing cloud's write endpoint. We recommend a pattern Qeasy customers often adopt: "centralized code mapping." Keep the Kingdee-code-to-marketing-cloud-SKU mapping in Qeasy's mapping dictionary instead of duplicating it inside every strategy. When a new SKU class is added, only one place changes.
Configure the write action as an idempotent upsert keyed on id, and rely on Qeasy's built-in retry and alerting to keep the pipeline stable.
Implementation Steps
The rollout has three phases.
Phase one — incremental start point. Before going live, run a one-shot script that backfills LAST_SYNC_TIME to the earliest known modification time, so the first run does not flood the marketing cloud with the entire history. After that, switch to normal incremental mode.
Phase two — full-volume trigger. In addition to daily incremental runs, keep a periodic full-volume reconciliation entry (for example, monthly). It pulls the complete item list by code, diffs it against the marketing cloud, and resyncs anything missing. This is the typical "incremental plus full-volume dual track" pattern.
Phase three — scheduling cadence. Source scheduling is set to */16 8-22 * * * (every 16 minutes during business hours); the target bulk write fires daily at 02:23. Business hours run near-real-time for store operations, while the overnight batch locks down consistency. The two rhythms are offset.
After going live, observe pull volume, failure rate, and map-hit rate for one week, then tune page_size and the time window to match real traffic.
Field-Tested Lessons
First, never guess the timestamp unit. Kingdee's API wants milliseconds, but Qeasy's default time variable is seconds. Append three zeros ({{LAST_SYNC_TIME}}000) — omitting them is a classic cause of an empty window.
Second, larger page_size is not always better. Item master records carry category, unit of measure, and multilingual fields. A page that is too large can trigger Kingdee-side timeouts or Qeasy-side memory churn. Start from 20, load-test, then adjust based on observed latency.
Third, centralize code mappings. We have seen projects where every sync strategy maintained its own Kingdee-code-to-SKU mapping; later, changing one category required editing a dozen places. Qeasy's mapping dictionary exists precisely to avoid this — manage once, change once.
Fourth, always enable idCheck. With idCheck=true, Qeasy uses the Kingdee id as the idempotency key, so overlapping time windows never produce duplicate SKUs in the marketing cloud.
Fifth, align scheduling windows with business hours. Item creation and edits concentrate before opening and around lunch. Scheduling too aggressively just wastes quota. The safer pattern is high frequency during business hours, low frequency or paused outside them.
When to Use and When Not to Use
Use it when: item master is owned by a single ERP, the marketing cloud only reads; near-real-time sync by modification time is acceptable; SKU volume stays within hundreds of thousands and the systems are clearly delineated.
Do not use it when: both sides maintain the catalog and write to the same store; compliance scenarios require a formal approval workflow before landing; or the source API cannot do time-based incremental queries and only supports full exports — those cases need file-based full exchange instead of this strategy.