Authoritative Tutorial on the Customer Group Query Interface of Xiaoman OKKICRM
What This Interface Solves
In the master data synchronization chain between CRM and ERP, customer groups are a frequently referenced "dimension field"—downstream document filtering, customer master data writing, and statistical aggregation all depend on it. Xiaoman OKKICRM exposes customer groups as a "field selector". The goal is to pull down this dropdown option list stably and map it to the customer group (master data) in Kingdee Cloud Cosmos, forming a mapping table for subsequent customer master data synchronization.
Interface Capability Overview
- Path:
/v1/company/fields/selector - Method: GET
- Authentication: Bearer Token (carried in the request header, issued by the gateway in private deployment scenarios)
- Core request parameter:
field=group_id(fixed value, indicating the option list of the group_id field of the company entity) - Response structure: a typical id-name option array; each record contains
id(primary key) andname; no explicit pagination field, returned all at once by the source system. - Sync strategy: QUERY_ONLY; the Target is configured as a "write null operation" and does not write to the target system, serving only as a data source for downstream mapping.
- Scheduling: usually triggered by an early-morning scheduled task (e.g., crontab
3 2 * * *), staggered from downstream customer master data sync.
Typical Field Mapping
| Field | Type | Meaning | Practical Notes |
|---|---|---|---|
| id | string | Unique identifier of the customer group in the source system; marked as the primary key in metadata | Used to filter customers by group (group_id parameter) and to write the target group code during customer sync; must be unique across systems |
| name | string | Display name of the customer group; marked as the number field in metadata | Used for cross-system name/code mapping; the same name with different ids may exist—validate both id and name |
| field (request param) | string | Fixed group_id, as the field selector input | Different business objects use different selector params (e.g., industry_id, source_id); verify when reusing templates |
How to Configure in Qeasy
In the Qeasy Data Integration Platform, such "field selector" interfaces are typically encapsulated by a query strategy adapter: configure the HTTP request template on the Source side, fill in field=group_id, and the response parser automatically expands the id-name array structure. The Target is configured as a "null operation", and the platform only caches the result into the mapper context without writing to the target database.
For field mapping, the Qeasy field mapper automatically recognizes id (primary key) and name (code) according to the metadata, and generates mapping nodes with Kingdee Cloud Cosmos's FGroup_FNumber / FGroup_FName. Engineers only need to confirm the direction and cleaning rules in the mapping canvas. For cross-system mapping scenarios, the platform's built-in "fuzzy match by name + exact match by ID" dual strategy can be enabled to avoid mismatches caused by relying solely on names.
Cross-Project Practical Points
- Always treat the field selector as a master data source: do not hardcode group_id directly in business interfaces. Run the selector first to cache the full option list, then provide it to downstream interfaces for reference.
- The fixed
fieldparameter is a convention, but watch for multiple versions: in different Xiaoman versions, the group_id field name may change occasionally; the adapter must be configurable rather than hardcoded. - Both id and name must be stored in the mapping table: mapping only by name easily causes duplicate-name groups, and subsequent customer sync writes may land in the wrong account set.
- Decouple scheduling time from downstream: run the selector in the early morning and customer master data sync in the morning, leaving a mapping table refresh window to avoid reading stale groups.
- Do not treat an empty response as success: if the source system returns an empty array, it is most likely token expiration or tenant isolation misconfiguration—alarm explicitly in monitoring.
- Domain isolation in private deployment: different environments have different gateway domains; the baseUrl in the adapter must be injected by environment variables, not packaged into the image.
Pitfall Review
- Pitfall 1: Mistaking the selector for a customer list interface. This interface only returns field options, not customer details. Some misuse it to pull customers, only to get a dozen group records.
- Pitfall 2: Ignoring the metadata's number annotation. The
namefield is of number type in the source system. Treating it as an ordinary string in the mapper may leave leading/trailing spaces and full-width characters uncleaned. - Pitfall 3: Storing only id in the mapping table. During subsequent O&M troubleshooting, you can only see a string of IDs without knowing their meaning, making problem location extremely slow. The safe approach is to store id, name, source system identifier, and update time together.
- Pitfall 4: Wrong timezone in scheduling. If the private server's timezone differs from UTC, the crontab trigger time drifts, causing downstream to read "yesterday's groups".
- Pitfall 5: No auto token renewal. The selector interface is sensitive to tokens. After expiration, it does not return an explicit error code but an empty array, easily misjudged as "no groups".
When to Use
This interface is suitable for scenarios where the CRM-side customer group dimension needs to be synced to the ERP-side master data—especially when a group mapping table must be built before writing customer master data, or when downstream business documents need to be filtered and returned by CRM groups. It is not suitable for pulling customer details, orders, or custom business data, nor is it recommended for high-frequency real-time chains because it returns all options at once with a large payload.