Sales Order Integration Practice: A Detailed Guide to Syncing Product Group Lists from OKKICRM

What This Strategy Solves

In a sales order integration chain, product groups serve as the "catalog root" for all downstream documents. If group data is not pushed into the middleware layer first, subsequent material mapping, customer pricing, and order line items will fail because they cannot find their parent reference. This tutorial breaks down one specific strategy—Query OKKICRM Product Group List. Its task is straightforward: pull product groups from OKKICRM into the Qeasy data integration platform as a prerequisite for sales order master data. Although it looks like a simple GET request, it determines whether the entire order flow can run smoothly.

Data Flow and Field Mapping

The data flow is unidirectional: source system (OKKICRM) → middleware layer (Qeasy) → downstream consumers. The source side calls GET /v1/product/groups, while the target side is a "write empty operation" placeholder. The actual write is triggered by downstream strategies that depend on this one.

Key field mapping:

Source Field	Label	Type	Target Handling	Notes
id	Product Group ID	int	Pass through as primary key	Group primary key, used as join key downstream
name	Product Group Name	string	Pass through as business number	Group name, used for human identification
client_id	Client/Tenant ID	string	Write into middleware tenant context	Identifies the owning client or tenant

The request side supports reverse lookup by id or name, but this strategy uses full extraction with empty filters. In Qeasy customer patterns, this falls into the full-trigger category.

How to Configure on Qeasy

When configuring this strategy on Qeasy, there are several key points:

Source Connector: Select OKKICRM with WebAPI type and fill in the basic access information. The request method is fixed as GET, and the response is parsed as JSON. Since autoFillResponse is true, the platform automatically maps response fields to the target model, eliminating the need for manual schema creation.
Target Connector: Select RESTful type with the API name "write empty operation". Set idCheck to true so that idempotency verification can be performed based on id when the actual write happens downstream.
Encoding Mapping: The product group ID on the source side is int. It is recommended to convert it to string when landing in the middleware layer to avoid join failures caused by type mismatch downstream. This is a common practice we see among Qeasy customers—centralized encoding mapping management.
Response Mapping: Since the source response structure is simple, just pass through all fields directly. No complex cleansing is needed.

Implementation Steps

In real customer projects, we usually roll out this strategy in three phases:

Phase 1: Incremental Starting Point Although this strategy is a full query, we recommend validating data accuracy on a small scope first (for example, filtering by a certain name prefix) before opening up to the full pull. The incremental starting point serves as a "safety valve" for operations.

Phase 2: Full Trigger Open up the filter conditions and run a complete pull. The crontab in the source configuration is 54 3 * * *, meaning it executes at 3:54 AM every day. The Qeasy platform lands the results into the target table in the middleware layer as "seed data" for downstream material and product synchronization.

Phase 3: Scheduling Frequency Product groups are low-frequency change data, so once a day is sufficient. If the customer reports that "orders fail after group adjustment", we suggest increasing the frequency to every 12 hours, but it is usually unnecessary. Note that the source crontab field and the Qeasy scheduler must be kept consistent; otherwise, misalignment between the two can cause duplicates or missed data.

Lessons from the Field

This strategy looks simple, but we have encountered several typical pitfalls in customer projects:

Type mismatch causing broken joins: The source id is int. If the target also receives it as int, downstream joins using string will fail. The safe approach is to convert to string uniformly at the mapping layer.
Ignoring client_id for multi-tenant isolation: Some customers have multiple tenants under the same OKKICRM instance. If client_id is not filtered, "cross-tenant" data leakage will occur. Always pass client_id explicitly into the middleware layer.
Crontab misalignment: If the source is set to 3:54 and the platform to 4:00, any group changes during those 6 minutes will be missed between two pulls. The source crontab and platform crontab must be aligned, or let the platform be the single scheduling source.
No row count validation after the first full run: The source returns 200 rows but the platform writes 198. The typical cause is that two rows were dropped during auto-mapping. The safe approach is to perform a row count reconciliation after the full run and alert when the difference exceeds a threshold.
Reversed dependency order: Product groups must be synchronized before users, customers, and materials; otherwise, downstream data creation will fail because the group ID cannot be found. In Qeasy strategy orchestration, keep depends_on empty for this strategy and let other strategies explicitly depend on it.

Applicable and Non-applicable Scenarios

Applicable: Scenarios where basic data such as product groups change infrequently and serve as prerequisites for sales orders; integration chains where a "group dictionary" needs to be shared across multiple downstream systems.

Non-applicable: Scenarios where group changes need near-real-time (<1 hour) synchronization to front-end business systems; scenarios where the source does not support full queries and must rely on cursor-based pagination for large data volumes—in those cases, the strategy needs to be rewritten as a paginated pull.