Qeasy Cloud
Get Started

Unit of Measure Sync in Practice: Field Mapping and Scheduling from Kingdee Cloud to MES

· 卢剑航· Integration Solutions· 12 views· 4 min read
四化智造MES(API)Kingdee Cloud计量单位同步基础资料MES轻易云Field Mapping

What This Strategy Solves

Units of measure are the most overlooked yet most error-prone master data between an ERP and an MES. In the source, Kingdee Cloud calls them "计量单位"; in the MES, they become "计算单位", and the field names and unit ID conventions differ. In one real engagement with a manufacturing enterprise, materials in Kingdee used units like "只/台/套", but after they were pushed to the MES, unit UUID mismatches caused the entire production issue conversion flow to fail.

The essence of this strategy is to push unit-of-measure master data from Kingdee Cloud into the MES compute-unit ledger using a deterministic convention, so it can serve as a prerequisite dependency for subsequent material, routing, and inventory document syncs.

Data Flow and Field Mapping

Overall flow: Kingdee Cloud (system B) → Qeasy Data Integration Platform → MES (system A).

The source pulls units through Kingdee's executeBillQuery API (POST) with pagination, and the target calls the MES /api/createComputeUnit API (POST) to write them. The key field mapping is shown below:

Source Field (Kingdee Cloud)LabelTarget Field (MES)LabelNotes
FNumberCodeunitNoUnit CodeBusiness unit code
FNameNameunitNameUnit NameDisplay name
FUNITIDUnit IDunitUuidUnit UUIDUsed as the unique identifier throughout
FForbidStatusStatus——Used for filtering forbidden records
——companyCodeCompany CodeOrganization parameter on the target
——basicUnitUuidBase Unit UUIDMust be populated when target requires it
——coefficientConversion CoefficientMust be populated when target requires it

A key point on the field side: Kingdee's FUNITID is a numeric internal code, but on the MES side it must be mapped to a string unitUuid, otherwise the target's type validation will reject the payload.

How to Configure on Qeasy

We use Qeasy (轻易云数据集成平台) to host this strategy, and the configuration is concentrated in three places:

  1. Source metadata: Use the built-in "Kingdee Cloud" adapter, select executeBillQuery as the API, set the primary key field to FUNITID, and set the business number field to FName (using the name as the visible code per the customer's convention). The pagination parameter Limit uses the {{PAGINATION_PAGE_SIZE}} placeholder, which Qeasy injects at runtime.
  2. Target metadata: Use the "MES (API)" adapter, select /api/createComputeUnit as the API, and map FUNITID, FNumber, FName to unitUuid, unitNo, unitName via variables. companyCode is written as a constant and filled with the customer's organization code.
  3. Code mapping: Build a unit-code mapping table in Qeasy's Mapping Management to centrally manage the "Kingdee code ↔ MES unit UUID" mapping. This is one of the most common patterns among Qeasy customers — centralized code mapping management — which avoids hard-coded mappings scattered across strategies.

Implementation Steps

We recommend landing this in three phases:

  • Phase 1: Initialize the incremental cursor. First, do a one-time full pull of Kingdee units to establish the baseline. In Qeasy, trigger this with the "Full Sync" button; once it finishes, the incremental cursor is written.
  • Phase 2: Incremental scheduling. Set the cron to * 7-22 * * * (every minute between 7am and 10pm), and let Qeasy's incremental mechanism compare against FUNITID for new or changed records and push them to the MES.
  • Phase 3: Status filtering. Filter FForbidStatus = 'A' (not forbidden) on the source query, so that forbidden units are not pushed and no "ghost units" appear in the MES.

Another common pattern on Qeasy is dual-track incremental and full sync: use incremental for daily operations, and run a full reconciliation after key checkpoints such as monthly closing, to keep both sides ultimately consistent.

Lessons Learned

  1. Forgot to substitute the pagination parameter. Kingdee's Limit is a required pagination parameter. A typical mistake is hard-coding it to 2000, which exceeds Kingdee's per-page limit and gets rejected. The safe approach is to let Qeasy inject it at runtime via {{PAGINATION_PAGE_SIZE}}.
  2. Missed the FUNITID type conversion. The source is numeric; the target expects a string. This is a common pitfall that causes an entire batch push to fail.
  3. Forbidden units got pushed. Forbidden but not deleted units in Kingdee are returned by the default query and pushed to the MES, creating "orphaned" unit records. The safe approach is to filter FForbidStatus on the source.
  4. Unit UUID was not written back. The unitUuid generated on the MES side was not written back to Kingdee, so subsequent material pushes could not find the matching relationship. The safe approach is to enable a "write-back strategy" in Qeasy to push the target UUID back into an extension field on the source.
  5. Base unit and coefficient not populated. Some MES APIs require basicUnitUuid and coefficient to be non-empty, but Kingdee units themselves do not carry these fields. The safe approach is to fill defaults at the mapping layer, or split this into two strategies: create the unit first, then populate the conversion relationship.

When to Use and When Not to Use

Use when: The ERP is the source of truth for unit-of-measure master data and the MES needs the unit ledger for conversion — typical for manufacturing enterprises within the same group, with multiple organizations and books. Do not use when: The MES maintains its own unit ledger in a dual-system parallel scenario, or when you need bidirectional sync with cross-system interlocking conversion relationships (a separate conversion-relationship strategy is required).

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-mes-api-kingdee-cloud-9955-ncb7bbca2-f0d740cf

Comments