Synchronizing Kingdee Cloud Cosmos Material Master Data to Xiaoman OKKI CRM: A Practical Qeasy Single-Strategy Tutorial
What This Strategy Solves
Synchronizing material master data from Kingdee Cloud Cosmos to Xiaoman OKKI CRM looks like a simple data搬运 job, but in a real project we saw the problem surface three months in: material codes, units, and categories had drifted between the two systems, sales were entering wrong orders in the CRM, and inventory figures no longer matched. The root cause is that the sync was only "pushing" data, not "aligning" it. The value of this strategy is to anchor material codes, units, categories, and status across both systems through a single, observable, replayable pipeline on the Qeasy data integration platform.
Data Flow and Field Mapping
The source is the material archive in Kingdee Cloud Cosmos; the target is the product master in Xiaoman OKKI CRM. The Qeasy platform sits in the middle to handle mapping and transformation. Key field mapping:
| Business Meaning | Kingdee Cloud Cosmos (Source) | Xiaoman OKKI CRM (Target) | Handling Notes |
|---|---|---|---|
| Material Code | FNumber / Material Code | Product Code | Centralize mapping; do not allow manual edits on either side |
| Material Name | FName | Product Name | Watch special characters and length truncation |
| Specification | FModel | Specification | Pass through verbatim |
| Unit of Measure | FBaseUnit | Unit | Apply unit dictionary when needed |
| Category | FCategoryID | Product Category | Align categories by ID, not by name |
| Enabled Status | FUsed | Enabled Flag | Disabled materials must also be synced as disabled |
In practice we adopt the common pattern of "centralized code mapping": all mapping rules are maintained in Qeasy's mapping tables, so any adjustment on either side only requires one change, avoiding logic scattered across scripts.
How to Configure in Qeasy
The whole strategy is modeled in Qeasy as a single sync flow from "Cosmos material" to "Xiaoman product." Configuration is split into four parts:
- Source connector: select the Kingdee Cloud Cosmos material archive API and pull incrementally by modification time. Use Cosmos's built-in last-modified timestamp, not creation time, to avoid missing data.
- Target writer: connect to Xiaoman OKKI CRM's product write API with an upsert semantic of "update if code exists, otherwise create," guaranteeing a one-to-one mapping.
- Mapping layer: place the table above into Qeasy's mapping configuration. For fields like units and categories that have dictionary differences, use transformation functions rather than hard-coded strings.
- Exception handling: Qeasy consolidates interface errors, validation failures, and unique-key conflicts into one exception queue. Configure explicit handling for the two most frequent alerts: duplicate codes and missing required fields.
Implementation Steps
We recommend a three-phase rollout, paired with the "incremental + full-load dual-track" pattern:
- Phase 1, full initialization: push all materials from Kingdee Cloud Cosmos to Xiaoman OKKI CRM in one shot to establish a baseline. This runs only once; afterwards, verify totals and sampled details on both sides.
- Phase 2, confirm the incremental starting point: the starting point must be the timestamp taken right after the full load completes, not "now." Otherwise, changes during the full load will be missed.
- Phase 3, enable scheduled runs: material master data does not change frequently, so an incremental schedule of every 10–15 minutes is typically sufficient; hourly is fine for slower business rhythms.
Because material archives contain both header fields and sometimes body-level content such as attachments and extended attributes, we adopt the "header-then-body phased" pattern: first stabilize header fields like code, name, unit, and category, then push extended attributes in a second phase, to avoid carrying too many variables on a single go-live.
Pitfalls and Lessons Learned
- Codes were manually edited on both sides; sync reported success while reality was already misaligned. The safe approach is centralized code mapping: the source is the single source of truth, and the target must not bypass Qeasy for direct edits.
- Wrong timestamp chosen for the incremental starting point — a typical mistake is using creation time, which causes missing or duplicated data. Use last-modified time and explicitly capture a timestamp after the full load completes.
- Categories aligned by name instead of ID; a single space in the name causes misalignment. Strongly structured data like categories must use ID or code mapping, never string similarity matching.
- Disabled materials were not synced, so the target system kept selling them. The status field must be in the mapping and must not be omitted from Qeasy's filter conditions on FUsed.
- Bringing header and body online at the same time made troubleshooting chains too long. The header-then-body phased approach is the steadier path we settled on after hitting this pitfall.
Applicable and Non-Applicable Scenarios
Applicable for enterprises where material master data is relatively consolidated, Kingdee Cloud Cosmos is the single source of truth, and the CRM primarily handles sales orders and quotations. Not applicable for scenarios where both sides need to bi-directionally maintain materials, where material change frequency is extremely high (second-level), or as a channel for inventory or price sync — those belong to a different strategy class.