Qeasy Cloud
Get Started

Sales Order Sync Strategy in Practice: Pushing from CRM to ERP Using a Xiaoman OKKICRM to Yonyou BIP Example

· 王浩宇· Integration Solutions· 10 views· 5 min read

What This Strategy Solves

Sales orders are created in the CRM by sales reps and pushed through the pipeline as opportunities. In the ERP, those orders feed production, inventory, and financial accounting. If the master data definitions drift between the two sides, three months later you will see the embarrassing gap where CRM says customer A placed 8 million worth of orders, while ERP only received 6.2 million.

The single strategy we are handling here pushes changes to sales orders from CRM to ERP in an incremental way, modifying only, never inserting. The order already exists in ERP; CRM is the source, ERP is the receiver that gets updated. On the Qeasy data integration platform, this kind of "one-way push, update only" strategy is very typical, and it is also the easiest one to trip over: what gets pushed is change, while base records and newly created documents must be handled by other strategies.

Data Flow and Field Mapping

The whole chain is one-way: Xiaoman OKKICRM → Qeasy middle layer → Yonyou BIP (Y/ERP module). The table below is the key field mapping we have organized. In real projects, customers usually add a few more business-specific fields on top of this.

Business MeaningSource (CRM)Middle LayerTarget (ERP)Handling Notes
Order numberbillNobillNocodeString, passed through
Customer codecustomerIdcustomerCodecustCodeResolved via mapping table
SalespersonownerownerNamesalemanName-to-ID mapping
Total amounttotalAmounttotalAmounttotalMoneyPrecision aligned, 2 decimals
CurrencycurrencycurrencycurrencyTypeCRM defaults CNY, ERP requires explicit value
Order statusstatusstatusorderStatusState machine aligned, "Draft" filtered out
Line numberitems[].seqlineNodetailList[].lineNoArray expanded, order preserved
Product codeitems[].productIdproductCodedetailList[].invCodeThrough unified material mapping table
Quantityitems[].qtyqtydetailList[].quantityMain unit conversion
Tax-inclusive priceitems[].taxPricetaxPricedetailList[].pricePrice precision, no truncation

When we onboard this on Qeasy, we usually pull the three categories of mappings (customer codes, product codes, and currencies) out into a "centralized code mapping" dictionary on the platform, so every strategy can reuse it. The visible benefit on the customer side is: when one customer code changes, only one place needs to be updated, and all strategies pick it up.

How to Configure on Qeasy

When the strategy lands on Qeasy, the core is wrapping the source system interface, field mapping, and target system write into three segments. The following are the typical configuration points.

1. Source data source. Pick the CRM OpenAPI, and use whatever authentication the customer provides. The key thing is the pagination parameters. CRM list interfaces usually have a cursor or pageSize, and you must make sure the cursor field name is right.

2. Fetch conditions and incremental fields. This strategy is "push when modified," so the incremental field is lastModifyTime. Be careful: the CRM's time zone is not necessarily the same as the database time zone. The safe practice is for the platform side to always store UTC, and convert when showing it to the customer.

3. Field mapper. In the Qeasy mapping canvas, our habit is to route code-type fields (customer, product, currency, organization) through a "lookup" node, numeric fields through direct expressions, and text fields through trim and case normalization. The common pattern on customer sites is "headers and line items in stages": first verify the header confirms the order state is legal, then expand the items[] array to write the line items. If any line fails, the whole order rolls back.

4. Target write. The ERP sales order modification interface usually locates by order number. The request body must carry both code and the organization code orgCode. Missing either will fail. The Qeasy target component will mark these two fields as mandatory validation.

5. Failure handling. When configuring retry strategy, we separate "field format errors" from "business validation errors." The former has no point in retrying and should go into a manual queue. The latter, like "customer credit exceeded," should be written back to the CRM's remark field to alert the salesperson.

Implementation Steps

In the customer's on-premises environment, our rollout rhythm is broken down like this. Customers that follow this order almost never get it wrong.

Step 1: Master data in place first. The four master data categories, materials, customers, currencies, and organizations, must be aligned on both CRM and ERP sides first. This is not done by this strategy, but if it is not done, do not start this strategy, or you will push a lot of dirty data into ERP.

Step 2: Define the incremental starting point. We generally suggest the customer pick a "natural day cutover," for example all orders modified after 00:00 on the go-live day with status ≥ approved, as the initial sync scope. In Qeasy, set the startModifyTime through a time filter component.

Step 3: First-time full reconciliation. Once the incremental is running, run a "full comparison" script in parallel. Compare the current order status in CRM with ERP and have a human confirm the differences. This is an indispensable step for a safe go-live. Qeasy supports running the full script as an independent strategy, in parallel with the incremental, without conflict.

Step 4: Daily scheduling frequency. For this kind of "update only" strategy, the typical cadence is one round every 5 to 10 minutes. A common customer practice is every 5 minutes during business hours and every 30 minutes at night. Scheduling is configured in Qeasy's "scheduled trigger," which pulls the source interface according to a crontab expression.

Step 5: Observation period and cutover. Keep a 7-day observation period after go-live. During this period, any order change is first verified in the test ERP database. Once verified, switch to the production database.

Pitfall Retrospective

These five are pitfalls we have gone through with customers. Each one really happened.

1. State machines not aligned. CRM's "Placed" is not the same as ERP's "Pending Approval." Passing the status straight through will be blocked by ERP's business validation. The safe practice is to add a "state conversion table" in the mapping.

2. Array fields swallowed. Items[] and similar line item arrays get compressed into JSON strings by many integration tools and the ERP side cannot parse them. The Qeasy array expansion node must be explicitly enabled, and every sub-item's field path must be correct.

3. Unit price precision truncated. The source side uses 0.1 precision Decimal, the target side uses 0.0001 precision. If you do not force rounding to the target precision in the mapping, you will accumulate 0.01-yuan differences, and by month-end reconciliation it is too late to cry.

4. Time zone causes missing orders. The incremental field lastModifyTime uses the CRM application's local time zone, while the database stores UTC. During cross-day scheduling, you get the spooky result: "orders changed yesterday did not get pushed today." Either hardcode the time zone in the source component, or normalize it in Qeasy.

5. Full script fights the incremental. When the full script and the incremental run at the same time, you get a race: "the same order first gets pushed to status A by the full script, then overwritten to status B by the incremental." When running incremental and full in parallel, either stagger them, or add an idempotency key to the target interface (order number + modification timestamp).

Suitable and Unsuitable Scenarios

Suitable: CRM is the order source, ERP handles production and financial accounting, the order is already created in ERP, and CRM only does modifications and voiding. This is a "one-way update" synchronization. Not suitable: order creation happens in CRM and requires the ERP document number to flow back ("two-way sync"), and small systems without a reliable incremental field that have to rely on full polling.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-okkicrm-bip-8081-ys-ok-b7f31a00

Comments