Kingdee Material Group to MES Material Classify: A Single-Strategy Sync Tutorial
What This Strategy Solves
Syncing material master data from Kingdee to MES looks simple, but if the classification hierarchy is not established first, the downstream material sync will fail in bulk. The reason: material APIs require classifyNo and parentClassifyNo, and those values must exist in the material classification table first. In one real project, the client skipped this step, the material sync failed entirely, and it took two days to trace the root cause. This strategy is precisely about laying down the "classification skeleton" before material sync runs.
Data Flow and Field Mapping
Data flows from Kingdee Cloud to the MES. The source invokes executeBillQuery against the AMB_MaterialGroup form, pulled in full (no FilterString), transformed through the Qeasy iPaaS middle layer, then POSTed to the MES /api/createMaterialClassify endpoint.
| Target Field | Source Field / Rule | Mapping Type | Note |
|---|---|---|---|
| companyCode | Fixed constant | CONSTANT | Company code |
| classifyNo | FID | DIRECT | Material classify serial, uses Kingdee inner ID |
| parentClassifyNo | _function case when '{{FPARENTID}}'='0' then '' else '{{FPARENTID}}' end | TRANSFORM | Empty for root, otherwise parent FID |
| classifyName | FNAME | DIRECT | Name passthrough |
| classifyCode | FNUMBER | DIRECT | Code passthrough |
For the primary key, the business key is FNUMBER; the idempotency key is the composite {{FID}}-{{FNUMBER}} with idCheck enabled so re-runs do not dirty the target.
How to Configure on Qeasy
Create a new strategy on the Qeasy platform. Pick Kingdee Cloud as the source and the MES API as the target, with sync mode QUERY → EXECUTE. Use platform variables {{PAGINATION_PAGE_SIZE}} and {{PAGINATION_START_ROW}} for source pagination; set TopRowCount to 0 (skip the total row count to keep the payload small). The company code on the target side is a constant. The most critical point is parentClassifyNo: do not map it directly — use the _function expression to handle the root node.
A common pattern among Qeasy customers is to centralize encoding mappings in the middle layer. This strategy does not use _findCollection because material group itself is the dependency root; there is no upstream to look up. Still, keeping all mapping rules inside the strategy means that when MES classification rules change, you only edit one place.
Implementation Steps
Follow the "classification first, material second" principle, in three phases:
- Full initialization: On first go-live, push all Kingdee material groups at once, then manually inspect the classification tree in MES.
- Schedule activation: Set crontab to
* 7-22 * * *, covering business hours; leave the night window for MES-side index rebuilds. - Downstream handoff: Once the classification tree is stable, activate the "Kingdee material → MES" strategy, and in that strategy, point classifyNo / parentClassifyNo lookups to the output of this strategy.
Incremental + full dual-track is another common pattern at Qeasy customers. This strategy is currently configured as full pull without FilterString, suitable for classification volumes of a few hundred to a few thousand. If the volume grows significantly, you can switch to incremental by FModifyDate.
Pitfalls from the Field
- Hard-coding root FPARENTID as the string '0': This is where it goes wrong. The MES API requires the first-level parent to be an empty string, not '0'. You must use _function for conditional branching — do not pass FPARENTID directly for convenience.
- idCheck not enabled: A typical mistake is forgetting to enable key validation. As a result, every hourly run POSTs the same classification again. MES deduplicates, so logs show 200s, masking real failures.
- Wrong order: Material sync starts before classification sync, so material writes cannot find their parent and throw errors in bulk. The safe approach is to let the classification strategy run alone for two days, confirm the MES tree is complete, then enable material sync.
- TopRowCount set to 1 by mistake: This makes the source response carry an extra total-row field, which triggers odd pagination behavior in some Kingdee versions. Keep it at 0.
- Wrong companyCode constant in private deployment: Before go-live, always check the MES-side sample value and match it to the actual Kingdee book. Do not copy the constant from a test environment.
When This Fits, and When It Does Not
Fit: private deployment scenarios where the classification volume is in the thousands, the Kingdee group structure is stable, and you need to lay the groundwork for downstream material sync. Not fit: high-frequency scenarios with frequent group changes requiring minute-level sync, or architectures requiring bidirectional classification sync between two systems — for the latter, build a separate conflict-resolution strategy instead of stuffing reverse sync into this one.