Syncing Customer Contacts from OKKICRM to Kingdee Cosmic: A Single-Strategy Tutorial
What This Strategy Solves
Syncing customer master data from a CRM to an ERP looks simple, but if the contact table is not designed well, the two systems drift apart within three months and business users start asking questions. In one real project, a retail enterprise used OKKICRM as the single source of truth for customers and contacts, while Kingdee Cosmic served as the downstream customer archive. We used the Qeasy Data Integration Platform to run a single strategy that bridged the "customer → contact" link and avoided the inconsistencies caused by maintaining data in both systems manually.
Data Flow and Field Mapping
The overall flow is: OKKICRM (source) → Qeasy (middle layer, handling code mapping, cleansing, transformation) → Kingdee Cosmic (target).
The key fields are mapped below. Code mapping is maintained centrally in Qeasy, a point we will revisit in the lessons learned section.
| Business Meaning | OKKICRM (Source) | Qeasy Middle Layer | Kingdee Cosmic (Target) |
|---|---|---|---|
| Customer Code | customer_code | Customer code (pass-through) | Customer Code (FNumber) |
| Customer Name | customer_name | Customer name (trim, full-width to half-width) | Customer Name (FName) |
| Contact Name | contact_name | Contact name (required validation) | Contact (FCONTACT) |
| Job Title | position | Job title (default fallback) | Job Title (FTitle) |
| Mobile | mobile | Mobile (format validation, strip dashes) | Mobile (FMobilePhone) |
| Email (format validation) | Email (FEmail) | ||
| Is Primary Contact | is_primary | Is Primary (Boolean → Yes/No) | Default Contact |
Customer code is the primary key for this strategy; all changes are idempotent on it. Contacts are a child table in Kingdee, attached via the customer code.
How to Configure in Qeasy
In Qeasy, we configure this strategy in four blocks, each corresponding to a real engineering action.
First, source data retrieval. Use OKKICRM's customer contact query interface with an incremental condition on "last modified time." The initial full sync has no condition; subsequent runs only fetch data within the incremental window.
Second, middle-layer cleansing. In Qeasy's data processing node, add three actions: trim fields, look up the code mapping table, and validate mobile format. Code mapping is maintained as a separate "Customer Code Mapping Table." Every new customer goes through this table first to prevent duplicate customer codes downstream. This is a common pattern among Qeasy customers: centralize code mapping so future adjustments only happen in one place.
Third, target write. Kingdee Cosmic's customer archive is a custom document with a header plus contact body. Qeasy supports staged writing: write the customer header first, capture the internal ID returned by Kingdee, then batch submit the contact body using that internal ID. In one project, contacts would be partially lost for large customers unless staged writing was used.
Fourth, retry and logging. Qeasy logs the processing result of every record by default; failures go into a retry queue. We additionally configured an "exception alert" that pushes to the corporate WeChat whenever a batch exceeds the failure threshold, so the on-call engineer is notified immediately.
Implementation Steps
We staged this strategy's rollout in three phases. The safe approach is staged scheduling rather than kicking off a 5-minute run right away.
- Incremental Starting Point: On first launch, run a full sync to push all existing customers and contacts into Kingdee. After the full run completes, record the maximum "last modified time" as the incremental starting point.
- Full Sync Trigger: The full task is only triggered manually during initialization or manual repair, and is not scheduled normally to avoid conflicting with the incremental run.
- Scheduling Frequency: Once stable, the incremental strategy runs every 15 minutes. This frequency reflects CRM changes in a timely manner without exhausting the source interface. If the business requires higher real-time performance, it can be tightened to every 5 minutes, but we recommend observing for a week first.
Additionally, this strategy depends on an upstream strategy that syncs customer archives first, otherwise contacts have nowhere to attach in Kingdee. We wired up the dependency in Qeasy so the order is locked.
Lessons Learned
We hit several typical pitfalls along the way. Sharing them here as warnings for future projects.
- No centralized code mapping. At first launch, we hardcoded the customer code mapping directly in the transformation script. Three months later, the business needed a new coding rule and we had to modify dozens of places. The safe approach is to maintain a mapping table in Qeasy from day one, shared by all strategies.
- No staged header/body writing. Submitting the contact body in one shot caused half the records to be lost for large customers with over a hundred contacts. After switching to "header first, capture internal ID, then batch submit the child table," the issue disappeared.
- Hardcoded incremental starting point. During early launch, we hardcoded the incremental starting point to a fixed time. Later, the source system backfilled historical data, and new records were missed. We changed it to "max last modified time + 1 second" with dynamic advancement.
- Inconsistent mobile formats. OKKICRM stored both "138-xxxx-xxxx" and "138xxxxxxxx." Pushing directly to Kingdee caused half the records to be rejected by format validation. A cleansing step fixed this.
- No dual-track for incremental and full sync. A full sync once overwrote a running incremental batch, producing duplicate contacts. We clarified in Qeasy that the full sync is only triggered manually during idle windows, and the incremental run is paused during that time.
When This Applies and When It Does Not
Suitable for: retail, trading, and service businesses where customers and contacts have a single source in CRM, the ERP serves as the downstream business backbone, and one-way sync with moderate real-time requirements (minute-level) is sufficient.
Not suitable for: scenarios where customers are maintained bidirectionally between CRM and ERP (which leads to write loops), or where the ERP fully owns customer records and the CRM only mirrors them for viewing. Those cases require a different approach.