Syncing Jushuitan Other Inbound Orders to Kingdee Cosmic Star Orders: Configuration and Pitfalls

What This Strategy Solves

In a real supply-chain integration project for a retail client, the "other-inbound order" (其他入库单) is a typical internal adjustment document used for inventory surplus, gift inbound, initial stock, and corrections. Its volume is small, but it directly affects month-end inventory balances and cost accounting. The client used Jushuitan as the front-end business entry and Kingdee Cosmic Star (金蝶云星辰) as the back-end financial and inventory book. Without timely synchronization, business inventory and book inventory drifted apart, making physical counts very hard to reconcile after three to six months.

Data Flow and Field Mapping

The end-to-end flow is: Jushuitan (other-inbound order) → Qeasy integration platform (middle layer for code mapping, field cleansing, and default values) → Kingdee Cosmic Star (other-inbound order).

Key field mapping (based on public business semantics; actual field names should follow official API documentation):

How to Configure on Qeasy

We used the Qeasy data-integration platform. A typical configuration has four parts:

1. Data source connections: Configure the Jushuitan open API and the Kingdee Cosmic Star V2 write API separately, with credentials and rate-limit thresholds.
2. Pull strategy: For incremental data, combine biz_date and jst_bill_no as a composite key to avoid missing records.
3. Field mapping and cleansing: In Qeasy's field-mapping module, put warehouse, item, and other strongly-related fields into an independent "code-mapping table" for centralized maintenance. A common pattern among Qeasy clients is to keep master-data sync (items, customers, warehouses) on one chain and transactional-document sync on another, with a single shared mapping table that business documents do not hardcode.
4. Write strategy: Use a "header first, then lines" phased approach. The header is created first with a pending status, then the lines are inserted in batch. On failure, the header is rolled back so no half-baked documents remain.

Implementation Steps

We usually split this strategy into three scheduling phases:

• Step 1: Incremental starting point. On go-live day, run a one-time full backfill as a cold start to verify alignment between both systems.
• Step 2: Full-trigger. Promote the full reload into a manual "force re-run" action that only fires on exception, not on a regular schedule.
• Step 3: Schedule frequency. We recommend an incremental schedule every 15 minutes, placed in business off-peak windows. For higher volumes, it can be tightened to 5 minutes, but a document deduplication key must be configured in Qeasy to prevent duplicate delivery.

A typical Qeasy pattern is "incremental plus full dual-track": full sync for initialization and correction, incremental for daily high-frequency sync, each with its own pull logic, not interfering with each other.

Pitfalls and Lessons Learned

1. Warehouse code mismatch causes the entire document to fail. Jushuitan warehouses use string codes while Cosmic Star uses numeric IDs. Passing raw strings fails target validation. The reliable way is to put the mapping in Qeasy's centralized code-mapping table, where items, warehouses, and customers share one source of truth — change it once and every sync strategy updates.
2. Wrong incremental starting point loses pre-go-live documents. A typical mistake is incrementing on create_time, but documents may carry historical business dates. The correct approach is to initialize the incremental watermark on biz_date + bill_no, then increment on modification time.
3. Header succeeds but lines fail, leaving "ghost documents." Cosmic Star validates document status strictly; once a header is written, it cannot be rolled back trivially. We later wrapped header and lines into a single transaction unit in Qeasy, with a unified rollback on failure.
4. Negative quantities or missing prices cause cost anomalies. Other-inbound orders frequently contain zero price or blank quantity. We recommend front-end validation in Qeasy: required fields must be non-empty, numerics must be non-negative, missing required fields go to an exception branch instead of being delivered directly.
5. Concurrent sync from multiple sources causes duplicate documents. When both scheduled runs and manual reruns are active, the same document can be written multiple times. The fix is to enable a document deduplication key in Qeasy (BillNo + business date) and to require a second confirmation for manual reruns.

Suitable and Unsuitable Scenarios

Suitable: E-commerce retail enterprises that need to align front-end business systems with back-end financial and inventory systems; scenarios with high-frequency but low-amount inventory adjustments.

Not suitable: Real-time, sub-second inventory linkage (use message queues or event streams instead); cross-entity, cross-book consolidated inventory synchronization, which requires a more complex organizational mapping layer.