Practical Guide: Syncing After-Sales Shipments and Consignment Shipments from JikeCloud to Kingdee Cosmic
What This Strategy Solves
A multi-channel retail business typically deals with two special order types: after-sales shipment orders and consignment shipment orders (where the supplier ships directly). These two types differ from standard retail orders in terms of ownership flow and settlement rules, and need to be accounted for independently in the financial system.
The single strategy we are implementing this time syncs these two special sales order types from JikeCloud to the corresponding business module in Kingdee Cosmic. It may look like just another sync task, but if coding systems, shipment type fields, and inventory organizations are not designed upfront, the data on both sides will not match after three months.
Data Flow and Field Mapping
The data flow is one-way push: JikeCloud (source) → Qeasy Data Integration Platform (intermediate layer) → Kingdee Cosmic (target).
| Business Meaning | JikeCloud Field | Kingdee Cosmic Field | Mapping Notes |
|---|---|---|---|
| Document Number | bill_no | FBillNo | Pass-through, Qeasy does not modify |
| Business Type | type (91/5) | FBusinessType | Converted via coding mapping table |
| Customer Code | customer_code | FCustId | Routed through master data mapping, centrally maintained |
| Material Code | sku_code | FMaterialId | Looked up via material archive sync table |
| Quantity | qty | FQty | Pass-through |
| Warehouse | warehouse | FStockId | Warehouse code mapping, Qeasy configures converter |
| Document Date | bill_date | FDate | Date format YYYY-MM-DD |
The most critical column is "Business Type". JikeCloud uses 91 for after-sales shipments and 5 for consignment shipments, while Kingdee requires mapping to its own business type codes. We built a dedicated coding mapping table in Qeasy: when the source adds a new type, we just add a row—no need to modify the main flow.
How to Configure on Qeasy
We use the Qeasy Data Integration Platform to host the entire pipeline. The configuration is divided into three parts:
1. Data Source Connection
On the source side, we use Qeasy's JikeCloud·Qimen adapter to filter and pull documents by order type (type=91 or type=5). On the target side, we use the Kingdee Cosmic adapter to invoke the corresponding sales order save interface.
2. Field Mapping and Conversion
Qeasy's mapping canvas supports visual drag-and-drop; complex logic (such as ownership type judgment) is implemented through Groovy scripts. A common practice at customer sites is to extract all code mappings into a "Mapping Table Management" module, so that when the source adds new values, there is no need to modify the main flow script.
3. Exception Handling
Qeasy has built-in retry and alert mechanisms: it automatically retries 3 times on network jitter, and field validation failures are written to an error queue where staff can review and resubmit via the Qeasy console.
Implementation Steps
We proceed in three steps to avoid running a full sync and scrambling both systems at the start.
Step 1: Initial Full Sync
Manually trigger a "Full Sync" in Qeasy, pulling after-sales and consignment shipment orders from the last 30 days. After completion, spot-check the document header and line item quantities and amounts in Kingdee. This is the baseline reconciliation.
Step 2: Configure the Incremental Starting Point
Once the full sync passes, set the starting timestamp in Qeasy's "Incremental Configuration" to the time when the full sync finished. Subsequent runs only fetch incremental data, avoiding duplicates.
Step 3: Scheduling Frequency
After-sales and consignment shipments have moderate real-time requirements (finance can tolerate a few hours of delay), so we configured a 30-minute schedule. Qeasy supports both cron and fixed-interval modes; we used fixed interval for clarity.
We also recommend enabling Qeasy's "Data Validation" step to query the document status back from Kingdee after push, confirming the save was successful.
Pitfalls and Lessons Learned
Pitfall 1: The Business Type Field Was Overlooked
In the early implementation, we only synced the document header and did not pay attention to JikeCloud's type field (91/5). As a result, Kingdee booked these two types of orders as regular retail orders, and the discrepancy was only discovered during month-end reconciliation. The safe approach is to make the business type field explicit at the mapping stage and treat it as a mandatory validation item.
Pitfall 2: Code Mapping Scattered in Scripts
In the first implementation, the warehouse code and material code conversion logic was all written in Groovy scripts. When a new warehouse was added later, we had to modify the script, change the version, and redeploy. After switching to a centralized mapping table, adding a new warehouse only requires adding one row to the mapping table.
Pitfall 3: Wrong Incremental Starting Point Caused Missing Orders
The incremental starting timestamp was set earlier than the last full-sync document's time, resulting in a week of old orders being re-synced; setting it the other way would cause missing orders. The safe approach: record the end time immediately after the full sync completes, and set the incremental starting point = that timestamp - 1 minute, leaving a buffer.
Pitfall 4: Header and Line Items Pushed in One Go
To save time, some clients push the header and line items in the same request. When Kingdee's transaction rolls back, it easily results in "header exists but no lines". The safe approach is to split into two steps: first push the header to get the document's internal ID returned by Kingdee, then push the line items with the internal ID. Qeasy's canvas supports orchestrating these two actions as sequential steps.
Pitfall 5: Settlement Party Issue in Consignment Shipments
The settlement party for consignment shipments is the supplier, not the end customer. In the early sync, we directly pushed the customer code from JikeCloud, causing the wrong invoicing target in Kingdee. Later, we added a branch in Qeasy: when type=5, the settlement party field takes the supplier code.
Applicable and Non-Applicable Scenarios
Applicable: Multi-channel retail enterprises that use JikeCloud as the front-end OMS and Kingdee Cosmic as the back-end ERP, where after-sales and consignment shipments need to enter the financial accounting system; real-time requirements are moderate (T+0.5 hour is acceptable).
Not Applicable: Scenarios requiring bi-directional sync (e.g., Kingdee needs to write shipment status back to JikeCloud); scenarios with extremely high document volume and second-level real-time requirements (should use message queues instead of scheduled pulling); scenarios where the source type field changes frequently and there is no master data governance.