Practical Guide to Syncing Real-Time Inventory from Kingdee to XinBao Supply Chain Platform
What This Strategy Solves
In manufacturing supply chain integration, "real-time inventory" is often the most underestimated piece. A manufacturing customer runs Kingdee Cloud Cosmos as ERP and the XinBao supply chain collaboration platform for upstream/downstream coordination. Both sides need to see "current inventory"—sales wants sellable stock, production wants kit completeness, procurement wants in-transit plus on-hand. It looks like just moving numbers, but the most common failure on-site is unit/metric mismatch: one side uses base units, the other uses sales units; or one side is real-time balance, the other is a 22:00 snapshot. We agreed with the customer on a clear rule: push both qty and baseQty from Kingdee together, and let the target side pick what it needs.
Data Flow and Field Mapping
Source is Kingdee Cloud Cosmos, queried via executeBillQuery. Target is the XinBao supply chain collaboration platform, written via POST /wms/inventory. Full path: Kingdee Cloud Cosmos → Qeasy (Qingyi Cloud Data Integration Platform) → XinBao Supply Chain Platform.
Key field mapping:
| Business meaning | Source field (Kingdee) | Target field (XinBao) | Notes |
|---|---|---|---|
| Warehouse code | FStockId.FNumber | data.warehouseCode | Code mapping, centralized |
| Material code | FMaterialId.FNumber | data.materialCode | Code mapping, centralized |
| Stock quantity | FQty | data.qty | Direct pass-through |
| Base unit quantity | FBaseQty | data.baseQty | Dual-track with qty |
| Material name | FMaterialId.FName | data.materialName | Log + reconciliation only |
Source-side FID is Kingdee's internal record key; target-side id is used for idempotency (idCheck: true). Same record re-pushed will not be duplicated into the target—this is a hard constraint of the XinBao endpoint.
How to Configure on Qeasy
In Qeasy's strategy canvas, there are four key configuration points:
First, the source uses executeBillQuery, and the request body should only include five fields: warehouse, material, stock quantity, base quantity, and material name. Don't pull everything—inventory tables are large and more fields mean slower runs.
Second, the target writes POST /wms/inventory, sending the entire inventory record as the data object.
Third, code mapping is centrally managed. Warehouse and material code mapping tables live in Qeasy's Mapping Center, not embedded in scripts. A common Qeasy customer pattern is to maintain a version number for mapping tables—when source or target changes a code, only the mapping is updated, the strategy body stays untouched.
Fourth, idempotency control. The target endpoint supports idCheck: true; the source FID is transformed into the target id. It is also recommended to enable "dedupe by id" in Qeasy's logging center to avoid dirty data from reruns.
Implementation Steps
We delivered this to the customer in three phases:
Phase 1, incremental start. We did not start with a full pull. We first scoped the first batch of warehouses and materials by FStockId and FMaterialId, typically the production-critical warehouses. Let that batch run stably for two cycles to confirm mapping is correct.
Phase 2, full trigger. After incremental is stable, loosen the scope and trigger full sync. Full runs are scheduled at night off-peak. Qeasy supports manual full triggers plus automatic incremental continuation—a typical dual-track pattern.
Phase 3, schedule frequency. The crontab in the source material is */15 6-20 * * *, meaning every 15 minutes from 06:00 to 20:00. This fits daytime factory operations: no runs at night to avoid clashing with Kingdee's daily close; 15-minute intervals during the day are close enough to "real-time" without saturating the API. Customers with stricter freshness should narrow the source filter, not tighten the cron to minute-level.
Lessons Learned
Pitfall 1: Unit mismatch. In one on-site case, the target only received qty, not baseQty, which produced odd-looking numbers when base and sales units diverged. Fix: push both qty and baseQty; let the target pick.
Pitfall 2: Scattered mapping. Early on we wrote mappings inside scripts; later, when new materials were added, the two sides drifted. The safe approach is to centralize in Qeasy's Mapping Center with versioning.
Pitfall 3: Full overwrite clobbering incremental. A manual full trigger once overwrote just-finished incremental data. Lesson: the strategy must make explicit "full-overwrite vs incremental-append" semantics. For inventory, it should always be "source-of-truth full replace + incremental update," not naive truncate-and-write.
Pitfall 4: Missing idempotency on target. XinBao supports idCheck, but a wrong id causes duplicates. Always confirm the source-key-to-target-id transform is stable, and ensure the primary key value is visible in Qeasy logs for every write.
Pitfall 5: Nightly cron colliding with daily close. Kingdee runs its daily close at night; we also ran schedules then and hit query timeouts. The fix was to restrict the schedule window to 06:00–20:00.
When to Use and When Not to Use
Suitable for manufacturing/retail inventory visibility where both source and target have inventory codes and freshness requirements at the 15-minute level. Not suitable for cross-legal-entity or inventory-ownership-divergent scenarios—those need organization/ownership mapping first, before numbers are moved.