Practical Tutorial on the Customer Master Query Strategy from XiaoMan OKKICRM to the Qeasy Integration Hub

What This Strategy Solves

In most CRM-to-ERP master data projects, the safe pattern is "pull CRM customer records into a hub first, then let ERP consume them on its own schedule." This tutorial focuses on the very first hop: the Query XiaoMan Customers strategy. Every 5 minutes it pages through the CRM customer list and lands the result in the Qeasy integration hub, forming the raw material pool that downstream strategies will later push into Kingdee Cosmic.

Data Flow and Field Mapping

The direction is one-way: CRM (source) → Qeasy hub (middle layer) → ERP (target). This strategy only covers the first half — source → middle layer.

The source calls /v1/company/list via GET, with effect=QUERY. The key source-side fields are:

The source primary key is company_id, the business number field is name. In Qeasy they map to id and number, with idCheck=false by default. On the target side, the API is labeled "write no-op", type=WebAPI, method=POST. That is the typical "land in the staging area first" pattern — get the data into Qeasy first, and let a separate downstream strategy perform the actual ERP write.

How to Configure It in Qeasy

When configuring this strategy in the Qeasy integration platform, we usually take four steps.

Step 1 — Register the source system. Choose XiaoMan OKKICRM under "Source Platform", enter the application credentials, and keep the platform code exactly as defined in the source metadata. Do not rename it, or downstream scripts will lose alignment.

Step 2 — Define the API. Fill in /v1/company/list, GET, and QUERY. Add each request parameter from the table above, with default values pre-filled so the very first run already returns page 1 successfully.

Step 3 — Set the hub landing point. Configure the target API as "write no-op" with POST method, and put 0 for both id and number. The goal is to land the result reliably into Qeasy's staging table so that downstream strategies can consume it. Writing straight into ERP at this stage is risky: if the downstream validation fails, the whole batch has to be replayed. The "stage first, write later" pattern is the most common posture we see among Qeasy customers.

Step 4 — Disable model auto-building. Set buildModel=false and autoFillResponse=false so the platform does not guess field semantics for you. Source field meaning must be confirmed by a human; this step cannot be skipped.

Implementation Steps

A phased rollout is safer. In real projects we usually do it this way:

• Increment baseline. On go-live day, run once with all=1 to pull the full customer set as a baseline. At the same time, record the maximum company_id per group as the increment cursor for later.
• Full pull trigger. Temporarily raise count to the source-side cap to backfill history in fewer pages, then drop it back to the normal business page size to ease source pressure.
• Schedule. Set the source strategy crontab to */5 8-22 * * *, which means every 5 minutes during working hours. The 8-22 window matters: running at night often collides with the CRM's own backup job, slowing responses or causing timeouts.
• Downstream handoff. Once the data lands in the hub, the downstream "write to Kingdee Cosmic customers" strategy consumes it on its own cadence (for example 23 2 * * *, every night at 02:23), so the CRM side never gets dragged down.

Lessons from the Field

1. Never default all to 1. The source default is 1, but many CRMs hold both public and private customers. Pulling everything by default triggers compliance alarms. In Qeasy we override it to 0 and only pull public customers or specific groups.
2. Pagination without resume-from-cursor is dangerous. In one project the source slowed down inside a 5-minute window and a page was missed, leaving a gap in the hub. The safer move is to add a date increment cursor in the Qeasy request and use the last record's update time, instead of relying on start_index alone.
3. Do not guess field naming. In one engagement, name on the source side means "company name", but it was mapped to "customer number" in Qeasy. That semantic drift only surfaced three months later. Always keep field mapping explicit and centralized in Qeasy: company_id → id, name → number. Do not rely on defaults.
4. Wrong time window. Someone once set */5 * * * * for a 24/7 schedule, and source-side timeouts spiked overnight. Switching to the 8-22 working-hours window immediately improved interface availability.
5. Do not write straight into ERP. A direct POST to Kingdee Cosmic will roll back the whole batch if the ERP rejects a row (for example, duplicate customer code), and the cost of replay is high. Land the data in the Qeasy hub first and redistribute in a second hop — this is the most common stable pattern we see among Qeasy customers.

When to Use and When Not to Use

Use it when: you are doing a first-time CRM-to-ERP master data integration, when CRM data changes frequently but ERP settles daily, or when you need to retain a full pull history for audit.

Do not use it when: you need second-level real-time customer writes, or when the source system has no increment cursor and can only do full refreshes. In those cases, a "full replace" strategy is more suitable than the incremental-with-staging pattern described here.