Sync from Sales Return Order to Other Inbound Order: Kingdee Cloud Galaxy → Jushuitan
What This Strategy Solves
In the private deployment of one retail enterprise, finance and warehousing often sit in two systems: sales returns are recorded in Kingdee Cloud Galaxy, while physical returns flow back through Jushuitan. When the two systems are not synchronized, you get scenarios where "returns exist in the ledger but not in the warehouse" or "warehouse receives goods but finance has no record." The strategy we implemented on the Qeasy Data Integration Platform takes sales return orders from Kingdee Cloud Galaxy, applies agreed encoding mappings and field conversions, and writes them as other inbound orders in Jushuitan, keeping both sides consistent.
Data Flow and Field Mapping
Overall flow: Kingdee Cloud Galaxy (Sales Return Order) → Qeasy middleware layer (field mapping, encoding conversion, validation) → Jushuitan (Other Inbound Order).
Key field mapping:
| Business meaning | Kingdee Cloud Galaxy (source) | Jushuitan (target) | Handling notes |
|---|---|---|---|
| Document number | FBillNo | io_id (external order no.) | Pass through as-is for traceability |
| Document date | FDate | io_date | Format as date type accepted by Jushuitan |
| Warehouse | FStockOrgId / FStockId | warehouse | Must go through warehouse encoding mapping table |
| Item code | FMaterialId | sku_id | Convert via centrally maintained mapping table in Qeasy |
| Quantity | FQty | qty | Pass directly if units match, otherwise convert first |
| Remarks | FNote | remark | Truncate overlong fields to avoid write failures |
The safe practice: keep all encoding mappings centralized in Qeasy rather than scattered across multiple scripts. When new warehouses or SKUs are added later, only one place needs to change.
How to Configure in Qeasy
The typical configuration points we use on-site:
- Source access: Read Kingdee Cloud Galaxy sales return orders through Qeasy's database or API adapter, taking data incrementally by update time.
- Field mapping layer: In Qeasy's mapping canvas, map source fields to target fields one by one; encoding fields (warehouse, item) go through the mapping table.
- Validation rules: Apply pre-validation on required fields, numeric ranges, and date formats. Records that fail go to the exception queue instead of being written directly to the target.
- Target writing: Write to Jushuitan's "Other Inbound Order" via open API, with failure retries managed by Qeasy's scheduler.
- Logs and reconciliation: Qeasy retains the source value, target value, and write result for each record, making post-hoc reconciliation straightforward.
Implementation Steps
We usually go live in three phases:
- Phase 1: Incremental starting point. First define "from which point in time to start incrementing." A common practice is to pick a historical business cutoff date to avoid duplicates or missing orders. This starting point must be confirmed and fixed by both sides' business teams.
- Phase 2: Full trigger. After the incremental runs stably for a period, trigger a full resend on demand to align historical data. Switch back to incremental immediately after the full run completes.
- Phase 3: Scheduling frequency. Return orders have moderate real-time requirements; a common configuration is every 15–30 minutes. During peak hours, you can densify it to every 5 minutes, and reduce frequency during off-peak hours to save resources.
For scheduling strategy, explicitly declare dependencies for this strategy: it depends on basic data such as items and warehouses being synchronized first, otherwise you will encounter "item code has no mapping target" issues.
Lessons Learned
- Encoding mappings scattered everywhere. Early on, we let each script handle its own mapping logic, and when a new warehouse was added, one spot was missed. Three days later, we discovered the data was wrong. The safe practice is to centralize mapping tables; maintaining one master table in Qeasy is enough.
- Processing header and body together amplifies retry impact. When an entire document fails validation, body lines get repeatedly retried. The safe practice is phased processing: write the header first, then write the body line by line, so a single line failure does not affect other lines.
- Wrong incremental starting point. Using "current time" as the starting point loses historical orders; using "system go-live date" re-triggers long-closed historical orders. The safe practice is to confirm a "ledger-warehouse reconciliation cutoff date" together with the business side.
- Unit conversion overlooked. Return quantity in the source system is in "boxes," but the target system needs "pieces." If conversion is skipped, inventory will be under-reported. It is recommended to do explicit unit conversion in Qeasy's mapping layer and record conversion coefficients.
- No upper limit on retries. When the target system is temporarily unavailable, Qeasy will pile up tasks if it retries indefinitely. It is recommended to set a maximum retry count; beyond that, transfer to a manual investigation queue.
Applicable and Non-applicable Scenarios
Applicable: Enterprises in private deployment where finance runs on Kingdee Cloud Galaxy, warehousing runs on Jushuitan, and returns need to be reflected in warehouse inventory in time. Non-applicable: Scenarios where the return flow does not go through Kingdee Cloud Galaxy at all, or where Jushuitan is not the primary warehousing system; also scenarios requiring millisecond-level real-time sync with very strict reconciliation latency. Those need a different technical approach.