Kingdee Cloud Material Master Push to MES: A Single-Strategy Sync Tutorial

What This Strategy Solves

Material master data is the shared dictionary between ERP and MES. In one real engagement, a manufacturer treats Kingdee Cloud as the single source of truth for materials and requires every new or modified material to land in MES within an hour. Once codes or categories diverge, shop-floor picking, BOM binding, and inventory deduction all break. We used the Qeasy data integration platform to host this "material sync" as an independent strategy, so that any change on the source side becomes visible on the target side within one hour.

Data Flow and Field Mapping

The flow is straightforward: Kingdee Cloud (BD_MATERIAL) → Qeasy middleware → MES (/api/createMaterialInfo). The source side pulls materials through executeBillQuery, the middleware performs field mapping and filtering, and the target side writes data after an idCheck=true validation.

Key field mapping:

Target Field	Source Field / Rule	Mapping Type	Notes
materialUuid	FMasterId	DIRECT	Kingdee material PK as MES material UUID
partNo	FNumber	DIRECT	Material code
gradeName	FName	DIRECT	Material name
spec	FSpecification	DIRECT	Specification
classifyNo	FMaterialGroup	DIRECT	Category UUID, depends on category sync
parentClassifyNo	FMaterialGroup	DIRECT	Top-level category, usually same as classifyNo
unitUuid	FBaseUnitId	DIRECT	Unit UUID
purchaseUnitUuid	FBaseUnitId	DIRECT	Purchase unit, same as base unit
erpClassifyCode	FCategoryID.FNumber	DIRECT	Inventory category code passthrough
companyCode	Fixed constant	CONSTANT	Company code

A few points worth noting: both classifyNo and parentClassifyNo take FMaterialGroup directly — this creates a hidden dependency: the material category strategy must run first. Fields like quality, brand, and picNo are currently empty constants and can be extended later as needed.

How to Configure on Qeasy

On Qeasy, this strategy has four typical configuration points:

Source settings: platform = Kingdee.Cloud, API = executeBillQuery, form BD_MATERIAL, pagination Limit=2000, TopRowCount=0 to skip total-row count and reduce overhead.
Filter conditions: the source WHERE clause is fixed as FUseOrgId.fnumber='100' AND FModifyDate>='{{LAST_SYNC_TIME}}' AND FMaterialGroup.FNumber!='virtual'. All three conditions are required: organization scope, incremental timestamp, and excluding virtual materials.
Target settings: platform = the MES, API path /api/createMaterialInfo, idCheck=true, materialUuid + partNo as the deduplication key.
Centralized code mapping management: this strategy does not enable _findCollection or _mongoQuery; all target fields are DIRECT or CONSTANT. If the MES unit UUID format later diverges from Kingdee's, add a unit mapping table in Qeasy's "Code Mapping" feature instead of scattering mappings across strategies — this is one of the common patterns among Qeasy customers.

Implementation Steps

We recommend a three-step rollout:

Step 1: Initialize the incremental starting point. Before the first go-live, do a cold start on the Kingdee side with FModifyDate>='some baseline time' to backfill historical materials. Qeasy automatically records the maximum modification time in LAST_SYNC_TIME, and subsequent runs continue the increment from there.

Step 2: Trigger a full-load run. On customer sites we usually recommend a manual full-load validation run during the off-peak early morning to confirm both sides agree. Qeasy supports a manually triggered "full re-run" that automatically writes back LAST_SYNC_TIME once finished.

Step 3: Scheduling frequency. The source provides crontab: * 7-22 * * *, meaning every hour on the hour from 07:00 to 22:00. Material master data does not change every second, so hourly scheduling is sufficient; if business needs faster turnaround, compress to every 30 minutes, but going below 15 minutes is generally discouraged because it can exhaust the source API quota.

One critical dependency: the material category strategy must run before this strategy. Since classifyNo directly takes FMaterialGroup as the category UUID, if categories have not been pushed yet, materials will reference non-existent category UUIDs.

Pitfall Retrospective

Material category strategy not yet running when material strategy goes live. A typical mistake is "launch both strategies together." The safe approach is phased rollout: run material categories first, watch for one week with no issues, then enable material sync.
Forgot to exclude virtual materials. The source material explicitly states FMaterialGroup.FNumber!='virtual', but on customer sites some engineers copy the strategy and drop this line, leaving the MES full of virtual materials that are painful to clean up later.
Misunderstanding the modification time field. Kingdee's FModifyDate is "last modification time." If a user un-approves, modifies, and re-approves a record, this timestamp updates. If the business requires "sync only after approval," switch to FAuditDate instead — another common pitfall.
Pagination parameter TopRowCount=0 is easy to mis-edit to 1 or 100. Changing it to non-zero forces the source to return a total count, which significantly slows first-page rendering on large tables. Keep it at 0.
Wrong constant for company code. The source material provides a fixed constant for companyCode, but in real projects this value usually differs per organization and must be updated when the customer switches organizations. Instead of hard-coding, drive it from the current user's organization dynamically.

Applicable and Non-Applicable Scenarios

Applicable: Kingdee is the single source of truth for materials, the MES category/unit IDs are compatible with Kingdee IDs, and the business needs to sync only one organization in a multi-org environment. Not applicable: when MES and Kingdee use completely different ID systems (heavy COLLECTION mapping required), when material changes must be visible within seconds (use a change-notification mechanism instead), or when the material data source itself is the MES side (reverse the flow direction).