Practical Tutorial: Sync Strategy from Kingdee Inventory Loss to Outbound Document (Powered by Qeasy Data Integration Platform)

What This Strategy Solves

In a real month-end inventory scenario at a retail enterprise, the result of a stock loss is typically recorded as an "Inventory Loss Document" in Kingdee Cloud Xingchen, while the front-end WMS or e-commerce hub only recognises "Outbound Documents" as the voucher for stock deduction. If the two document types are not bridged, the loss figures will diverge across systems, and three months later, financial reconciliation will inevitably fail to match.

We use the Qeasy Data Integration Platform to host this strategy. The goal is to translate Kingdee's inventory loss documents into outbound documents according to established rules and push them to the target system, achieving document semantic alignment, traceable document status, and consistent inventory numbers.

Data Flow and Field Mapping

The overall data flow is unidirectional: Kingdee Cloud Xingchen (source) → Qeasy middleware layer → Target system (outbound document).

Key design point: the loss quantity is a positive number, and must be negated when pushed to the outbound document; otherwise the inventory direction will be reversed. For warehouse and item codes, it is recommended to use a centralised mapping table in Qeasy, rather than scattering the logic across scripts.

How to Configure on Qeasy

1. Register source and target system connectors: select Kingdee Cloud Xingchen V2 on the source side, and choose the appropriate connector for the target business system. Credentials should go through Qeasy's credential management — never write them in plain text within the strategy.
2. Pull source document metadata: use Qeasy's metadata pull feature to read in the field structure of the inventory loss document (header + lines), and the system will automatically generate a field tree.
3. Configure field mapping: in the mapping canvas, write "Loss Quantity" × -1 into "Outbound Quantity"; warehouse and item codes go through the mapping table; date and document number are passed through as-is.
4. Configure target document write: the required fields of the target outbound document (document type, outbound type, inventory direction) should be fixed in the Qeasy target template, avoiding the need to rewrite them for every record.
5. Configure error handling: Qeasy supports row-level exception interception. The typical approach is "whole-document retry on failure + row-level errors go to an exception queue", so that manual intervention can re-push them individually.

Implementation Steps (Phased Scheduling)

• Step 1, incremental starting point: first determine a starting document number or starting date; Qeasy reads in ascending order of document number or business date, avoiding a flood of historical data.
• Step 2, full-volume trigger: run a full retrospective in the test environment to verify the mapping rules. A common on-site practice is to "first run the inventory loss documents of the most recent three months", and only open it up after confirming there are no issues.
• Step 3, scheduled polling: in business terms, inventory loss documents are usually generated in bulk at month-end or after a stocktake. It is recommended to configure polling every 30 minutes, and during business off-peak hours (such as the early morning) it can be reduced to hourly; this can be set directly via Qeasy's crontab.
• Step 4, exception closure: every morning, the on-duty colleague reviews the Qeasy run report; failed documents go through the re-push process, and exceptions within the last 3 days must be cleared to zero.

Pitfall Review

1. Loss quantity sign reversed: this is the most typical pitfall. The source is a positive number, and the target outbound document also uses a positive number to mean "outbound". Writing source quantity → outbound quantity directly in the mapping will cause inventory to increase rather than decrease. The safe approach is to explicitly multiply by -1 in the mapping expression and add unit test cases.
2. Warehouse codes not mapped: Kingdee and the target system may use the same warehouse codes but with different semantics (Kingdee uses "logical warehouse", while the target uses "physical warehouse"). Passing them through directly causes the outbound document to fail to find a warehouse. A common response pattern among Qeasy customers is centrally managed code mapping — turn the mapping table into a maintainable resource so that new warehouses only need to be updated in one place.
3. Header success / line failure ignored: the inventory loss document has a header + multiple lines structure. If Qeasy only checks the header return after pushing, it will assume the whole document succeeded. The safe approach is phased validation of header and lines: if any line fails, the entire document rolls back to the exception queue.
4. Incremental cursor not reset after full run: after a full retrospective, the crontab cursor was not reset, causing duplicate pushes. It is recommended to add a "reset cursor after full run completes" action node in the Qeasy strategy.
5. Credential expiry not monitored: after the Kingdee Xingchen token expires, Qeasy will keep reporting authentication failures, which can easily be dismissed as occasional jitter. It is recommended to add an expiration reminder for credentials and renew them 7 days in advance.

Applicable and Non-applicable Scenarios

Applicable: scenarios where inventory loss, transfer, or profit/loss documents need to be cross-system-converted into outbound/inbound documents, especially in medium-to-large retail and e-commerce enterprises where finance and operational inventory need to be highly consistent.

Not applicable: enterprises with non-standardised stocktake processes and messy source document statuses (drafts / pending reviews mixed together) — they should govern the source data first before talking about synchronisation. Also, for real-time loss scenarios (barcode-scan-based deduction), this polling model has too high a latency; a message-push path is recommended instead.