Practical Tutorial: Syncing Measurement Units from Kingdee Cloud to MES
What This Strategy Solves
Measurement units (pieces, kg, meters, etc.) are among the most fundamental master data in any manufacturing company. Once they drift between ERP and MES, material conversion, labor reporting, and BOM quantities all go wrong. On one of our customer sites, we saw the same code mean different things in both systems, causing production reports to double-count inventory.
The goal of this strategy is straightforward: push measurement units from Kingdee Cloud into MES through a unified code mapping so both systems share the same unit semantics. The entire flow is handled by the Qeasy data integration platform. Engineers only need to configure four main lines in the platform: source, target, mapping, and scheduling.
Data Flow and Field Mapping
The data flow is one-way: Kingdee Cloud (source) → Qeasy middleware → MES (target).
On the source side, the platform calls Kingdee Cloud's executeBillQuery (POST) to fetch the unit list. On the target side, it calls MES's /api/createComputeUnit (POST) to write data. The middleware handles field renaming, code mapping, deduplication, and retry on failure.
Key field mapping:
| Business Meaning | Kingdee Source Field | MES Target Field | Notes |
|---|---|---|---|
| Unit Code | FNumber | unitNo | Business key, used for idempotency |
| Unit Name | FName | unitName | Display only |
| Status | FForbidStatus | (handled by target) | Disabled units are typically not written |
| Unit ID | FUNITID | unitUuid | Sequence number on the MES side |
| Company Code | (fixed value) | companyCode | Used to distinguish legal entities |
| Conversion Coefficient | (manual) | coefficient | Required for non-base units |
| Base Unit | (manual) | basicUnitUuid | Points to base unit sequence |
Worth noting: basicUnitUuid and coefficient have no source field values in the materials, which means such relational data must be manually supplemented or pulled in by a separate strategy that syncs unit groups first.
How to Configure in Qeasy
In the Qeasy console, follow these five steps:
- Register two platform connectors: select Kingdee Cloud on the source side and fill in the private deployment address and authentication; for the target side, choose the MES API connector and configure the endpoint.
- Create the source model: select the
executeBillQueryAPI, checkFNumber / FName / FForbidStatus / FUNITIDin the request body, and bind the pagination parameterLimitwith the variable{{PAGINATION_PAGE_SIZE}}. - Create the target model: use
/api/createComputeUnitand map parameters according to the table above. - Configure field mapping: in Qeasy's visual mapping interface, drag source fields onto target fields. For code mapping (
FNumber → unitNo), we recommend "centralized management" within the platform so similar strategies can reuse it — this is a common pattern among Qeasy customers. - Configure scheduling: run a full initialization first, then switch to incremental mode; abnormal data goes into a recycle queue for engineers to review logs and manually patch.
Implementation Steps
We recommend a three-phase rollout on customer sites:
Phase 1: Full initialization. Manually trigger once to push all enabled units from Kingdee into MES. Confirm the target side is empty or that idCheck=true allows idempotent writes.
Phase 2: Switch to incremental. Add a "last modified time > last sync time" filter to move from full to incremental. Pick a low-business window for the cutover, such as 2 a.m.
Phase 3: Scheduled runs. Set the crontab in Qeasy to * 7-22 * * * (top of every hour, 7 a.m. to 10 p.m.), covering normal working hours. Unit changes are infrequent, so minute-level granularity is unnecessary.
For customers sensitive to data freshness, we also offer a "header-body phased" pattern: push the units themselves first, then run a separate strategy to sync unit conversion relationships, avoiding one large transaction that blocks the system.
Pitfalls and Lessons Learned
- Status field not filtered. In Kingdee,
FForbidStatus='B'means disabled. We once forgot to filter and ended up with a pile of "zombie units" in MES that confused downstream users. The safe approach: filter on the source side to only fetchA(enabled). - Code case inconsistency. Kingdee codes may be uppercase while the MES API sometimes forces lowercase. Add a normalization mapping.
- Unit group and conversion loss. Pushing only base units is not enough; a separate strategy is needed to sync "which unit is how many times which base unit," otherwise reporting conversions break.
- Pagination parameter not passed. The first run only returned 200 records and subsequent runs came back empty. Always bind
Limitwith a platform variable — never hardcode it. - Target idempotency failure.
idCheck=truerequires consistent IDs on both sides; MES usesunitUuid, so map Kingdee'sFUNITIDdirectly to it instead of generating a new ID.
Suitable and Unsuitable Scenarios
Suitable: stable unit count (tens to hundreds), infrequent changes, primarily one-way sync in private deployment.
Not suitable: complex unit conversion relationships, bidirectional sync required, or scenarios where MES-side units are maintained by the production floor. For the latter, it is better to reverse the direction — make MES the source and Kingdee the target — and run another strategy.