Basic Unit Information Sync: A Practical Guide from MySQL to Kingdee Cloud

What This Strategy Solves

Basic unit information is the foundational dictionary referenced by every downstream supply chain document—materials, purchasing, inventory, and sales. In a real project, a customer stored over a thousand UOM records in MySQL, while the target Kingdee Cloud required its own unit system. If the two sides drift apart, every downstream document eventually breaks. This strategy does one straightforward thing: push unit-of-measure master data incrementally and stably from the source system to the target, so downstream business can rely on it.

Data Flow and Field Mapping

The source system is MySQL. Through the Qeasy data integration platform, a WebAPI executor issues a POST request that runs a SQL statement with placeholders. Incremental extraction is achieved via last_update_date >= {{LAST_SYNC_TIME|datetime}}, and pagination is controlled by limit :limit offset :offset. The main_params request parameter carries the pagination values.

The target is Kingdee Cloud. On the target side, the metadata is marked as a "write no-op," which is a transitional pattern Qeasy commonly uses for centralized code-mapping management: the data lands in an intermediate table or cache layer first, then a downstream write strategy or manual script consumes it. The benefit is decoupling "extract" from "land." When Kingdee fields change, only the downstream side needs adjustment.

Key field mapping table (source → target semantics):

How to Configure It in Qeasy

On the source side, in the Qeasy configurator pick WebAPI → select. Bind main_params and main_sql to the request body. Inside main_sql, embed the {{LAST_SYNC_TIME|datetime}} placeholder—the platform automatically replaces it with the last successful sync timestamp before each execution. This is the typical "incremental and full-volume dual-track" approach Qeasy customers adopt. Set idCheck to true so the platform performs idempotent deduplication by 单位ID and avoids duplicate writes.

On the target side, configure as a "write no-op" (number=0, id=0), which temporarily stores the upstream structured result for downstream strategies to consume. In special deployment scenarios, the target side can also be directly switched to Kingdee Cloud's save interface for a one-shot landing.

For scheduling, set the source cron to */59 * * * *, i.e., every 59 minutes. That number is not arbitrary: unit master data rarely changes within a day, so higher frequency just adds noise to the logs. Meanwhile, 59 minutes avoids the top-of-the-hour spike and shifts load off the peak. The target cron is */5 * * * *, pushing cached records to the target system in small, frequent batches.

Implementation Steps

Phase 1: Confirm the incremental starting point. Before the first execution, manually determine a reasonable LAST_SYNC_TIME starting point. The safe approach is to take the historical minimum of last_update_date on the source and roll back one day, perform a cold-start full sync first, then continue with last_update_date >= {{LAST_SYNC_TIME}}.

Phase 2: Full-volume trigger and reconciliation. Use Qeasy's "full-volume trigger" button to run once and verify that the record count on the target matches the SQL result count on the source. For reconciliation, check three things: total count, null ratio, and non-null ratio of key fields (unit code, base-unit flag).

Phase 3: Bring scheduling online. After reconciliation passes, enable both schedules—the source */59 * * * * and the target */5 * * * *—and observe the logs for 24 hours. Once no anomalies surface, switch the target from the "write no-op" to the actual Kingdee Cloud save interface.

Pitfalls and Lessons Learned

1. Placeholders not replaced, causing full-table scans. A typical mistake is hard-coding {{LAST_SYNC_TIME|datetime}} as a fixed value. It looks like it works, but every run pulls a full volume. This is where things go wrong. The safe approach is to spot-check the actual SQL bound values in the Qeasy execution history before going live.

2. Precision issues with decimal_number and conversion_value. If these two fields are defined as float in MySQL, cross-database transmission will produce tail-difference issues like 0.1+0.2. The recommendation is to CAST(... AS DECIMAL(20,8)) in the SQL before returning.

3. Enum mappings forgotten. uom_type, process_mode, and enable_flag are enums on the Kingdee Cloud side. Writing strings directly will be rejected by the target. A common Qeasy customer pattern is to maintain enums centrally in a mapping table, so source strategies only reference keys, and future enum adjustments only touch the mapping table.

4. Target-side "write no-op" mistaken as completion state. This is a common misjudgment in private deployments: seeing a 200 in the configuration is taken as success, but in reality the data has only landed in the cache layer. Be sure to distinguish between "extraction success" and "landing success" in the monitoring view.

5. Scheduling frequency conflicting with source write peaks. Changing */59 to */5 looks more real-time, but unit master data writes are sparse, and the change just churns Qeasy's connection pool and the source binlog. A week later, the customer reported slowness, and rolling back the frequency fixed it.

When to Use and When Not to Use

Suitable for: basic dictionary master data sync such as units, currencies, tax rates, and warehouses; scenarios with sparse updates, strong idempotency requirements, and the need for centralized code-mapping management. Not suitable for: business document sync (should use phased strategies with header and body), high-frequency transactional data (changes faster than one minute), or inventory transactions that require complex write-back validation.