Purchase Return Material Slip Echo-Back Modification: A Practical Tutorial on a Single Strategy from YiWeiMeng WMS to Kingdee Cloud
What This Strategy Solves
In a private deployment where WMS and ERP are separated, the purchase return material slip often follows a bi-directional chain: "the slip is first created in ERP, executed on the WMS site, and the execution result is then written back to ERP." The problem is that the execution side (the warehouse) is the source of truth, and if the planning side (ERP) does not update the slip status accordingly, the book balance will show that the material has been returned while the physical flow has no record, or vice versa. The strategy focused on in this article is to write the return result back to the corresponding slip in Kingdee Cloud after WMS execution is complete, and to upgrade the one-way push into a bi-directional closed loop through two flag fields—"whether it has been pushed to WMS" and "whether WMS has operated on it."
Data Flow and Field Mapping
Overall flow: WMS (execution result) → Qeasy Data Integration Platform (middle layer) → Kingdee Cloud (target slip modification).
The value of the middle layer is not in "moving data," but in three things: looking up the FID in ERP by slip number, aggregating the extension fields echoed back from WMS, and ensuring idempotency.
Key field mapping table
| Meaning | WMS side (source) | Middle-layer handling | Kingdee side (target) |
|---|---|---|---|
| WMS slip number | bh | Passed through as the association key | Input parameter {{bh}} |
| Warehouse name | ckmc | Passed through | Written to the return slip header |
| Return-to party | thdw | Passed through | Written to the header supplier/return-to party |
| Creation time | cjsj | Passed through | Written to the slip date/audit time |
| Slip internal ID | — | _mongoQuery reverse lookup by FBillNo | FID |
| Whether pushed to WMS | — | Hardcoded to 1 | F_UVQS_CheckBox1 |
| Whether WMS has operated | — | Hardcoded to 1 | F_UVQS_CheckBox2 |
| Form identifier | — | Configuration item | FormId = PUR_MRB |
The last two rows are the key design idea of this solution: using two boolean custom fields as a "handshake protocol," so that the ERP side can tell at a glance which slips have been taken over by WMS and avoid duplicate echo-backs.
How to Configure on Qeasy
When we implemented this strategy on the customer site, we usually configured it in three blocks within the Qeasy Data Integration Platform's strategy canvas.
Source component: Select the connector corresponding to the WMS platform, with API outResult, RESTful POST. This interface itself has query semantics (QUERY) and is used to fetch the details of the return slip after WMS processing is complete; in the request body, wmsbh (warehouse/operation point code on the WMS side) and bh (slip number) are the minimum set needed to locate the slip.
Middle-layer script: This section usually uses Groovy expressions to rename and convert the fields echoed back from WMS, and to converge the _autoFillResponse fields into a standard structure. Centralized management of encoding mappings is a common approach among Qeasy customers—putting the lookup tables for vendors, organizations, warehouses and other master data into an independent mapping component, so that all subsequent return/inbound/return-goods strategies reference it, and a change in one place takes effect globally.
Target component: Select the Kingdee Cloud WebAPI connector, with operation batchSave, FormId fixed as PUR_MRB (Purchase Return Material Slip). FID is not passed in as a direct value; instead, _mongoQuery is used to reverse-lookup by FBillNo = {{bh}}, because Kingdee's internal ID is generated upon creation and should not be held by an external system.
Implementation Steps
Step one, trigger a full run once to do baseline alignment. In the test environment, run a complete echo-back with historical slips to confirm that the FID reverse-lookup, the custom field writes, and the phased header/body submission all work correctly. We are used to running the header first to confirm that the slip can be located, and then opening up the body—phasing header and body is one of the least-pitfall rhythms seen among Qeasy customers.
Step two, set the incremental starting point. The WMS side usually has a timestamp such as update_time or cjsj; use it as the incremental cursor. Set the starting point to midnight on the switchover day to ensure that slips before the switchover are not echoed back repeatedly.
Step three, configure the scheduling frequency. The source outResult is configured with crontab 1 1 1 1 1 (triggered at 1:01 AM every Monday as a fallback full reconciliation); the target batchSave is configured with 3-59/10 7-22 * * * (every 10 minutes during working hours, with a 3-minute offset to avoid peak collisions). Sparse on the source side and high-frequency on the target side is the common pairing for this kind of echo-back strategy.
Step four, gray release and rollback. When going live, release by warehouse—first open a non-core warehouse for a week, verify that the count of slips with F_UVQS_CheckBox1=1 on the Kingdee side matches the WMS operation records, and then open everything.
Pitfall Review
Pitfall one: hardcoding FID as an input parameter. A typical mistake is to write some number from the WMS side directly into Kingdee's FID field, resulting in a "slip does not exist" error. The safe approach is that FID should always go through a reverse lookup, and the external system should never hold the internal ID.
Pitfall two: misunderstanding the custom field type. For Kingdee's CheckBox custom fields, passing in "true"/"1"/the number 1 behaves inconsistently across different versions. In this strategy, hardcoding the string "1" is hardcoded here, and its compatibility has been verified across multiple customer sites as the best.
Pitfall three: not distinguishing the incremental starting point from the full trigger. If the same timestamp is used as both the incremental starting point and the full reconciliation, echo-backs will be duplicated. Dual tracks of incremental and full is a mature approach used by Qeasy customers—the incremental side uses a business timestamp, and the full reconciliation uses an independent "whether it has been echoed back" flag for filtering.
Pitfall four: confusing FormId with Operation. The FormId for batchSave must be the real Kingdee form ID (such as PUR_MRB); do not save effort by writing the strategy name instead.
Pitfall five: mixing the QA test environment with production. This strategy itself is marked "for QA testing only"; before going live, be sure to switch the target end back to the production environment, otherwise you will run into the embarrassment of "test slips being written back to the production system."
Applicable and Inapplicable Scenarios
Applicable: scenarios where WMS and ERP are deployed separately, the return material flow is initiated and executed on the warehouse side, and the execution result needs to be written back to ERP for financial/inventory settlement; suitable for projects with a stable slip structure and custom fields already created.
Not applicable: scenarios where the return material flow is entirely initiated on the ERP side, or where business rules on the WMS side change frequently (custom fields will be repeatedly adjusted); also not suitable for complex return-goods chains that require line-item-level state machine management.