Syncing Material Master Data from OKKICRM to Kingdee Cosmic Flagship: A Single-Strategy Tutorial
What This Strategy Solves
Material master data is the foundation of any ERP. In one retail project, the front-end business runs on OKKICRM while finance and supply chain run on Kingdee Cosmic Flagship, and the two systems use different coding schemes. A salesperson updates a specification in the CRM, the backend material record does not catch up, and a few days later mismatches in unit, tax category, or default warehouse are discovered, blocking order pushes.
We use the Qeasy data integration platform to host this strategy. The goal is straightforward: changes to material data in the CRM must land reliably and traceably in Kingdee, with correctness taking priority over speed.
Data Flow and Field Mapping
Data flows from OKKICRM through the Qeasy middleware, where coding mapping, field cleansing, and unit conversion take place, and is then written into Kingdee's material master. The key field mapping is shown below.
| Business Meaning | OKKICRM Source | Qeasy Middleware | Kingdee Target | Notes |
|---|---|---|---|---|
| Material code | product_code | Standardized code | FNumber | Trim spaces, normalize case in middleware |
| Material name | product_name | Trim leading/trailing spaces | FName | Truncate by target system limit |
| Specification | spec | Pass-through | FSpecification | - |
| Unit of measure | unit | Unit code mapping | FBaseUnitId | Mapping table managed centrally |
| Default warehouse | default_warehouse | Warehouse code mapping | FDefaultStockId | Must exist in target system first |
| Tax category | tax_category | Dictionary mapping | FTaxCategoryId | Maintain mapping table |
| Status | status | 0/1 to enabled/disabled | FUsed | - |
| Last modified | update_time | Incremental cursor | - | Starting point for incremental sync |
How to Configure on Qeasy
On the Qeasy integration platform, one strategy corresponds to one integration scenario. The key configuration points are as follows.
- Source connection: Use the OKKICRM open API. Authentication credentials are stored in Qeasy's credential manager and never hard-coded in the strategy.
- Target connection: For the on-premise deployment of Kingdee Cosmic Flagship, register the API endpoint in Qeasy's "System Connections" so other strategies can reuse it.
- Data source configuration: Use
update_time > ${LAST_RUN_TIME}for incremental pulls. The first run switches to a one-time full sync channel. - Field mapping: Use Qeasy's visual mapping editor. Foreign-key fields such as unit, warehouse, and tax category all point to a central mapping table rather than being hard-coded.
- Write method: Prefer the save interface on the Kingdee side. If it fails, fall back to a separate audit call to avoid writing dirty data.
- Logging and alerts: Enable field-level change logs in Qeasy so that before/after values are visible for audit.
Implementation Steps
We recommend a three-phase rollout to avoid the common trap of running full sync too early.
Phase 1: Confirm the incremental starting point. Run a query strategy in Qeasy to fetch the latest modification time from OKKICRM and use it as the initial cursor value. A common on-site mistake is using the current system time as the starting point, which causes historical data to be skipped or duplicated.
Phase 2: Full sync and reconciliation. The initial full sync should run during off-peak hours, for example late at night. Once it completes, perform a reconciliation in Qeasy: source material count versus target material count, with a separate list for differences. A common pattern among Qeasy customers is to split header and line into two phases: the material master (header) goes first, and the extended attributes (line) come in a later strategy. This keeps each strategy manageable.
Phase 3: Scheduling and operations. We recommend running incremental sync every 5 to 10 minutes. Higher frequency tends to trigger rate limiting on the target system. Configure the schedule in Qeasy as a scheduled task with three automatic retries; persistent failures trigger a manual alert.
Lessons Learned
The following pitfalls were experienced firsthand on customer sites.
- Mapping logic scattered across strategies. In early projects we wrote unit-to-target-unit mapping directly into each strategy. Changing one source unit required editing more than a dozen strategies. The reliable approach is to build a single mapping table in Qeasy and have every strategy reference it, so a single change propagates everywhere.
- Wrong cursor field. Using
create_timeinstead ofupdate_timecaused updates in the CRM that did not create new records to never reach the target. - Target-side data missing. Foreign keys such as default warehouse do not exist in the target system, so the entire record fails. Run a dependency check before sync to fill missing warehouses and units first.
- Full and incremental running together. If incremental starts before the full sync finishes, the two flows overwrite each other and data becomes inconsistent. The safe approach is to finish the full sync, manually confirm reconciliation, and only then switch to incremental.
- On-premise endpoint changes. After the customer migrated servers, the Kingdee endpoint domain changed, but the strategy still pointed to the old address, and syncs failed silently overnight. Add a connectivity self-check in Qeasy's connection configuration.
When to Use and When Not to Use
Suitable for: on-premise deployments where OKKICRM is the front-end and Kingdee Cosmic Flagship is the back-end ERP, where the CRM is the source of truth for material data, the ERP is the mirror, and the material volume is in the tens of thousands or below in steady state.
Not suitable for: bi-directional sync, target systems with many custom fields, or scenarios with millions of materials that require real-time CDC. These require a separate design.