Purchase Order Sync Strategy in Practice: Field Mapping and Scheduling Design from Kingdee Cloud to WMS

What This Strategy Solves

In a real retail supply chain integration project, a customer uses Kingdee Cloud as the procurement backbone and WMS as the store-level purchasing entry. Both sides need purchase orders, but their coding systems, tax rate conventions, and field naming are all different. The most direct question is: how can we push Kingdee's approved purchase orders to WMS incrementally and stably, ensuring a one-to-one match on document number, supplier, warehouse, and line items?

This strategy is designed exactly for that — a one-way sync of Kingdee Cloud purchase orders to WMS, taking on the cross-system document mirroring role. We use the Qeasy Data Integration Platform to handle it.

Data Flow and Field Mapping

The overall flow is Kingdee Cloud → Qeasy → WMS. Kingdee's side uses executeBillQuery (QUERY type) to fetch the purchase order header and lines in a flat structure. The platform then groups the rows by FBillNo into a POOrderEntry array and pushes the whole document to WMS's wdt.purchase.purchaseorder.createorder.

Key field mapping (header):

Key field mapping (line purchase_details):

How to Configure on Qeasy

In Qeasy's strategy canvas, pick executeBillQuery for the source and wdt.purchase.purchaseorder.createorder for the target. The source buildModel: false must be kept; the platform performs grouping by FBillNo in the data flow, aggregating multiple lines of the same document into the POOrderEntry array and assigning it to the target line field purchase_details.

In the mapping panel, most header fields use {{FBillNo}} template syntax for direct value extraction. Constant fields (purchaser_name, is_check, pay_type) are fixed at the strategy level. Lines are expanded by iterating the POOrderEntry array. Two transformation functions are mandatory: first, FEntryTaxRate/100 to convert the tax rate from percent to 0~1; second, the datetime formatter for date fields.

Centralized code mapping management is a common practice among Qeasy customers: supplier, material, and warehouse code differences are maintained in a dedicated "Code Mapping" or master data strategy rather than scattered across each transaction strategy. Phased header/line rollout is also common — get the header running stably for a week before opening up line iteration, to avoid pushing the full line volume right away.

Implementation Steps

Step 1: Master data preparation. Before the sync starts, supplier, material, and warehouse master data must be aligned on both sides; otherwise provider_no, spec_no, and receive_warehouse_nos will fail to push.

Step 2: Full trigger. For the initial go-live, use a full sync to backfill historical approved purchase orders and verify that document numbers, suppliers, tax rates, and warehouses all match correctly.

Step 3: Incremental starting point. Switch to incremental mode. Use the Kingdee filter FApproveDate >= LAST_SYNC_TIME and FDocumentStatus = 'C' and FPurchaseOrgId.FNumber = '100' — pull by approval date, sync only approved documents, and restrict to the specific purchase organization.

Step 4: Scheduling frequency. Source runs at */30 7-20 * * *, target runs at */31 7-20 * * *, staggered by 1 minute to avoid both ends triggering in the same second.

Step 5: Lookup preparation. Downstream purchase receipt sync needs _findCollection or _mongoQuery to look up FID and FPOOrderEntry_FEntryId from the scheme hub. This strategy's FBillNo plus the line goods_no serve as the join keys — make sure those lookup fields are persisted in advance.

Pitfall Review

1. Pushing flat data without grouping. Kingdee returns a flat structure where header fields repeat on every row. Without grouping by FBillNo, pushing each row as a separate document to WMS produces N duplicate purchase orders, each with only one line. The safe approach is to perform grouping in the data flow layer.

2. Inconsistent tax rate conventions. Kingdee's FEntryTaxRate is a percentage, while WMS's tax is a 0~1 decimal. Forgetting to divide by 100 causes WMS to calculate tax at 13x the correct rate, throwing the document amounts off.

3. Running transaction docs before master data is aligned. If supplier, material, or warehouse codes are missing on either side, the push will fail with null pointers or "code does not exist" errors.

4. Delivery date is read from line level, with unclear rules for multi-line cases. FDeliveryDate is a line-level field. When there are multiple lines, whether to take the first line or aggregate by business rule must be written explicitly in the strategy — otherwise running the same document at different times can produce different results.

5. Both ends scheduled at the same second. When source and target crontabs are identical, the platform can easily trigger duplicates at boundary seconds. Staggering by 1 minute significantly reduces this risk.

Applicable and Non-Applicable Scenarios

Applicable: Kingdee acts as the procurement backbone, WMS acts as the store/fulfillment-side purchasing entry, one-way sync of approved purchase orders, and cross-system codes have been unified or can be mapped.

Not applicable: bidirectional sync, write-back to Kingdee, source contains unapproved or draft documents, or tax rate conventions are completely different from the target side — these require separate strategy designs.