Practical Tutorial: Read-Only Sync Strategy for Kingdee Xingchen Measure Units

What This Strategy Solves

In supply chain integration, measure units are an easy-to-overlook yet business-critical piece of master data. Every purchase order, sales order, stock transfer, and packing conversion depends on them. In one of our projects, we found that a customer's Kingdee Xingchen held around a hundred measure units, with new ones being added or deactivated as new products were launched. The downstream Lingxing ERP needed a stable master data view when processing orders; once the two sides drifted apart, conversion errors would surface and cause mismatches between received quantities and packing numbers.

The goal of this strategy is to pull measure units in the "enabled" state from Kingdee Xingchen on a fixed schedule into the Qeasy integration hub, archive them centrally, and distribute them downstream. It is read-only — no write-back. The value is simple: lock the single source of truth in the source system, let the integration layer only mirror and map, and reduce the dirty-data risk that comes with bidirectional sync.

Data Flow and Field Mapping

The flow is unidirectional: Kingdee Xingchen V2 → Qeasy Data Integration Platform. The source system is authoritative, and the target side uses a "write null operation" placeholder strategy. This means the strategy does not write directly into the downstream ERP at this stage; instead, the results are first persisted to a Qeasy intermediate table for downstream strategies to consume.

Key field mapping (source → intermediate layer):

Practical note: using number rather than id as the business primary key is the safe choice. id can change across environment migrations; number is the stable anchor for the business team.

How to Configure It on Qeasy

Within the Qeasy Data Integration Platform, the metadata highlights of this strategy are as follows:

• Source configuration: platform is Kingdee.YXC, API is /jdy/v2/bd/measure_unit, HTTP method GET, effect QUERY. idCheck is disabled because the source does not rely on ID validation — deduplication is fully based on number.
• Request parameters: enable uses the function expression 0*1, which is equivalent to passing a fixed value of 1, meaning "enabled only". page_size is fixed at 100, matching the Xingchen API upper limit. search is left empty, indicating a full pull filtered by status.
• Target configuration: platform is the built-in datahub, the API is described as "write null operation", method POST, effect EXECUTE. idCheck is enabled here to provide idempotent write protection at the intermediate layer.
• Scheduling: the source strategy uses 30 7-23/2 * * *, i.e. every 2 hours at minute 30, between 07:00 and 23:00 daily. The target strategy's crontab is set to 1 1 1 1 1, which means "dependency-triggered" — it is invoked by the source strategy upon completion, rather than running on its own clock.
• Model building and response auto-fill: buildModel and autoFillResponse are both disabled. This strategy does not depend on automatic modeling, and the field structure is already stable on the source side.

Implementation Steps

Phased rollout is a repeatedly proven pattern among Qeasy customers: centralized encoding mapping, header/body staged delivery, and incremental + full-volume dual tracks.

1. Phase 1: Get the read-only chain working. Start with enable=1 and pull a single page to confirm that number, name, id, and other fields are returned reliably and that the intermediate table can be written to. A typical mistake is to chase "every field" right away without first verifying pagination and filter conditions — once the API throttles, you are stuck.
2. Phase 2: Confirm the incremental starting point. Find the timestamp of the most recent create/deactivate action on measure units in Xingchen, and use it as the baseline for create_end_time. After that, every scheduled run advances from this rolling cursor so that each call does not rescan everything.
3. Phase 3: Configure high-frequency scheduling. Adjust the source strategy's crontab to 30 7-23/2 * * * to cover business hours. Keep the target strategy as dependency-triggered, so the intermediate write only fires after the source pull succeeds.
4. Phase 4: Wire up downstream distribution. Inside Qeasy, add another strategy that pushes measure units from the intermediate table to Lingxing ERP based on code mapping. Keep all encoding mappings in Qeasy's mapping center rather than scattering them across strategies — you will regret it later otherwise.
5. Phase 5: Inspection and reconciliation. At a fixed time every day, compare the record count and enabled-status distribution between the Xingchen source and the intermediate layer. Any divergence should trigger an alert immediately.

Pitfalls and Lessons Learned

1. "Pull everything" is a false shortcut. Pulling every enabled unit in one go looks efficient, but once the count crosses a thousand, API pagination and throttling will drag the schedule down. The safe approach is an incremental cursor plus frequent small batches.
2. Using id as the primary key breaks the moment environments change. After the source system is upgraded or migrated, internal id values can be reshuffled, leaving the intermediate layer with "same code, different ID" dirty records. number is the business-facing primary key.
3. Ignoring the disabled status leaves downstream using retired units. The enable filter on the source side must be effective, otherwise Lingxing ERP will end up using deactivated measure units and orders will fail to save.
4. Setting the target strategy on a fixed cron causes empty runs or backlog. The target side here is a "write null operation" and must be triggered by the source strategy. Do not give it an independent cron, otherwise the intermediate layer will see source-less empty writes.
5. Wrong pagination parameters silently lose data. The Xingchen API caps at 100 records per page; exceeding it truncates the response. If page_size is omitted, the API falls back to a "no pagination" mode. Mixing the two semantics is a classic foot-gun. Pass 100 explicitly, and add a pagination loop in Qeasy that keeps calling until an empty page is returned.

When to Use and When Not to Use

Use it for: unidirectional master data sync, scenarios that need frequent refreshes at a controlled volume, and cases where the source system is the authority and should not be disturbed by downstream write-back.

Do not use it for: bidirectional sync, source APIs with strong transactional requirements, or scenarios where measure units must stay in lockstep across multiple ERPs in real time — those call for a heavier event-driven plus intermediate-table design.