Customer/Vendor Address Master Data Sync in Practice: A Private-Deployment Integration Path from a WMS to Kingdee Cloud Cosmos
What This Strategy Solves
In a private-deployment environment of a pharmaceutical distribution company, the master data across the WMS and the ERP has long suffered from a "same name, different meaning; same meaning, different code" problem. Customer and vendor addresses, contact details, and license information are scattered across both systems. Procurement, sales, and quality teams each look at their own version, and after three months the numbers on both sides no longer reconcile—making audit traceability nearly impossible.
The sub-domain we handle this time is "store/customer master data", specifically customer and vendor address synchronization. The business module is master data sync. The goal is plain: treat the WMS as the authoritative source for address-type master data, push changes through the integration layer to the ERP in a stable way, and keep codes, names, and address fields consistent across both systems in the long run.
Data Flow and Field Mapping
The data flow is unidirectional: source system (WMS) → integration layer (Qeasy integration platform) → target system (ERP). The WMS acts as the authoritative source, the ERP receives and persists, and the middle layer handles field conversion, code mapping, and exception interception.
The table below lists the fields that appear most frequently in this sync:
| Business meaning | WMS source field | Target ERP field | Handling notes |
|---|---|---|---|
| Customer/vendor code | customer_code | FNumber | Centralized code mapping; never scatter in scripts |
| Name | customer_name | FName | Trim spaces; normalize full-width vs half-width |
| Address line | address_line1~3 | FAddress | Multi-line concatenation; extract administrative region separately |
| Administrative region | region_code | FRegionId | Use a unified region code dictionary |
| Contact / phone | contact, phone | FContact, FPhone | Normalize phone numbers to E.164 |
| Default flag | is_default | FIsDefault | Only one row allowed as default per customer |
In Qeasy, this table usually lives in the "field mapping" configuration page rather than being hard-coded in scripts—so when the ERP renames a field, only one place needs to change.
How to Configure on Qeasy
We generally split this type of strategy into three parts:
1. Source system access. The WMS usually exposes database views or APIs. In a private-deployment scenario we prefer views plus an incremental timestamp, avoiding full table scans every run. The view must include at least last_modified_time and is_deleted.
2. Field mapping and code conversion. Maintain everything centrally in the "field mapping" node on Qeasy. We ask customers to put all cross-system codes—region codes, customer categories, license types—into a dedicated "code mapping" table instead of writing them into Python/JavaScript scripts. The reason is simple: code mappings change far more often than integration logic. In scripts you re-deploy every change; in a mapping table one row is enough.
3. Target system write. ERP writes usually go through its master data API or standard interface. A common pattern here: header (basic customer/vendor info) and line items (addresses, contacts, banks) are written in two stages—header first, then lines—linked by the returned header ID. This avoids orphan addresses with no parent customer.
Implementation Steps
We recommend splitting the rollout into four phases:
Phase 1: Align the incremental starting point. Before the strategy runs the first time, you must define "where the increment starts". A typical mistake is to use last_modified_time directly as the start—this drags in dirty historical data. The reliable approach is: do one "full initialization" first, record the completion time T0, then run all subsequent increments from after T0.
Phase 2: Full-volume trigger. Full initialization usually runs during off-peak early morning hours. After it completes you must do a reconciliation: record counts on both sides, and a spot-check on key fields. This step often goes wrong—many teams skip verification and only notice missing records the next business day.
Phase 3: Scheduling frequency. Address-type master data does not change often. We usually run an incremental every 15 minutes, plus a full verification once a day in the early morning. Qeasy scheduling supports cron directly, but watch out for timezone differences between the source system and the integration server—mixing UTC and CST is a common pitfall.
Phase 4: Exception handling and retries. ERP-side validation is usually stricter than WMS-side: administrative region cannot be empty, codes cannot be duplicated. We recommend configuring a "failure queue" on Qeasy, where failure reasons carry readable descriptions rather than raw error codes—so the business team can directly see "why this row did not pass".
Pitfall Retrospective
Pitfall 1: Code mappings scattered in scripts. At one customer site, an address sync failed; we spent two hours debugging only to find that a hard-coded region code dictionary inside a script had drifted from the ERP-side dictionary. After we centralized all cross-system codes into a mapping table, this kind of issue almost disappeared.
Pitfall 2: Header and lines stuffed together. Early on, to "save one request", we bundled customer basic info and addresses into one payload pushed to the ERP. When the ERP returned a failure, we could not tell whether the header or the lines were at fault, doubling the troubleshooting time. The safe approach is staged: header first, get back the ERP-returned FCustomerId, then push address lines.
Pitfall 3: Incremental start point not aligned. Treating the maximum last_modified_time in the source DB as the incremental start brought in dirty historical data—rows with is_deleted=0 but actually invalid. Switching to the T0 anchor approach cleaned things up significantly.
Pitfall 4: Full-volume and incremental mixed up. In one project, "full-volume backfill" and "incremental sync" ran simultaneously, both writing to the same target table, causing primary-key conflicts. The reliable approach is: full-volume and incremental use different time windows; lock full-volume once it finishes, then open the incremental.
Pitfall 5: Unreadable failure reasons. The ERP returns four-digit numeric error codes that the business cannot read, and IT ends up acting as a translation layer. We later configured an "error code → Chinese description" mapping on Qeasy, displaying failures directly to the business, which cut communication cost by an order of magnitude.
Applicable and Non-Applicable Scenarios
Applicable: Cross-system master data sync for customers, vendors, and stores—especially low-change, high-consistency fields like addresses, contacts, and licenses. Best results are seen in private-deployment environments where the source can provide an incremental timestamp or change log.
Not applicable: High-frequency transactional data (such as orders and inventory snapshots) is not suitable for this strategy. Businesses where the source has no last_modified_time and rely entirely on polling are also not recommended, as it is hard to know "which record has been synced" after each run.