Sales Order Sync in Practice: Mapping YonBIP NCC Sales Orders to Jky Stock-In Documents

What This Strategy Solves

In a real engagement with a retail enterprise that runs financial and supply-chain ledgers in YonBIP NCC while using Jky for downstream warehousing and store fulfillment, a gap kept appearing: sales orders—especially those on the "blue" logistics-company business line—were created in NCC, but the warehouse in Jky still needed a corresponding stock-in document to receive and put away goods. The structures don't line up, and the business demanded a 30-minute catch-up cadence. We delivered this with the Qeasy Data Integration Platform, turning the cross-system document translation into a single, isolated strategy that neither pollutes NCC master data nor forces warehouse staff to manually re-key entries.

Data Flow and Field Mapping

The overall flow is YonBIP NCC (source) → Qeasy middle layer → Jky (target). The source calls NCC's /nccloud/api/so/saleorder/querybyscheme to pull orders incrementally by document date. The middle layer performs code translation, field concatenation, and idempotency control. The target calls Jky's erp.stock.createandstockin to generate the stock-in document.

Business Meaning	YonBIP NCC (Source)	Jky (Target)	Handling Notes
Warehouse code	`so_so_saleorder_b.csendstockorgid.code` + `csendstordocid.code`	`inWarehouseCode`	Concatenated with `-`; becomes Jky's warehouse primary key
Stock-in type	—	`inType`	Fixed value `104` (other stock-in), since logistics-company returns/transfers are not purchases
Related document ID	`so_so_saleorder.vbillcode`	`relDataId`	Carries the NCC document number as part of the idempotency key
Apply time	`so_so_saleorder.ts`	`applyDate`	Uses NCC timestamp to avoid timezone drift
Memo	—	`memo`	Concatenated as `Agent flow-{docNo}` so the warehouse can identify the source

The source request uses dbilldate as an incremental range (LAST_SYNC_TIME to CURRENT_TIME), with multi-value pk_org for sales organizations and a precise ccustomerid filter to tighten the scope.

How to Configure It on Qeasy

In Qeasy this strategy is split into three segments: source reader → field mapping → target writer.

Source reader: pick the WebAPI/POST adapter, point it at NCC's querybyscheme endpoint, and enable idCheck plus autoFillResponse so the response body expands into mappable fields automatically.
Middle-layer mapping: drag source fields onto target fields. Warehouse code uses a concat function to join the two code segments; memo uses a template string. One common pattern among Qeasy customers is centralized code-mapping management: extract organization, customer, and warehouse code tables into a shared mapping sheet so other strategies can reuse them, instead of redefining per strategy.
Target writer: choose Jky's erp.stock.createandstockin, set number to the returned id, and turn on idCheck. That way a second push of the same document is recognized as idempotent and won't create duplicates.

Implementation Steps

We adopted the classic incremental-plus-full dual-track approach in three phases:

Phase 1: Full trigger (initial run). Manually rewind LAST_SYNC_TIME to three months before go-live, run a historical backfill, and reconcile counts on both sides; stop at the most recent timestamp afterward.
Phase 2: Incremental start. Switch to scheduled mode. The source crontab is 1-59/30 6-23 * * * (every 30 minutes during business hours); the target crontab is 5-59/10 6-23 * * * (every 10 minutes, intentionally offset by 5 minutes to leave a processing window).
Phase 3: Steady-state monitoring. Use Qeasy's run logs and failure-replay mechanism to watch for two anomaly types: empty responses from the source (likely NCC maintenance windows) and unresolved warehouse codes on the target (typically new sales organizations whose mappings haven't been maintained).

Another common pattern is rolling out header and body in stages: stabilize header fields first, then open up body line items. This avoids being buried in a flood of detail lines when troubleshooting.

Post-Mortem: Lessons from the Field

Hard-coded warehouse concatenation backfired. We initially hard-coded org-warehouse as a string. When Jky later revised its warehouse naming convention, documents landed on an "unknown warehouse" in bulk. The safe approach is to externalize the mapping into a shared table so changes happen in one place.
Wrong stock-in type. A classic mistake is writing 104 as 101 (purchase stock-in), which breaks both inventory and purchasing accounts. Before go-live, confirm with the business whether the "blue logistics-company" line counts as purchase or other stock-in.
Wrong incremental starting point. On the first go-live someone set LAST_SYNC_TIME to "today at 00:00", which silently dropped the morning's orders. During backfill, always use a historical window for the full run; never jump straight into incremental.
Idempotency key uses only the document number. The same NCC document number may be pushed again after modification, producing duplicate stock-in documents on the target. The safe approach is to use document number + timestamp or document number + version as the idempotency key.
Misaligned schedules caused empty target runs. With source every 30 minutes and target every 10 minutes, the target keeps firing before the source has produced data, leaving logs full of "0 records."

When to Use and When Not To

Use it when: there's a clear sales-order source-of-truth, orders need to flow into a downstream WMS/fulfillment system in near real time, and the coding conventions on both sides are relatively stable. Don't use it when: cross-organization document revisions are frequent, line-level write-back is required (e.g., NCC needs to post reversals based on Jky receiving results), or warehouse master-data rules on either side are still unstable—in the latter case, fix master data first, then sync.