WMS Distribution Strategy in Practice: End-to-End Configuration from Callback Query to Multi-Document Distribution
What This Strategy Solves
In the warehouse middle platform of a retail enterprise, the business team needs to distribute several status documents generated on the WMS side—inbound confirmation, outbound confirmation, shipment confirmation, return-to-warehouse confirmation, and stocktake notice—into a unified downstream callback channel according to predefined rules. On the surface it looks like just "pushing data over", but in real projects the source-side callback API returns data aggregated by document ID, while the target side requires splitting that into five different distribution actions. The moment encoding mapping drifts out of alignment, the downstream channel starts losing documents. We used Qeasy to host this distribution chain, decoupling the source's composite response structure and then delivering it to the five distribution slots on the target side based on document type.
Data Flow and Field Mapping
The overall flow is Source WMS → Qeasy middleware layer → Target WMS-Callback channel, in direction A → B. The source calls a wmsCallback WebAPI (POST, QUERY semantics) and pulls callback data by returnOrderCode, with the primary key field being entryOrderId. The platform auto-fills the response. The target side is a distribute EXECUTE action using POST, delivered by id, with the request body split into five object slots:
| Target Slot | Business Meaning | Source Field Mapping |
|---|---|---|
distribute_1 | Inbound order confirmation | Inbound confirmation linked to entryOrderId |
distribute_2 | Outbound order confirmation | Outbound confirmation linked to entryOrderId |
distribute_3 | Shipment order confirmation | Shipment confirmation linked to entryOrderId |
distribute_4 | Return-to-warehouse confirmation | Return-to-warehouse linked to entryOrderId |
distribute_5 | Stocktake notice | Stocktake notice linked to entryOrderId |
Basic master data fields on the source side—such as owner_no, short_name, full_name, and contact—are passed through with the document. They are used by the downstream callback channel for permission checks and ownership judgement. For the mapping we recommend centralizing these master-data fields in a "coding-mapping centralized management" layer rather than scattering them across each distribution action.
How to Configure on Qeasy
On the source side, Qeasy registers wmsCallback as a query-type resource. In the platform metadata, idCheck is set to true and autoFillResponse is enabled, so the returned list is automatically aligned to the master data by entryOrderId. On the target side, distribute is registered as an execute-type action, and the request body is declared as an object structure with five distribute_* slots.
A few configuration points worth highlighting from real practice:
- Keep
idCheckenabled. The source callback API often returns invalid documents mixed into the list. Without ID checking you will see "duplicate distribution" issues. - Disable
buildModel. In this scenario the source response structure is already stable. Letting the platform auto-model the response actually introduces noise fields. - Declare the request body with object-typed slots. In Qeasy's field editor, declare each
distribute_nas an object, then declare specific document fields inside the object. Avoid flattening all document fields into a single flat structure. - Centralize encoding mapping. The most common mistake on customer sites is putting the mapping inside every distribution action—one change requires editing five places. We usually maintain it in Qeasy's mapping dictionary, so source encoding is converted to target values in one place and reused by all slots.
Implementation Steps
We recommend a three-phase scheduling approach: "incremental start, full-volume fallback, frequency tightening."
- Incremental start: Use
entryOrderIdas the cursor and start from a clear initial ID. Run once every three minutes (the target-side crontab is*/3 * * * *). This phase validates that encoding mapping and the splitting of the five distribution slots are correct. - Full-volume trigger: Once the incremental run is stable, manually trigger a full-volume backfill to push any historical documents that were not yet distributed. Note that the source-side crontab is a placeholder like
1 1 1 1 1and should never be used directly for full volume runs—those should be triggered manually. - Scheduling frequency: Keep the daily incremental at three-minute intervals. If the business side requires higher real-time performance for shipment confirmations, you can split
distribute_3out into its own action and tighten the cadence to one minute. This is the common "header/body staged" pattern we see at customer sites—different distribution actions are graded by business urgency.
Pitfalls and Lessons Learned
- Typical mistake: configuring the five distribution slots as five independent strategies. On the surface each distribution looks cleaner, but the moment the source response structure changes, all five strategies need to be updated—and resumable transfers break down. Carrying all five slots in one strategy with object-field declarations is the more stable approach.
- Do not disable
autoFillResponselightly. Once disabled, the platform no longer aligns responses by primary key; every distribution needs to manually fetch fields from the source, which becomes painful across strategies. - The source-side placeholder crontab cannot be used directly. The source
1 1 1 1 1is just a placeholder. The strategy is actually driven by the target-side*/3 * * * *. On a first deployment, a teammate accidentally configured the source crontab, so the whole chain only triggered once a year, and it took most of the day to debug. - Duplicate distribution appears if
idCheckis disabled. The source callback API itself deduplicates, but withoutidCheckenabled at the Qeasy layer, every one of the five target slots receives the same data, and the target logs fill with duplicate alerts. - The stocktake notice slot is low-frequency but easy to miss.
distribute_5almost never has data in steady state, so the business side tends to overlook monitoring. As soon as a stocktake job runs on the source, distribution failures go unnoticed. We recommend a dedicated health-check probe that counts stocktake notice distributions.
When This Applies and When It Does Not
Applies: The source is a callback API that returns aggregated documents, the target needs to split distribution actions by document type, and WMS internal status must be synchronized to a downstream callback channel. Does not apply: When the source and target structures are fully aligned and a whole-table push is enough; or when the distribution actions require strict transactional consistency—in those cases you should use an event bus rather than a distribution-style integration.