Standard Kingdee Sub-item Assembly → Wangdiantong Outsourced Warehouse Return: Outbound Sync Tutorial
What This Strategy Solves (Scenario & Value)
In a retail or manufacturing enterprise, after outsourced processing, the outsourced warehouse needs to perform return outbound operations based on actual consumption and material returns. Kingdee Cosmic serves as the financial and supply chain back-end, recording sub-item assembly and return material logic; Wangdiantong, as the warehouse and distribution front-end, needs to receive the outsourced warehouse return outbound documents to update physical inventory and flow logs. With inconsistent encodings, organizations, and inventory dimensions on both sides, manual entry is slow and error-prone. The goal of this strategy is to synchronize Kingdee Cosmic's sub-item assembly return material outbound documents to Wangdiantong's outsourced warehouse return outbound business documents according to established rules, achieving "one source of truth, consistent on both sides."
Data Flow & Field Mapping (Source → Middle Layer → Target)
Data flow: Kingdee Cosmic (source) → Qeasy Data Integration Platform (middle layer, responsible for cleaning, mapping, and enrichment) → Wangdiantong (target, outsourced warehouse return outbound business).
Key field mapping (taking the sub-item assembly return material outbound document as an example):
| Business Meaning | Kingdee Cosmic Source Field (Example) | Middle Layer Processing | Wangdiantong Target Field (Example) |
|---|---|---|---|
| Document Number | FBillNo | Pass-through original value | External order number (deduplication key) |
| Document Type | Document type identifier | Map to business type code | Business type = Outsourced warehouse return |
| Warehouse | Outbound warehouse code | Organization code mapping table | Outsourced warehouse code |
| Material Code | Material code | Centralized encoding mapping | Wangdiantong product code |
| Quantity | Actual return quantity | Unit conversion | Outbound quantity |
| Batch | Batch number | Pass-through original value | Batch attribute |
| Return Reason | Return reason / remarks | Concatenate business summary | Remarks |
| Business Date | Business date | Timezone and format normalization | Document date |
Do not hard-code encoding mappings in scripts — a common Qeasy practice is to maintain material codes, organization codes, and other mappings as a separate "mapping table" in the platform. When the source side changes, you only need to modify one place, avoiding the situation where numbers on both sides don't match three months after the strategy goes live.
How to Configure in Qeasy
In the Qeasy Data Integration Platform, this strategy is essentially a sync pipeline of "source fetch → middle layer transformation → target write." Several key configuration points:
- Source data fetching: Connect to Kingdee Cosmic's outsourced return material outbound document query interface, filter by document status and last modification time, and only retrieve records that have been audited and not yet pushed.
- Target write: Connect to Wangdiantong's outsourced warehouse return outbound business creation interface, using the "external order number" as the idempotency key to avoid duplicate pushes that would cause inventory to be incorrectly reduced.
- Centralized encoding mapping: The three mapping tables for material codes, organization codes, and units of measure are placed in Qeasy's "Data Dictionary / Mapping Table," and the strategy references the mapping instead of hard-coding values.
- Header and body phased assembly: Kingdee Cosmic's sub-item assembly return material document has a header + multiple line item details (sub-item material, batch, return quantity). In the Qeasy strategy, the assembly order of the header and body must be clarified — create the header first, then loop to push the body. If any line fails, the entire document should be rolled back or retried by line, and this needs to be defined in advance.
- Error handling and alerting: Documents that fail to write to Wangdiantong should not be thrown into a black hole. A common Qeasy practice is to drop them into an "exception document pool" and push notifications to operations via DingTalk robots or enterprise IM for manual or semi-automatic compensation.
Implementation Steps (Phased Scheduling)
To make this strategy run stably, it is usually divided into three steps:
Step 1: Align the incremental starting point. During the first go-live, agree with the business side on an "incremental starting time" (for example, 00:00 on the 1st of a certain month). In Qeasy, use this time as the anchor, only pulling incremental data after the starting point without doing a historical full backfill. This avoids a flood of documents on go-live night due to old data.
Step 2: Full trigger and backfill. If the business side explicitly requires historical outsourced warehouse return documents to also be pushed to Wangdiantong, run a separate "full backfill" task in Qeasy, strictly pushing in ascending order of business date and document number. After completion, switch to incremental mode. A typical pitfall here is the lack of isolation between full and incremental tasks — if the incremental task is also running while the full task is running, duplicate documents will appear. The safe approach is to disable the incremental scheduling during the full window.
Step 3: Scheduling frequency and concurrency control. During the incremental phase, it is recommended to run every 10–30 minutes, avoiding the peak business hours of both Kingdee Cosmic and Wangdiantong. Configure scheduled tasks in Qeasy, combined with "document status + last modification time" for the incremental cursor. The cursor itself must be persisted so that the platform can resume running after a restart. It is recommended to start with a conservative concurrency (2–5 concurrent), observe the response of both systems, and then loosen it up.
Pitfall Recap
- Encoding mappings hard-coded in scripts: Three months later, the source side adds a new material, but the target side has no corresponding code, causing the document to fail directly. The safe approach is to make material/organization/unit mappings into a "centralized mapping table" in Qeasy.
- Header and body order reversed or not phased: The Wangdiantong interface requires the document header to exist before details can be pushed. If the Qeasy strategy pushes the header and body in parallel, "dirty" documents with a created header but missing details will appear. The safe approach is to loop and push the body only after the header succeeds, with a clear retry strategy for row-level failures.
- No idempotency, duplicate pushes causing inventory to be incorrectly reduced: When Kingdee Cosmic repushes or Qeasy scheduling reruns, if the external order number is not used as the idempotency key, Wangdiantong will generate multiple return documents, and the physical inventory of the outsourced warehouse will be deducted multiple times. This is easy to get wrong — be sure to use the external order number as the unique key.
- Incremental cursor not persisted: After the Qeasy instance restarts, the cursor is lost, and a full re-fetch happens, which is both slow and dangerous. The safe approach is to persist the cursor to durable storage and resume from the breakpoint after restart.
- Full and incremental scheduling not isolated: During the full backfill window, the incremental task is also running, and documents on both sides overlap on the Wangdiantong side. The safe approach is to explicitly stop the incremental task during the full window and switch after completion.
Applicable & Non-Applicable Scenarios
Applicable: Kingdee Cosmic serves as the supply chain / financial back-end, Wangdiantong serves as the warehouse and distribution front-end. In outsourced processing scenarios, return material outbound synchronization needs to be performed according to sub-item assembly rules, with clear organizations on both sides and a fixed document flow. Not applicable: Outsourced return scenarios requiring real-time, second-level response (this strategy is a minute-level batch synchronization); and scenarios where either the source or target system has undergone major version changes with inconsistent field meanings — these require data governance before synchronization can be discussed.