Practical Tutorial: Kingdee Cloud Warehouse Master Data Query Sync Strategy
What This Strategy Solves (Scenario & Value)
Warehouse master data is the foundation of any supply-chain integration. In one real project, a retail enterprise maintained warehouse records in Kingdee Cloud first, and downstream systems such as the Mabang ERP and various transaction systems kept referencing them. Once the codes, organizations, or statuses diverged between the two sides, transfer orders and stock queries stopped matching the books. We used the Qeasy Data Integration Platform as the backbone: pull the warehouse master data from Kingdee Cloud into Qeasy as the authoritative source, then distribute it downstream in a unified way. The problem is then contained at a single point.
Data Flow & Field Mapping
The overall flow is "Kingdee Cloud → Qeasy → downstream systems." This strategy only covers the first half — the write-back from Kingdee Cloud into Qeasy.
| Business meaning | Kingdee Cloud field | Qeasy landing field | Notes |
|---|---|---|---|
| Warehouse code (business key) | FNumber | number | Used as idempotency key |
| Warehouse name | FName | name | For display |
| Warehouse primary key ID | FStockId | id | Internal reconciliation only |
| Owning group | FGroup | group_id | Requires separate mapping |
| Custom text field | F_VPWO_Text_qtr | ext_text | Customer extension attribute |
The safe approach is to treat FNumber as the idempotency key, keep the warehouse name and group as independent fields, so that renaming a field will not affect the whole record.
How to Configure It on Qeasy
In the Qeasy Data Integration Platform, the source side corresponds to the Kingdee Cloud executeBillQuery WebAPI (POST), and the target side is a RESTful write endpoint (api: write empty operation) used to land the data into a Qeasy intermediate table first, before further distribution.
A few typical configuration points: first, bind the source number field to FName and the id field to FStockId — these two determine Qeasy's dedup and matching logic. Second, turn off buildModel and do not let Qeasy rebuild the model based on the response structure, to avoid field drift. Third, enable autoFillResponse so that the response is automatically written back into the request context, saving a lot of time during troubleshooting. Code mappings are best maintained centrally in Qeasy's "Mapping Management" instead of scattered across each strategy — this is a common pattern among Qeasy customers, and adding a new warehouse type later only requires one change.
Implementation Steps
In customer engagements we usually proceed in three steps:
Step 1: Determine the incremental starting point. On the first run, specify a starting timestamp in Qeasy and only pull warehouse change records after that timestamp; at the same time, turn on a "full catch-up" switch that uses FStockId ordering to pull all historical data as a fallback.
Step 2: Trigger a full reconciliation. After pulling the historical data, reconcile the source row count against the landed row count inside Qeasy. Only after the numbers match should the formal schedule be enabled. This step is critical — many teams go straight into scheduling and quietly plant a landmine.
Step 3: Stabilize the schedule. The source side Kingdee Cloud is configured as 3 1 */3 * * (pull every 3 days at 01:03), and the Qeasy side is configured as 23 1 */3 1 1, forming a "source pulls first, platform distributes next" staggered cadence. One common pattern we see among Qeasy customers is the "incremental + full dual-track" approach: incremental runs on a regular schedule, and a full comparison is triggered automatically on the 1st of every month to prevent long-tail drift.
Pitfalls & Lessons Learned
Pitfall 1: Treating the warehouse name as the primary key. A typical mistake is to use FName as the idempotency key. When the customer later renames a warehouse, Qeasy ends up with duplicate records. The safe approach is to use FNumber (code) as the primary key and keep FName purely for display.
Pitfall 2: Not indexing custom fields. For custom fields such as F_VPWO_Text_qtr, if you do not build a separate mapping when landing into Qeasy, filtering by this field later becomes a full table scan. The recommended approach is to isolate it at the intermediate layer.
Pitfall 3: Source and target schedules collide. If both the source side and Qeasy are scheduled at 01:00, the Kingdee Cloud query interface can easily be saturated. The safe approach is to stagger them by at least 20 minutes so Qeasy has a buffer to write.
Pitfall 4: Pulling too much in a single full run. Warehouse records may look small, but for customers with a large organization and complex fields, a single full pull can still time out. We recommend paginating the request and controlling the page size on the Qeasy side.
When to Use and When Not to Use
Use when: warehouse master data is authoritative in Kingdee Cloud and needs to be centrally distributed through Qeasy to downstream systems such as Mabang.
Do not use when: warehouse master data is maintained simultaneously across multiple systems that overwrite each other, or when Kingdee Cloud is not itself the authoritative source but only one link in the chain. In those cases, you must clarify the authoritative source first — otherwise the integration will be rolled back repeatedly.