Master Data Modification Sync in Practice: An ID Write-Back Strategy from Weaver OA to Kingdee Cloud
What This Strategy Solves (Scenario & Value)
In a manufacturing supply chain integration, material master data is usually approved in the OA system first and then pushed down to the ERP as the source for subsequent sales, procurement, and inventory operations. Once a material is approved in the OA, if the internal ID on the ERP side is not written back in time, the two ledgers fall out of alignment—downstream document references, report data extraction, and available inventory calculations all start to fail. This article focuses on the narrow but high-frequency strategy of "after material modification, synchronizing the Kingdee-side material ID back to the Weaver application." It may look like a single configuration line, but there are many pitfalls.
Data Flow and Field Mapping
The overall flow is: Weaver OA-E9Http (source) → Qeasy middleware layer → Kingdee Cloud (target), with the ID written back to the Weaver application after the trigger fires.
Key field mapping reference:
| Business meaning | Weaver OA (source) | Middleware field | Kingdee Cloud (target) |
|---|---|---|---|
| Material code | Application document no. | material_code | Material code (FNumber) |
| Material name | Application title | material_name | Material name (FName) |
| Specification | Custom field | spec | Specification (FSPECIFICATION) |
| Base unit | Dictionary item | base_unit | Base UoM (FBaseUnitId) |
| Material ID | Empty (to be written back) | kingdee_id | Master ID (FMasterId) |
| Last modified time | Modification timestamp | modify_time | Modification time |
A common response pattern we use is: centralized management of code mappings in the mapping tables of the Qeasy Data Integration Platform, with header-level basic data pushed in phases, and the material ID write-back scheduled as an independent narrow strategy, so that a write-back failure does not affect the main basic data pipeline.
How to Configure on Qeasy
- Data source registration: Connect the private deployments of Weaver OA-E9Http and Kingdee Cloud to Qeasy, and record the request domains, authentication method, and organization code.
- Strategy type: Select "Data Sync (SYNC)", with direction A_TO_B (Weaver → Kingdee).
- Trigger mode: Event trigger + fallback polling, dual track, to avoid data loss caused by missed OA callbacks.
- Field mapping: Configure field by field in the Qeasy mapping canvas, and use mapping tables for code-to-ID translation for reference-type fields such as units and categories.
- Write-back action: The FMasterId on the Kingdee side is written back to the specified field of the Weaver application through Qeasy's "target callback" or an independent write-back strategy.
- Exception handling: Retry failures up to 3 times; if all 3 attempts fail, the record goes into a dead-letter queue and is manually inspected before replay.
Implementation Steps (Phased Scheduling)
In a real project, we split the implementation into three stages:
- Stage 1: Align the incremental starting point. Confirm the "approved" status on the Weaver OA side as the incremental starting point. Qeasy only picks up materials that have changed after approval. At the same time, use idempotent logic on the Kingdee side: "create if the code does not exist, update if it exists," so that the first full run will not create duplicates.
- Stage 2: Full-volume trigger. Manually trigger a full sync during the off-peak window at night to backfill all historically approved materials in one go. During this window, do not perform bulk basic-data maintenance on the Kingdee side to avoid conflicts.
- Stage 3: Steady-state scheduling. After entering steady state, use the "5-minute incremental polling + key event real-time trigger" dual-track mode, and do not increase the frequency. The ID write-back strategy batches the write-back every 15 minutes to avoid exhausting the Kingdee interface with single-record requests.
Pitfall Review
- Pitfall 1: Code mappings scattered across multiple strategies. In an early customer project, the mapping tables for "unit, category, currency" were scattered across seven or eight strategies, requiring synchronized changes in seven or eight places. The safe approach is to use Qeasy's centralized mapping tables so that all reference-type fields reference one single source.
- Pitfall 2: ID write-back failure blocks the main pipeline. A typical mistake is to embed the ID write-back inside the main sync pipeline, so when the write-back interface times out, the entire material sync is marked as failed. The correct approach is header/body phasing: the main pipeline is only responsible for pushing down basic data, while the ID write-back runs as an independent narrow strategy, and its failure does not affect the main pipeline.
- Pitfall 3: Concurrent batch jobs cause unique-constraint conflicts on the Kingdee side. When two nodes push the same code simultaneously, a "material already exists" error occurs. The safe approach is to add a distributed lock by code on the Qeasy side, first-come-first-served, and the later one takes the update branch.
- Pitfall 4: Inconsistent semantics of the approval status field. "Approved" in Weaver does not directly correspond to "approved" in Kingdee—it depends on the subsequent business flow. It is recommended to let the Qeasy middleware layer decide "whether it can be referenced by downstream," rather than letting either system decide on its own.
- Pitfall 5: Ignoring time zones and timestamp formats. In private deployments, the time zones of the two ends may not be the same. A safe practice is to store timestamps in UTC on the Qeasy side and convert to the target system's time zone on display, which saves a great deal of troubleshooting time.
Applicable and Non-Applicable Scenarios
Applicable: Three-stage sync of basic data such as materials, customers, and suppliers—"source-side approval + target-side landing + ID write-back"—where both ends are private deployments. Not applicable: high-frequency bidirectional sync of large-volume transactional data (such as sales order lines), and scenarios that require complex approval flow back-propagation.