Querying Customer Master Data from Xiaoman CRM to the Middle Layer: A Single-Strategy Tutorial
What This Strategy Solves
Syncing customer master data from CRM to ERP looks like simple "moving," but the real challenge in the field is "moving in a controllable way." This single strategy does only one thing: scheduled retrieval of the customer list from Xiaoman OKKI CRM into the Qeasy integration platform's middle layer, serving as the prerequisite action for downstream writes to the target system (Kingdee Cosmic). Splitting "query" and "write" into two strategies—landing data in the middle layer first, then transforming it downstream—is the most reliable transitional approach at customer sites.
Data Flow and Field Mapping
The data flow runs in three segments: source system (Xiaoman OKKI CRM, platform code Moor7) → middle layer (Qeasy integration platform, platform code datahub) → target system (Kingdee Cosmic). This strategy covers the first two segments.
The source calls GET /v1/company/list with pagination parameters start_index (default 1) and count (default 20), and filter parameters removed (0/1), all (1 = all customers / 0 = private sea only), group_id, and date. After the response, name serves as the business number and company_id serves as the business primary key when entering the middle layer.
The middle layer uses a "write null operation" to receive data (POST, idCheck=true), with the purpose of letting data land in the platform's traceable storage first, facilitating reconciliation and replay, and providing a data snapshot for downstream strategies.
| Dimension | Source (Xiaoman) | Middle Layer (Qeasy) | Notes |
|---|---|---|---|
| Primary key | company_id | Pass-through | For idempotent dedup |
| Number | name | Pass-through | Business number |
| Page index | start_index | Internal cursor | Incremental starting point |
| Page size | count | Internal cursor | Recommended 50–200 |
| Deletion state | removed | Same-row pass-through | Enable with caution |
| Scope | all / group_id | Pass-through | Default: all customers |
How to Configure on Qeasy
In the Qeasy integration platform, this strategy is of type QUERY_ONLY, with Xiaoman as the source platform and datahub itself as the target platform (i.e., the middle layer). Key points:
- API and method: Source-side
GET /v1/company/list; target-side uses the platform's built-in "write null operation"POST. - Cursor and idempotency: Set
company_idas the primary key andidCheck=trueto avoid duplicate writes; usenameas the business number field. - Default request parameters:
start_index=1,count=20,removed=0,all=1, with optionalgroup_idanddatefor incremental filtering as needed. - Scheduling: Source crontab uses
3 2 * * *and the middle layer lands at23 2 * * *, staggered by 20 minutes for easier log tracing. - Response model: The source response does not require automatic model building (
buildModel=false,autoFillResponse=false); the platform parses the schema directly.
A common lightweight pattern at customer sites is to centrally maintain code mapping in the platform mapping table, with downstream strategies (writing to ERP) only referencing—not rewriting—this way adding fields or changing groups later doesn't require touching dozens of scripts.
Implementation Steps
- Environment and credentials: Register the source platform
Moor7access credentials and the target platformdatahubinternal routing on Qeasy; in private deployment environments, use the internal network domain directly. - Incremental starting point: First run a full pull with
start_index=1&count=20&all=1&removed=0to confirm the middle layer landing count matches the source. - Incremental and full dual-track: Daily scheduling uses "incremental by
date", with a fixed-time full reconciliation trigger once a week to avoid missing records—this is the most common and worry-free dual-track approach among Qeasy customers. - Scheduling frequency: The source triggers a pull at 02:03 every morning, with the middle layer landing at 02:23; for tenants with customer volumes under 100,000, the default frequency is sufficient.
- Subsequent linkage: Once this strategy (sequence B) runs stably, the downstream "Xiaoman Customer => Cosmic Customer - Add" (sequence A) can consume the middle layer data and write it according to the target system's customer master data specification.
Lessons Learned from the Field
- Pitfall 1: Mid-pagination errors causing missed pages. The source API truncates when
countexceeds a threshold and does not return totals; the reliable approach is to keepcountat a moderate value and enable "resume from breakpoint" in the platform. - Typical error 2:
removedenabled by default. On-site staff often mistakenly set "whether to query deleted" to 1, causing a flood of deleted records in the middle layer that downstream cannot interpret. The default must be 0. - Typical error 3:
all=0causing private sea data loss. Sales private sea customers in Xiaoman won't be pulled, and the business side only notices later that "30% are missing." Confirmall=1according to the business specification. - Typical error 4: Code mapping scattered everywhere. The same
group_idgets mapped to different groups across strategies, and the two sides don't match in the end. Centralized management in the platform mapping table is mandatory. - Typical error 5: Source/middle layer scheduling too close together. If the middle layer triggers before the source pull finishes, it reads a stale snapshot; stagger them by at least 15–20 minutes.
Applicable and Non-Applicable Scenarios
Applicable: Scenarios where CRM serves as the customer master data source and data needs to land in the middle layer first before being distributed to multiple ERPs / finance systems / data warehouses; customer volumes under 100,000 with "visible next day" real-time requirements. Not applicable: Scenarios requiring minute-level real-time sync with direct real-time CRM API calls rather than landing in storage; and scenarios with customer volumes at the million-plus level that need dedicated CDC and streaming channels—these exceed the design scope of this strategy.