Warehouse Archive Sync in Practice: A Single-Strategy Implementation from Kingdee Cosmic to Fenxiao CRM
What This Strategy Solves
A retail enterprise runs Kingdee Cosmic on a public cloud as its back-end finance and supply chain system, while the front-end business team uses Fenxiao CRM for sales collaboration and on-site management. Both systems maintained warehouse archives independently. Three months in, the classic symptom appeared: the same warehouse had mismatched codes, names, and status flags across the two systems. Sales outbound orders could not find the correct warehouse, and monthly stock reconciliation never balanced.
The root cause is that a foundational master like the warehouse archive was never unified at the source. We used Qeasy (Qingyi Cloud Data Integration Platform) to make Kingdee Cosmic the single source of truth and push one-way to Fenxiao CRM, so that the front-end always follows back-end master data.
Data Flow and Field Mapping
The flow is one-directional: Kingdee Cosmic (source) → Qeasy middle layer → Fenxiao CRM (target). The middle layer handles code mapping, cleansing, and delta comparison; the target side only receives the final payload.
Key field mapping:
| Business Meaning | Kingdee Source | Qeasy Mapping Layer | Fenxiao Target |
|---|---|---|---|
| Warehouse Code | FNumber | Pass-through, used as idempotency key | externalCode |
| Warehouse Name | FName | Pass-through, length-trim validation | name |
| Warehouse Type | FStockType | Dictionary mapping (FG/RM/Virtual) | warehouseType |
| Active Status | FForbidStatus | Boolean conversion | isActive |
| Owning Org | FUseOrgId | Org code resolution | orgExternalCode |
| Last Updated | FModifyTime | ISO8601 normalization | updatedAt |
We adopted centralized code mapping: the FNumber-to-externalCode mapping is maintained in a Qeasy mapping table, so no hard-coding lives in scripts.
How to Configure in Qeasy
Step 1, create a new strategy in Qeasy, choose the B_TO_A direction, point the source to Kingdee's warehouse archive API, and the target to Fenxiao's warehouse object write API.
Step 2, configure the source fetch view. We use Kingdee's warehouse list API, pull in descending order by FModifyTime, with a page size of 200. Qeasy records the maximum timestamp of each pull as the starting point for the next delta run.
Step 3, do field transformation in the middle layer. Pay special attention to the warehouse type dictionary mapping—Kingdee uses enum values while Fenxiao uses string enums, so direct pass-through will fail. Once the code mapping is centralized, future additions only need a mapping table update.
Step 4, the target write uses upsert semantics with externalCode as the idempotency key. This handles both create and update in one strategy; no need to split into two.
Step 5, enable Qeasy's failure retry and alerting: after three failed sync attempts, an alert is pushed to the enterprise WeChat for manual intervention.
Implementation Steps
The rollout proceeded in three phases.
Phase 1: Full Initialization. Manually trigger a full pull to push all existing Kingdee warehouse archives to Fenxiao. In Qeasy, simply check "Full Pull". After completion, the platform remembers the maximum timestamp as the delta starting point. Schedule this during off-peak hours, such as 2 AM.
Phase 2: Delta Scheduling. After the full run, the strategy automatically switches to delta mode. We configured a 15-minute schedule in Qeasy, fetching deltas by FModifyTime. The key here is that the timestamp field must carry timezone information, otherwise cross-timezone scheduling will miss data.
Phase 3: Monitoring and Reconciliation. During the first week, we compared warehouse archive counts and active-status counts between the two systems daily; weekly in week two; and monthly after stabilization. Qeasy's task monitoring dashboard directly shows pull counts, write counts, and failure counts per run, which makes troubleshooting straightforward.
Pitfall Review
Pitfall 1: No idempotency key. In the first version we matched on warehouse name, and duplicates caused data corruption. The safe approach is to use Kingdee's FNumber as the source-side unique identifier and create an externalCode field on the Fenxiao side to guarantee non-corrupting upserts.
Pitfall 2: Inconsistent active-status field types. Kingdee's FForbidStatus is an enum (Forbidden / Not Forbidden); Fenxiao's isActive is a boolean. Direct pass-through writes dirty data—an explicit conversion in the Qeasy middle layer is required.
Pitfall 3: Forgetting to evaluate target before full run. If the target system already holds historical data, you must decide overwrite vs. skip before the full pull. In Qeasy we checked "skip if exists" to avoid accidentally overwriting manually maintained special warehouses.
Pitfall 4: Delta timestamp without timezone. Kingdee returns local-time strings by default. Without an explicit conversion to UTC, Qeasy's delta comparison will under-fetch. Always convert to ISO8601 in the middle layer.
Pitfall 5: Org code passed through without resolution. Kingdee's FUseOrgId is a numeric ID, while Fenxiao expects a code string. Passing the number directly causes a field-type error on the target. Resolve the org through an org API in Qeasy before mapping.
When It Fits and When It Does Not
Fits: a back-end ERP (here, Kingdee Cosmic) as the single source of truth for master data, a front-end business system that needs to follow, and a master-data change volume that is modest (tens to hundreds per day).
Does not fit: bi-directional sync, sub-minute real-time requirements, or scenarios where warehouse archives must be independently maintained in both systems (e.g., different subsidiaries each entering their own).