Qeasy Cloud
Get Started

Querying Customer Master Data from Xiaoman CRM to the Middle Layer: A Single-Strategy Tutorial

· 何海波· Integration Solutions· 13 views· 4 min read
小满OKKICRM金蝶云·星空旗舰版客户主数据金蝶云·星空基础资料同步轻易云集成增量全量双轨

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.

DimensionSource (Xiaoman)Middle Layer (Qeasy)Notes
Primary keycompany_idPass-throughFor idempotent dedup
NumbernamePass-throughBusiness number
Page indexstart_indexInternal cursorIncremental starting point
Page sizecountInternal cursorRecommended 50–200
Deletion stateremovedSame-row pass-throughEnable with caution
Scopeall / group_idPass-throughDefault: 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:

  1. API and method: Source-side GET /v1/company/list; target-side uses the platform's built-in "write null operation" POST.
  2. Cursor and idempotency: Set company_id as the primary key and idCheck=true to avoid duplicate writes; use name as the business number field.
  3. Default request parameters: start_index=1, count=20, removed=0, all=1, with optional group_id and date for incremental filtering as needed.
  4. Scheduling: Source crontab uses 3 2 * * * and the middle layer lands at 23 2 * * *, staggered by 20 minutes for easier log tracing.
  5. 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

  1. Environment and credentials: Register the source platform Moor7 access credentials and the target platform datahub internal routing on Qeasy; in private deployment environments, use the internal network domain directly.
  2. Incremental starting point: First run a full pull with start_index=1&count=20&all=1&removed=0 to confirm the middle layer landing count matches the source.
  3. 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.
  4. 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.
  5. 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 count exceeds a threshold and does not return totals; the reliable approach is to keep count at a moderate value and enable "resume from breakpoint" in the platform.
  • Typical error 2: removed enabled 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=0 causing 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." Confirm all=1 according to the business specification.
  • Typical error 4: Code mapping scattered everywhere. The same group_id gets 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.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-okkicrm-p110c26-0637-ok-08af43f4

Comments