[Query-Only] Xiaoman Grouping: A Practical Pre-Sales-Order Data Preparation Strategy

What This Strategy Solves

In retail and distribution scenarios, sales orders never exist in isolation — their line items typically need to reference foundational data such as product groupings, pricing tiers, and customer categories. Once this grouping data is not prepared in advance, the downstream order sync will hit a chain of issues: missing category mappings, dangling codes, and absent price tiers.

The "[Query-Only] Xiaoman grouping" strategy we discuss here is a typical preparatory query strategy: it does not write to any business system itself, but pulls the Xiaoman groupings from the upstream CRM into the Qeasy middle layer on a schedule, serving as the grouping basis for subsequent sales order synchronization. Whether this strategy runs stably directly determines whether the downstream order sync chain can stand up.

Data Flow and Field Mapping

The whole chain is a one-way query → middle-layer landing: Xiaoman OKKICRM → Qeasy data integration platform (middle layer) → no direct write to target system, only referenced by downstream strategies.

Field notes:

• id: unique grouping identifier, used as the join key for subsequent orders.
• name: grouping name, used to render the category on the order side.
• parent_id: parent grouping identifier, describing the tree hierarchy (note: empty string when the upstream does not return it).

How to Configure It in Qeasy

When configuring this strategy, we recommend treating it as a "foundational data preparation" strategy, not a write strategy. Key points:

1. Strategy type: choose "Query-Only", set the effect to QUERY, and configure the target end as a "write no-op" to avoid accidentally writing into the target system.
2. Request config: the GET request has no input parameters and relies on the upstream API's own authentication. Headers and tokens are maintained centrally in the Qeasy connector to avoid scattering them across strategies.
3. Response parsing: map the id, name, and parent_id fields into Qeasy's intermediate table structure. Use id as the primary key, and set the number field as {{id}}-{{name}} for easy human identification during troubleshooting.
4. Code mapping: although this strategy does not directly write downstream, once the grouping code is fixed in the middle layer, all subsequent consumers will look it up. Code mapping is best centrally managed in Qeasy, not redundantly maintained in each downstream strategy.
5. Execution frequency: the crontab is set to 0-59/40 7-22 * * *, meaning every 40 minutes from 7 AM to 10 PM daily. High frequency during business hours and paused during off-hours keeps data fresh while saving upstream quota.

Implementation Steps

We typically roll out this kind of preparatory strategy in three steps:

Step 1: Incremental Starting Point On first go-live, run a full sync first to confirm the middle-layer grouping table can fully reproduce the upstream tree structure. We do not recommend jumping straight into incremental from production; a "full cold start" is more robust.

Step 2: Full Trigger Mount the full task on Qeasy's "Full Trigger" entry and trigger it manually once to write all upstream groupings into the middle layer, which becomes the comparison baseline for subsequent incrementals.

Step 3: Scheduling Frequency Run incrementals every 40 minutes during business hours. After running for a while, verify that "upstream grouping count = middle-layer grouping count" before exposing the data to downstream order strategies. We recommend a dual-track of incremental and full: incrementals run daily, and a full calibration runs on a fixed weekly schedule to guard against the middle layer lagging whenever the upstream API occasionally misses a push.

Pitfalls We Have Seen

Here are some typical issues we have encountered on customer sites:

1. Treating "Query-Only" as "Sync". The most common pitfall is forgetting to change the target end's effect to QUERY, resulting in accidental writes downstream. The safe approach is: always configure the target end as a "write no-op" so the configuration itself precludes side effects.
2. Losing hierarchy when parent_id is empty. The upstream returns an empty string for the parent grouping ID, and naively landing it loses the root-level hierarchy. Normalize empty values to 0 or a designated sentinel, and explicitly establish the "root grouping = 0" convention in the middle layer.
3. Code mapping scattered across downstream strategies. When the same grouping code is maintained separately in sales order, product sync, and price sync, the three places drift apart within three months. The safe approach is centralized code mapping — maintain one source of truth in Qeasy's unified mapping center and let all strategies reference the same copy.
4. One-size-fits-all scheduling across business hours. Running every 40 minutes 24/7 wastes upstream quota when no changes occur at night. The safe approach is to schedule only during business hours, pause at night, and increase frequency during peak hours.
5. No full-sync fallback. After running pure incremental for a long time, if the upstream API hiccups once and misses a push, the middle layer will be missing data for an extended period. Dual-track incremental and full is the standard for this kind of foundational data strategy.

When It Applies and When It Does Not

Applies: when the upstream CRM provides product/customer/pricing grouping APIs and the grouping data needs to serve as the category basis for subsequent order, product, and pricing synchronization, and the timeliness requirement is at "near real-time during business hours" level.

Does not apply: when grouping data needs to be written into downstream business systems, when second-level real-time sync is required, when the grouping structure changes frequently on the source side with no stable primary key, or when the upstream API is itself unreliable with no fallback mechanism.