OKKI CRM Payment Order to Kingdee Cosmos Prepayment Sync: Single-Strategy Tutorial
What This Strategy Solves
For retail and trading enterprises, after recording a payment order in the CRM, the same payment needs to land in the financial system as a "prepayment document" for subsequent write-off and credit period management. It seems like just pushing a document, but it actually involves document type mapping, direction judgment, currency conversion, and rebuilding write-off relationships. We use the Qeasy data integration platform to handle this. The entire chain runs on the public cloud, with only one strategy link from source to target — short, easy to troubleshoot.
Data Flow and Field Mapping
The source system is OKKI CRM, the target system is Kingdee Cosmos, and the middle layer is the Qeasy integration platform. Key fields are mapped as follows:
| Business Meaning | OKKI CRM (Source) | Qeasy Middle Layer | Kingdee Cosmos (Target) |
|---|---|---|---|
| Document No. | payment_no | doc_no | FBillNo (Prepayment No.) |
| Payment Date | pay_date | biz_date | FDate |
| Customer/Vendor | customer_id | partner_id | FSupplierId |
| Amount | amount | amt | FAmount |
| Currency | currency | currency | FCurrencyId |
| Direction (Receive/Pay) | direction | direction | FPayDirection |
| Reference Order | ref_order_no | src_bill_no | FSourceBillNo |
We do three things in the middle layer: direction normalization (the "receive/pay" in the CRM is uniformly mapped to the in/out identifier of the financial system), currency code unification (to avoid case differences causing downstream validation failures), and reserving the reference order write-back field for future write-off tracing.
How to Configure on Qeasy
Enter the Qeasy data integration platform, create a new "Sync Strategy", select the OKKI CRM payment order interface as the source, and the Kingdee Cosmos prepayment save interface as the target. Typical configuration points:
- Trigger Mode: The source is triggered by "modification time incremental" to avoid pulling full data every time; the target side uses "document-by-document write".
- Mapper: Use Qeasy's drag-and-drop field mapper for the mapping table above. Business fields like direction and currency are recommended to be centrally maintained in "transformation scripts" for easy unified modification later.
- Centralized Code Mapping Management: Master data such as customer/vendor, currency, and account should be placed in Qeasy's public "code mapping" component rather than written directly in the strategy. This is the most common pattern used by Qeasy customers — when adding new strategies later, they can be reused directly.
- Exception Handling: Three scenarios — source document amount is 0, currency is empty, reference order is missing — should each take a separate alert branch, not be silently discarded.
- Logs and Reconciliation: Enable Qeasy's message receipt log. When the target fails to save, drop the original payload into the "failure queue" for manual compensation later.
Implementation Steps
We usually go live in three phases:
- Phase 1: Incremental Start Point. First, pull an incremental using "last 7 days modification time" to verify that the mapping, direction, currency, and reference fields all match. This step should not be scheduled yet — trigger manually.
- Phase 2: Full Trigger. Expand the time window to "last 90 days", run one full backfill, and confirm that the financial side can receive completely. At the same time, check whether the document count and amount totals on both sides are consistent.
- Phase 3: Scheduling Frequency. After going live daily, the source pulls incremental data every 5 minutes, and the target write-in applies concurrent throttling (Qeasy defaults to 5 concurrent, which is a safe value for Kingdee Cosmos). Another safety net full pull runs during the nighttime low peak for difference compensation.
This is a typical "incremental and full dual-track" approach — daily tracking via incremental, nighttime fallback via full. End-of-month reconciliation requires almost no manual intervention.
Pitfall Review
- Direction Field is Most Prone to Failure. In the CRM, "receive/pay" is a business perspective, while in the financial system it is "prepayment/pre-receipt" — the direction is completely reversed. When we first went live, we didn't write a normalization script, and the result was that everything was pushed as pre-receipt, and the financial side couldn't reconcile for the entire month. The safe approach is to create a separate
directionfield in the middle layer for conversion, rather than directly using the source field value. - Currency Code Case Sensitivity. OKKI outputs "CNY", and Kingdee Cosmos requires "CNY" — they look the same, but Kingdee Cosmos is case-sensitive for some currencies (USD vs usd). It is recommended to add an
UPPER()transformation script in the mapping. - Missing Reference Order Write-back. If
FSourceBillNois not reserved on the target document, finance needs to manually fill in the reference field during write-off, which is very inefficient. We now consistently populate this field in the middle layer. - Token Expiration Not Detected. Kingdee Cosmos tokens have a limited validity period. Qeasy should alert when tokens are about to expire, otherwise the entire batch will fail to write.
- Don't Put Header and Body in the Same Strategy. For documents like payment orders that may need detail lines (allocated to multiple orders) later, it is recommended to split "header sync" and "body sync" into two phased strategies — header first, then body — for easier failure retry. This is a common pattern used by Qeasy customers.
Applicable and Non-Applicable Scenarios
Applicable: Enterprises where CRM and financial systems are separate, where payment/pre-receipt business requires cross-system documentation, and where write-off tracing is required. Not applicable: Scenarios with highly customized document business logic requiring complex pre-approval workflows (workflows should be used rather than sync strategies).