Jushuitan Other Inbound to Xingchen Other Inbound: One Strategy to Master Inventory Document Sync

What This Strategy Solves

In retail and warehouse-integrated operations, "Other Inbound Orders" typically cover scenarios like return-to-stock, inventory surplus, transfer-in, and assembly/disassembly. In one real engagement, a retailer had dozens to hundreds of such documents per day scattered across the front-end system, while finance and the central warehouse required real-time booking in the back-end ERP. With mismatched document numbers and inconsistent field semantics, manual re-entry over three months routinely led to discrepancies in the hundreds of thousands.

This strategy delivers timely, semantically-aligned sync of Other Inbound Orders from the source to the target, generating auditable, bookable documents on the target side. We use the Qeasy Data Integration Platform as the middleware, centralizing code mapping and field-semantic convergence so the source and target systems stay decoupled.

Data Flow and Field Mapping

The overall flow is unidirectional, following the typical three-stage pattern:

Source System (Other Inbound) → Qeasy Middleware → Target ERP (Other Inbound)

Key fields are mapped as follows. Real projects usually require additional mapping by organization and stock direction on the target side:

The two mapping tables—warehouse code and material code—are the most typical application of centralized code-mapping management on Qeasy. When the client opens a new warehouse or launches a new SKU later, only one row needs to be added to the mapping table; the strategy body stays untouched.

Configuring on Qeasy

In the strategy editor on the Qeasy Data Integration Platform, this strategy typically consists of four core configuration blocks:

1. Data source registration: The source side pulls documents via its open API, while the target side writes through its document-save API. Credentials for both sides are stored in Qeasy connectors—never hard-coded in the strategy body.
2. Pull condition: After the incremental starting point, fetch where modified ≥ last success time; on a full-trigger run, clear the cursor and re-pull by business date range.
3. Field mapping and transformation scripts: Header fields undergo date-format and stock-direction normalization; body rows go through code mapping; qty is validated for sign retention, with negative values routed to the return-to-stock logic.
4. Write-back and acknowledgment: After writing to the target, the document's internal ID returned by the target is written back to the middleware as the anchor for reconciliation and reruns.

Implementation Steps

We typically split go-live into three phases, validating repeatedly on-site before switching to production scheduling:

• Phase 1: Establish the incremental starting point. Pick a clear cutoff time in the test environment (e.g., 23:59 on a specific day) and sync only increments after that point. This step trips up the most teams—set it too early and you get duplicates; too late and you miss data. The safe approach is to backfill historical data via a full sync first, then chase new data with incremental sync.
• Phase 2: Full-trigger run and reconciliation. Synchronize existing documents in date-bounded batches, reconciling both sides after each batch. A common pattern on Qeasy is header-then-body staging: write headers in bulk and stage them, then attach bodies document by document. This avoids errors when the target API is hit with full-batch payloads.
• Phase 3: Lock down the schedule. In retail scenarios, incremental polling is typically set to every 5–15 minutes; an end-of-day reconciliation job then cross-checks document counts and amounts. Incremental and full sync run in parallel—incremental for real-time, full as the safety net. Either side can be rerun on failure.

Pitfalls and Lessons Learned

1. Idempotency key design flaw. The source system's io_id is not a natural unique key on the target side. Using Document No. as the idempotency key causes modification-after-sync to be misread as a new document. The safe approach is a composite key of source primary key plus write timestamp.
2. Inconsistent warehouse code semantics. "Central warehouse" in the source and "main warehouse" in the target may refer to the same physical warehouse but carry different codes. Hard-coding these into the strategy does not scale—centralized code-mapping management is the long-term answer.
3. Quantity signs get dropped. Transfer-out quantities within Other Inbound documents are negative. If the front-end table treats the field as text, the sign is lost and the target side ends up with doubled quantities. Transformation scripts must enforce numeric coercion and sign preservation.
4. Modifications and voiding don't flow back. When a synced document is modified in the source, chasing only by incremental timestamp can miss intermediate versions. The middleware should retain the latest N versions, with the target applying updates by version number.
5. Cross-org, multi-book mixing. When one strategy is reused across organizations, the org identifier must be carried explicitly in the request parameters. Otherwise the target writes to the default organization, causing documents to land in the wrong book.

When to Use and When Not to Use

Use when: the source system serves as the store-and-warehouse front end while the target ERP serves as the finance and general-ledger back end, and non-purchasing inbound documents need to be synced and booked on time—typical of retail and warehouse-integrated businesses.

Do not use when: the target side enforces a strict approval workflow with a complex state machine and expects documents to be created manually within the target itself; or when a large group runs multiple organizations/books in parallel, each requiring its own independent code system. The latter case should be split into multiple strategies, one per organization.