Authoritative Tutorial on Kingdee Cloud Skylight Customer Group Query Interface
What This Interface Solves
In the master data synchronization scenarios between CRM and ERP systems, the customer group is the core master data used to classify customers hierarchically (by industry, region, scale, etc.). This interface batches customer groups from Kingdee Cloud Skylight through the executeBillQuery WebAPI against the AMB_CustomerGroup form. Typical use cases include: aligning CRM customer classification with ERP customer groups, synchronizing customer archive classifications, and cross-system hierarchical customer management.
Interface Capability Overview
- Authentication: Standard Kingdee WebAPI Cookie/Session authentication. A login call is usually required up front to obtain a session.
- Request structure:
POST executeBillQuerywith a JSON body. Key parameters includeFormId(fixed asAMB_CustomerGroup),FieldKeys,FilterString,Limit,StartRow, andTopRowCount. - Response structure: A two-dimensional array of records; each row corresponds to one customer group, with field order matching
FieldKeys. - Pagination pattern: Use
Limit + StartRowto paginate.Limitis usually injected via the{{PAGINATION_PAGE_SIZE}}variable. 2000 per page is a recommended balance between throughput and stability. - Incremental pattern: Use
FilterStringto filterFModifyDate > last_sync_timefor incremental queries. To avoid missing records, a safer approach is to combineFCreateDateand perform periodic full reconciliation.
Typical Field Mapping
| Field | Type | Meaning | Practical Notes |
|---|---|---|---|
| FID | string | Internal Kingdee primary key, unique identifier of a customer group | Used for internal references and as the anchor for FParentId associations |
| FNumber | string | Business code; metadata maps both id and number to it | Primary cross-system mapping key; recommended to carry this as a code field on the CRM side |
| FName | string | Display name | Used for UI display; watch out for multilingual/encoding differences |
| FParentId | string | Parent group FID; root nodes are typically empty or 0 | Essential for building the tree hierarchy; wrong integration order causes orphan nodes |
How to Configure on Qeasy Cloud
In the Qeasy Cloud data integration platform, this Kingdee query interface is typically wrapped as a Kingdee Cloud Skylight adapter. The source AMB_CustomerGroup data object corresponds to the platform's "Kingdee Customer Group" model. When configuring, you usually do the following: select the "Kingdee Cloud Skylight — Master Data Query" template for the data source, set FormId to AMB_CustomerGroup, and bind pagination parameters to the platform variables {{PAGINATION_PAGE_SIZE}} and {{PAGINATION_START_ROW}}. The field mapper automatically maps FNumber to the downstream group code field and FParentId to the parent group field. The target side is often configured as a "null write operation", turning it into a pure query strategy that other write strategies can reference as master data.
Cross-Scenario Practical Highlights
- In metadata, both id and number point to FNumber: This is a common Kingdee master data convention. Always use FNumber as the unique key during cross-system reconciliation to avoid duplication from mixing it with FID.
- Process tree structures in hierarchical order: In real projects, we typically first build a
FID → Nodemap in memory, then iterate a second pass to attach parent-child relationships. Root nodes are those whoseFParentIdis empty/0/"0". - FModifyDate is the safer incremental field: Incrementing by modification time is safer than creation time, because it covers renaming and moving groups. Pair it with periodic full reconciliation as a fallback.
- Don't be greedy with page size: Pages larger than 5000 tend to time out on large datasets. 2000 is a reliable sweet spot.
- Watch out for FilterString escaping: If group names contain special characters (like
'or&), pre-escape them; otherwise the entire batch query will return 500. - Schedule cron jobs during off-peak hours: Run them after day-end, in the early morning when business is idle, to reduce table locks and rate-limit pressure on the Kingdee side.
Pitfall Retrospective
- Pitfall 1: Root node detection varies. In some environments the root
FParentIdis an empty string, in others it's"0", and sometimes it equals the node's own FID. The safe approach is to check for all three states — empty or equal to 0. - Pitfall 2: Incremental data loss. Incrementing only by
FModifyDatewill miss updates on disabled or un-approved groups whose modification time isn't refreshed, causing the CRM side to retain stale records. Run a full reconciliation weekly. - Pitfall 3: Parent-child loops. Theoretically Kingdee won't produce self-references, but cross-system writes that fail and re-write can easily create
A→B→A. IfFParentIdequals the node's own FID, treat it as a root node. - Pitfall 4: Code length truncation. In some versions, FNumber has a length cap of 80 characters; longer CRM-side codes will be truncated. Validate at the source.
- Pitfall 5: Same-name group confusion. FName allows duplicates. For idempotent writes, do not use the name as the primary key; use FNumber.
When to Use
Best for scenarios where CRM and ERP need customer classification alignment, hierarchical customer operations, or regular master data reconciliation. If you only need a one-time import or only need customer records (not group mappings), consider using the lighter "Customer Query" interface instead.