Auxiliary Unit Sync from Kingdee Cosmos to Jikeyun: A Single-Strategy Practical Guide
What This Strategy Solves
Auxiliary units are the most overlooked—and most failure-prone—master data in the supply chain. In one retail engagement, the warehouse maintained multiple measurement units (box, pallet, piece) in Kingdee Cosmos, while Jikeyun's purchasing and sales documents relied on a separate unit system. When the two sides managed units independently and conversion rules drifted apart, purchase order entry threw errors, inventory counts drifted, and month-end reconciliation broke—problems usually surfacing only at month-end. This strategy has a simple goal: treat Kingdee Cosmos as the single source of truth for unit master data, and incrementally sync it to Jikeyun so the front-end business system always uses one authoritative set of conversion rules.
Data Flow and Field Mapping
Data flow: Kingdee Cosmos (source) → Qeasy Data Integration Platform (middleware) → Jikeyun (target). The middleware does not persist data; it only performs field conversion, code mapping, and incremental marking.
Core field mapping (typical example):
| Business Meaning | Kingdee Cosmos Source Field | Jikeyun Target Field | Handling Notes |
|---|---|---|---|
| Material code | FMaterialId.FNumber | product_code | Pass-through |
| Auxiliary unit code | FUnitId.FNumber | aux_unit_code | Pass-through |
| Auxiliary unit name | FUnitId.FName | aux_unit_name | Pass-through |
| Conversion numerator | FConvertNum | numerator | Pass-through |
| Conversion denominator | FConvertDen | denominator | Pass-through |
| Is base unit | FIsBaseUnit | is_base | Boolean mapping: 1→true, 0→false |
| Enabled status | FUsed | status | 0→Enabled, 1→Disabled |
Code mappings are centrally managed in Qeasy's mapping tables rather than scattered in scripts. When a new unit is added, only one place is edited; the strategy itself stays untouched.
How to Configure on Qeasy
On the Qeasy Data Integration Platform, this strategy is configured in four parts:
- Source system connection: Select the Kingdee Cosmos adapter, configure account info (kept as environment identifiers only after desensitization), point the interface path to the auxiliary unit query, and add filter conditions on
FUsedand last-modified time. - Target system connection: Select the Jikeyun adapter, configure authorization and target organization code, and use the auxiliary unit master data write API.
- Field mapping: Beyond the routine fields above, focus on the conversion numerator/denominator—values may be 0 or empty in Kingdee. Apply a null-value fallback before pushing, otherwise the Jikeyun API validation will reject them.
- Run policy: Incremental mode advances by the
FModifyDatecursor; full mode backfills historical data in one shot. Failure retry and alert notifications follow project standards (e.g., enterprise WeChat or email).
Implementation Steps
In a real engagement, we typically proceed in three phases:
- Phase 1: Full trigger (first go-live). Manually run a full sync on Qeasy to push every historical auxiliary unit to Jikeyun. After it completes, reconcile both sides, focusing on verifying conversion correctness—especially 1:1 "pseudo auxiliary units."
- Phase 2: Incremental start switchover. Once full sync is done, switch the sync mode to incremental, with the start point set to the maximum
FModifyDatefrom the full run. This step is the most error-prone—set the start one second too early and you push duplicates; one second too late and you lose data. - Phase 3: Schedule frequency hardening. Auxiliary units change infrequently; we typically set a 15-minute interval. If business confirms almost no changes during the day, this can be compressed to hourly or a few scheduled runs per day. Qeasy's scheduler supports cron expressions; configure it to match the business rhythm.
The safe approach: keep a manual rerun entry point available for two weeks after go-live to facilitate corrections, then close it and switch to scheduled-only operation.
Pitfall Retrospective
- Conversion direction reversed. In Kingdee, "1 box = 24 pieces" and "1 piece = 0.0417 box" are two directions. Swapping numerator and denominator causes front-end inventory calculations to collapse. During configuration, always walk through sample data with the business side row by row.
- Empty vs. zero values conflated. The conversion numerator/denominator is empty when not maintained in Kingdee; the Jikeyun API requires non-empty integers. We use Qeasy's field cleansing to provide a null-value fallback (default 1) and enforce type conversion; otherwise batch pushes fail en masse.
- Base units pushed as auxiliary units. A common mistake is pushing every unit, causing duplicate records on the Jikeyun side. The safe approach is to add
FIsBaseUnit = 0to the source-side filter, pushing only true auxiliary units. - Incremental start overlaps with full sync. As mentioned earlier—"one second too early duplicates, one second too late loses data." Qeasy can mitigate this by enabling the "deduplicate by primary key" option, but we still recommend manually verifying the start timestamp once.
- Authorization expiration without alerts. When Kingdee or Jikeyun interface tokens expire, the strategy doesn't error immediately but manifests as a long silence with no data. Qeasy can be configured to trigger an alert when no data is seen for N consecutive cycles, which is more reliable than simply watching error logs.
Applicable and Non-Applicable Scenarios
Applicable: Kingdee as the single source of truth for unit master data, Jikeyun as the front-end business system, low change frequency but high consistency requirements—typical of supply chain integration scenarios. Not applicable: scenarios requiring bidirectional unit maintenance on both sides, or where unit conversion is dynamically computed by the business front-end (rather than maintained as master data).