Wangdiant Logistics Number Write-Back to Kingdee Cloud SAL_OUTSTOCK: Single-Strategy Sync Tutorial

What This Strategy Solves

In one retail customer's order fulfillment flow, the front end runs in Wangdiant (order review, printing, shipping), with carrier tracking numbers landing on the Wangdiant side. Finance and warehousing, however, treat Kingdee Cloud's sales-outstock orders (SAL_OUTSTOCK) as the system of record. The problem is that logistics numbers trail the actual shipping action, and the customer-service and warehouse teams need to see the real carrier tracking numbers in Kingdee for reconciliation and downstream pushes. This strategy does only one thing: pull shipped sales-outstock increments from Wangdiant and write the tracking numbers back to Kingdee's SAL_OUTSTOCK, at the document level. It is not a full mirror — it is a narrow, accurate write-back channel.

Data Flow and Field Mapping

The flow is a one-way write-back: Wangdiant (source) → Qeasy integration platform (the orchestration/transformation middle layer) → Kingdee Cloud (target).

Key field mapping (source → target):

The target side calls Kingdee's batchSave API. The business-object form ID is fixed at SAL_OUTSTOCK, operation is BatchSave, and IsUserModelInit=true (network control on). Qeasy folds the source detail rows into the FEntity array and submits the whole batch.

How to Configure It on Qeasy

On the Qeasy integration platform, this strategy is split into three stages — source reader, transformer, and target writer. Key configuration points:

1. Source reader: choose the QUERY action, API wdt.stockout.order.query.trade, primary key stockout_id, idempotency switch idCheck=true. Express the incremental anchor as a function so you never hand-edit the time.
2. Incremental anchor and time window: start_time uses _function from_unixtime((CURRENT_TIME-259200),'%Y-%m-%d %H:%i:%s') (3 days back), end_time uses CURRENT_TIME-172800 (2 days back). This 24-hour sliding window guarantees recovery even if one round is missed.
3. Status filter: leave status empty for upstream flexibility, but in production it is safer to pin it to 95 (shipped) so cancelled or abnormal shipments never leak in.
4. Centralised encoding mapping: in Qeasy's Mapping Center, map Wangdiant's shop_no, warehouse code, and carrier code to the corresponding Kingdee archive IDs. These mappings must live in one place; once they scatter into individual strategies, the numbers will drift within three months.
5. Target writer: EXECUTE action, API batchSave, FormId=SAL_OUTSTOCK, Operation=BatchSave, IsUserModelInit=true. Build FID with _function substring_index('{{src_tids}}','_',-1) to slice the real Kingdee document number off the concatenated original-order string.
6. Header/detail staged handling: this strategy writes only the tracking number; it does not re-send amounts or tax lines. Inside FEntity keep only logistics-related fields, everything else untouched, so an already-approved document is never knocked back to pending.

Implementation Steps

We recommend splitting the rollout into three phases.

1. One-shot full trigger: run a wider time window (e.g. past 30 days) once to write back all historical shipped documents. Schedule it during off-peak hours, and either disable Kingdee's network control or station someone to release locked documents.
2. Switch to incremental anchor: after the full run finishes, switch the start_time offset back to the normal 3-day sliding window so the schedule settles into daily rhythm. The source crontab should be 13 */3 * * * (minute 13 of every 3rd hour), and the target crontab 22 */3 * * *, leaving 9 minutes between them for transformation and buffering.
3. Schedule frequency and monitoring: one round every 3 hours is enough for typical carrier-return latency. If reconciliation runs at noon the next day, align one round to fire about an hour before that. While incremental and full runs run in parallel, hang a "document-count reconciliation" alert on Qeasy — if the hourly write-back count drops more than the threshold, jump in manually immediately.

Lessons Learned

1. Do not make the sliding window too tight. The earliest version used a 1-hour start_time to be lazy, but a single scheduler hiccup meant that hour of shipments could never be recovered except via a full rerun. The 3-day vs 2-day window was settled after several production incidents.
2. Carrier codes do not match. Wangdiant uses its own carrier code; Kingdee expects the carrier-archive ID. The first version had no mapping at all, so every Kingdee record errored out or got stamped with an "unknown carrier". Since then, every cross-system archive lookup goes through a single mapping table in Qeasy; no hard-coded values inside strategies.
3. Always keep IsUserModelInit=true. If you turn off Kingdee's network control on a batch save, concurrent runs hit "document is being edited by another user". Letting Kingdee queue internally is the safest approach.
4. Do not overwrite the whole outstock document. If you shortcut by sending the full document back, an already-approved, voucher-generated document in Kingdee will be revived into the pending state — finance will definitely push back. When writing back tracking numbers, touch only the logistics field; leave the rest of the document as-is.
5. The src_tids tail-extraction depends on the concatenation order. substring_index('_',-1) assumes the Kingdee document number sits at the end of the original-order string. One warehouse system once placed the shop code at the end, so the tail extraction produced garbage everywhere. A team-wide convention on concatenation order finally fixed it.

When to Use, When Not

Use it: retail and distribution scenarios where Wangdiant is the fulfillment hub and Kingdee is the finance/warehousing hub, and you need shipped-status tracking numbers back in Kingdee for reconciliation and downstream consumption. Do not use it: when you need to sync the full outstock document (amounts, taxes, price lists) — that belongs to a separate whole-document sync strategy; or for cross-entity, cross-book intercompany settlement, which needs its own receivables strategy.