Sales Order Master Data Sync Practice: A Deep Dive into the XiaoMan OKKI CRM Customer Query Strategy
What This Strategy Solves
In the sales order integration pipeline, customer master data is the prerequisite for every order write: without a clean customer profile, downstream order creation, payment reconciliation, and shipping matching will all carry dirty data. The specific strategy we are discussing here is 'Query XiaoMan Customers'. Its task is straightforward: pull customer data from the CRM side incrementally by time window, land it into the Qeasy middle layer, and serve as the foundational profile base table for the entire sales order pipeline.
Data Flow and Field Mapping
The data flow is very clear:
Source system (XiaoMan OKKI CRM) → Qeasy Integration Platform (Qeasy middle layer) → consumed by subsequent sales order write strategies.
The source-side query interface is GET /v1/company/updates. Pagination parameters include start_index (default 1) and count (default 20). removed=0 means do not include deleted records; all=1 means query all customers; group_id is optional (used for filtering by customer group); date serves as the incremental starting point. The unique customer identifier in the response is company_id, and the serial number is serial_id.
The target side on Qeasy is a 'write null operation' (POST), used to persist the customer profile into the middle-layer table with the id field, so that subsequent sales order strategies can reference it by company_id.
Below is the key field mapping table we organized on the customer site:
| Business Meaning | Source Field | Target Field | Notes |
|---|---|---|---|
| Customer unique identifier | company_id | id | Primary key, order join key |
| Customer serial number | serial_id | serial_id | Serial number, auxiliary sorting |
| Customer name | name | name | Name normalization handled in middle layer |
| Group ID | group_id | group_id | Optional, filter condition |
| Deletion flag | removed | removed | Incremental window control |
| Last updated time | date | updated_at | Incremental starting point |
There is one design point that is easy to overlook: centralized management of code mapping. We maintain the 'XiaoMan company_id ↔ Qeasy id' mapping in a mapping table on Qeasy, rather than hardcoding it in each order write strategy. This way, when extending to a third-party CRM in the future, we only need to append mapping rows.
How to Configure on Qeasy
In the Qeasy Data Integration Platform, this strategy is a typical QUERY_ONLY type. There are several key configuration points:
-
Data source registration: Register XiaoMan OKKI CRM as a platform access point. Authentication information (keys, tenant identifiers, etc.) is configured in the Qeasy connector. We won't go into detail here, but one reminder — do not store keys in the strategy configuration; keep them at the connector layer.
-
Request parameter template: Make the pagination parameters
start_index,count,removed=0,all=1into a template. The initial request usesstart_index=1, and subsequent requests paginate based ontotalorhas_morein the response. The incremental starting pointdatecomes from a cursor variable maintained by Qeasy (the maximum update time of the last successful sync). -
Target write: The 'write null operation' on the target side is not really null — it lands the customer profile into a Qeasy middle-layer table, with field names following the source side. Subsequent order strategies consume it via JOIN. Here we adopt the 'header-table and body-table phased' pattern: the customer profile only goes into the header table, and the subsequent orders bring line items, avoiding mixing customer, contact, and address data into one batch.
-
ID check: The target-side
idCheck=trueindicates primary key deduplication and idempotency check — multiple syncs of the samecompany_idwill not result in duplicate inserts. This is the safety net for data consistency. -
crontab and dependencies: The crontab in the source strategy example is written as
*/20 8-22 * * *, meaning a round every 20 minutes during business hours. In Qeasy we configure this in the schedule center, using a first-time full trigger + subsequent incremental dual-track approach: the night of go-live, we manually run a full sync to fill in the historical customer profiles, then enter the*/20incremental rhythm.
Implementation Steps
Phased scheduling is the key to whether this strategy can run stably. The implementation order we followed on the customer site is as follows:
- Step 1 · Full starting point: Before go-live, manually trigger a full query in Qeasy, with
removed=0&all=1to pull all existing customers. This step is to fill the baseline of the middle-layer table. - Step 2 · Cursor initialization: After the full sync completes, Qeasy automatically records the maximum
dateas the incremental cursor and stores it in a state variable. - Step 3 · Incremental scheduling: Enter the
*/20 8-22 * * *incremental rhythm; each round advances the cursor by one page. - Step 4 · Pagination control: Determine from the response whether there is a next page. If yes, continue paginating; if no, refresh the cursor and wait for the next round.
- Step 5 · Dependency linkage: This strategy has an empty
depends_on, meaning it must run before the sales order write strategies. We use Qeasy's strategy orchestration to place customer profile sync upstream of order writing.
Lessons Learned from Pitfalls
- Forgot to pass the
removedparameter, causing previously deleted customers to be pulled back in. A typical mistake is overlooking the default value. The safe approach is to explicitly hardcoderemoved=0in the Qeasy request template. dateincremental cursor was not saved, causing full pulls every time. When the customer volume is large, the interface will time out. We use Qeasy's variable pool to persist the cursor, so it is not lost even on retry.- Confused
all=1andall=0, mixing public sea and private sea data. If the business only wants sales to see private sea customers,allmust be 0; but this will miss data. The safe approach is to first pull all profiles withall=1, then filter by business rules on the order write side. company_idhas no unique index in the Qeasy middle layer, resulting in multiple profiles for the same customer and random hits on order association. This requires the dual safety net of target-sideidCheck=trueplus a database unique constraint.- crontab written as
1 1 1 1 1— that strange expression in the target-side example is clearly not a normal schedule. A pitfall reminder: the source strategy's schedule is the effective schedule; the crontab field on the target side basically does not execute in the 'write null operation' scenario. Do not be misled by example values.
Applicable and Non-applicable Scenarios
Applicable: CRM-side customer master data needs to be persisted incrementally into the middle layer for consumption by multiple downstream consumers such as orders, payments, and shipping, with customer volumes ranging from hundreds of thousands to millions. Not applicable: scenarios that require real-time (second-level) synchronization of customer changes — the */20 rhythm cannot support it. Also not applicable for lightweight scenarios where the CRM and ERP are directly connected to the same database without needing a middle layer.