Qeasy Cloud
Get Started

Master Data Sync to Kingdee Cloud: A Practical Tutorial on the Material Query Strategy

· 谢锴斌· Integration Solutions· 48 views· 4 min read
WDTKingdee Cloud物料主数据executeBillQuery轻易云供应链集成定时调度

What This Strategy Solves

In a real retail engagement we kept running into one awkward symptom after material master data was pushed from the source ERP/WMS into Kingdee Cloud: the write API returned success, yet downstream modules (purchasing, sales, inventory) still saw the material as "unaudited" or "temporary" a few minutes later. The root cause is that Kingdee Cloud commits material saves asynchronously, and several fields depend on organization-level configuration writes. If you reuse the write response as the source of truth for downstream fan-out, the data "looks persisted but isn't really in effect."

The approach we took on the Qeasy data integration platform (轻易云数据集成平台) was to add a dedicated strategy: after the material write finishes, schedule a re-query against Kingdee's material API (validated by FNumber / FMasterId), and use a "query-then-redistribute" chain so downstream consumers only ever read the confirmed, persisted version. This tutorial walks through that single strategy in depth.

Data Flow and Field Mapping

The end-to-end chain is Source System → Qeasy Middle Layer → Kingdee Cloud (re-query source) → Qeasy Middle Layer → Downstream Consumers. In this strategy, Kingdee Cloud is both the system being queried and the authoritative source of the material data.

DimensionSource (Query Request)Middle Layer (Qeasy)Target (Kingdee executeBillQuery)
APIInternal triggerScheduled jobexecuteBillQuery (POST)
Primary keysFMasterId / FNumberPass-throughFNumber (code), FMasterId (internal id)
Org fieldsFCreateOrgId.FNumberPass-throughCreating org, Using org (both required)
Business switchesFIsBatchManage / FIsKFPeriodPass-throughBatch management, Shelf-life period
Response direction—Full row write-backFMasterId (dedup key)

All request fields on the source side use value directly referencing the field name (e.g. FMasterId, FNumber, FCreateOrgId.FNumber). Kingdee's metadata model automatically expands these values into query conditions that include the organization internal id. The idCheck=true flag tells the middle layer to deduplicate by FMasterId, preventing the same material from being consumed by downstream twice.

How to Configure It on Qeasy

On the Qeasy data integration platform, this strategy is modeled as a "source → target" pair of configurations:

Source side (reading Kingdee Cloud)

  • Source platform: Kingdee Cloud (Kingdee.Cloud)
  • Metadata API: executeBillQuery, type QUERY, effect QUERY
  • HTTP method: POST
  • Number key: FNumber, internal id: FMasterId
  • buildModel=true: Qeasy automatically builds the request model from the request fields
  • Each request field is described via field / label / type / is_required, and value references the Kingdee field name directly (e.g. FCreateOrgId.FNumber)

Target side (downstream fan-out placeholder)

  • Source platform: Qeasy integration platform (datahub)
  • Metadata API: "Write no-op" (WebAPI / EXECUTE / POST)
  • idCheck=true, both number and internal id set to 0
  • This side does not actually write to a third party; it only acts as the scheduling landing point and the subscription entry for downstream

On crontab, the source side is defined as 08 01,03 * * * (01:03 and 03:08), and the target side as 23 2 * * * (02:23). The two schedules are deliberately staggered so they don't fight for the Kingdee connection pool and so downstream has a clear consumption slot.

Implementation Steps

Putting it into production, we usually go through four phases:

  1. Modeling and connectivity verification: register both metadata blocks in Qeasy, then run executeBillQuery with a single FNumber and confirm the FMasterId is returned correctly.
  2. Incremental starting point: take the last modification time of materials as a boundary and run a one-off full re-query over the existing stock by FNumber list, so downstream has a cold-start baseline.
  3. Dual-track scheduling go-live: day-to-day use the incremental window (by modification time), and trigger a full re-query on a fixed weekday or month boundary to reconcile counts and statuses — the classic "incremental + full double track" pattern we see across Qeasy customers.
  4. Schedule frequency tuning: observe Kingdee's response latency and connection pool usage, and stagger the 01:03 / 03:08 slots so they don't collide with upstream write strategies.

Code mappings are maintained centrally in Qeasy's mapping table. When a new organization or material type is added, only one place needs to be touched — this is the reason many customers stay stable even six months after go-live.

Pitfalls and Lessons Learned

  • Reusing the write response directly: the classic mistake is to take the FMasterId from the save response and fan it out immediately. Kingdee backfills some fields (organization, batch management, shelf-life) asynchronously, so the safe pattern is persist first, re-query on a timer, then redistribute.
  • Required org fields left blank: FCreateOrgId_FNumber and FUseOrgId_FNumber are required by executeBillQuery; missing them fails the whole batch. We inject both values as constants during the request assembly stage on Qeasy instead of relying on upstream.
  • idCheck accidentally disabled: if idCheck is off, the same material will be treated as multiple new records by downstream within the same window and trigger duplicate documents. Our approach is to use FMasterId as the idempotency key and deduplicate at the middle layer.
  • Schedule colliding with writes: this strategy's crontab runs in the early morning, but if the upstream write strategy also runs at the same hour, Kingdee's connection pool fills up fast. Staggering the two by 20-30 minutes basically eliminates timeout circuit breakers.
  • Batch/shelf-life switches back-filled out of order: FIsBatchManage and FIsKFPeriod are back-filled with a delay; you can't judge them based on the source system push result alone, you must wait for the re-query confirmation.

When to Use It and When Not To

Use it when material master data must be redistributed to multiple downstream systems (purchasing, sales, e-commerce mid-platform, WMS) only after Kingdee Cloud has authoritatively persisted it, and when those downstream systems are sensitive to "temporary/unaudited" states.

Don't use it when downstream can tolerate consuming the write response directly and does not require synchronization against the latest confirmed version, or when the material volume is so small that staggered scheduling brings no value.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-wdt-kingdee-cloud-4337-new-de64ee08

Comments