Material Master Data Sync in Practice: A Deep Dive into a Single Strategy from Kingdee Cloud to OKKICRM

What This Strategy Solves

Syncing material master data from an ERP to a CRM looks like "just move the code, name, and specification over," but in real customer environments we have seen the most typical "simple thing gone wrong" scenario: salespeople quoting in the CRM find codes misaligned, specifications displaced, units inconsistent, and three months later the data has forked irreparably between the two systems. This article focuses on a single-point strategy: extracting material master data from an ERP (referred to as "System A") via scheduled polling and writing it into a CRM's ("System B") product library, ensuring code consistency and key attribute synchronization so that sales, supply chain, and finance all work against the same product definition.

Data Flow and Field Mapping

The overall flow is System A (source) → Qeasy Data Integration Platform (middleware) → System B (target). The source retrieves deduplicated records via a query interface, the middleware performs field mapping and transformation, and the target writes the product records through a WebAPI.

Key field mapping table (based on production metadata; numeric fields are passed through as-is, text fields are processed per the target interface constraints):

The number and id positions in both endpoints are configured to identify the business code and system primary key respectively. In the target endpoint these two positions are filled with "0", meaning the target system itself owns uniqueness and the middleware does not participate in primary key generation.

How to Configure on Qeasy

On the Qeasy (轻易云) Data Integration Platform, this strategy is implemented as a standard "Source QUERY + Target EXECUTE" combination. Several key configuration points: first, on the source side, use a query interface such as executeBillQuery and enable idCheck, so the platform uses the primary key for idempotency validation—checkpoint resumption will not produce duplicates. Second, keep buildModel off and autoFillResponse on; the response structure is auto-filled by the platform, eliminating handwritten deserialization. Third, on the target side, use the WebAPI /v1/product/push with POST, where field values reference source fields via variables like {{FName}}—change one place, and all calls are updated.

A few engineering habits: keep code mappings (especially old/new codes and internal/external codes) in Qeasy's centralized mapping table rather than hardcoding them in scripts; roll out header and line items in stages—start with the material header, stabilize it, then attach extended attributes; run incremental syncs on a dual track of primary key plus modification time, full sync via one-shot trigger, and routine scheduling only for incremental.

Implementation Steps

Staged scheduling was key to a smooth rollout. In practice it ran roughly in three steps:

1. Determine the incremental starting point: Before the first go-live, run a full sync in the source system and record the primary keys of all current materials as the "watermark." On Qeasy, use FMasterId as the incremental anchor; after the first run, only records with FMasterId > recorded watermark are fetched.
2. Full sync trigger: Use Qeasy's "one-shot full sync" task to bulk-load historical materials into System B, observing failure rate and retry count during the process. Once the full sync is complete, push the watermark to the current maximum and officially enter incremental scheduling.
3. Scheduling frequency: Source cron is set to 0-59/5 7-20 * * * (every 5 minutes during business hours), target is 1-59/5 7-20 * * *, with the two points staggered by one minute to avoid thundering herd. Stop running outside business hours to reduce pressure on the source system.

Before go-live we also did a "dry run": switching the target API to sandbox or adding a dry-run flag so it only reads and does not write, verifying that field mapping and filter conditions match expectations.

Lessons Learned

1. Code mapping not centralized: A classic mistake is writing FNumber → product_no directly in each strategy's script, and when the code rules later changed, eight strategies had to be reworked. The safe approach is to maintain it uniformly in Qeasy's mapping table, with all referencing strategies only reading from the mapping table.
2. Specification length truncation: The source specification field allows up to 200 characters, while System B's interface caps at 80; pushing directly triggers interface errors. This is a place prone to failure. The safe approach is to add a truncation-plus-ellipsis rule in the middleware and flag truncated records in logs, so the business can later confirm whether splitting is needed.
3. Numeric-to-string conversion loses precision: For decimal types such as gross weight, a direct toString in some language runtimes produces scientific notation, and the target system fails during deserialization. The safe approach is to specify decimal places and format in Qeasy's field transformer, for example 0.000.
4. Wrong idempotency key: Early on we used FNumber as the idempotency key, but the source allowed code modifications, causing the same primary key to be written twice with new values, leaving stale data behind. The safe approach is to use FMATERIALID (primary key) as the idempotency key; business code changes do not affect deduplication.
5. Scheduling outside business hours: The source system performs nightly closing and backups; a 5-minute polling cycle competes with batch processing for resources. The safe approach is to constrain cron to the 7-20 window and let the source system rest at night.

Suitable and Unsuitable Scenarios

Suitable: Material master sync where the ERP is the data source and CRM/e-commerce/WMS are consumers; interfacing with legacy systems that have stable code rules and clear field semantics; supply-chain downstream systems requiring 5–10 minute quasi-real-time sync.

Not suitable: High-frequency scenarios with frequent material CRUD that require second-level consistency (switch to event-driven + CDC); projects where source code rules are being refactored or field semantics are not yet aligned; interfaces where the target system imposes strict primary-key constraints and disallows externally supplied business codes (align the primary-key strategy with the business owner first).