Qeasy Cloud
Get Started

Authoritative Tutorial on Kingdee Cloud Skylight Customer Group Query Interface

· 何金辉· Engineering Best Practices· 28 views· 4 min read
小满OKKICRMKingdee Cloud客户分组executeBillQuery基础资料同步轻易云字段映射手册

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 executeBillQuery with a JSON body. Key parameters include FormId (fixed as AMB_CustomerGroup), FieldKeys, FilterString, Limit, StartRow, and TopRowCount.
  • Response structure: A two-dimensional array of records; each row corresponds to one customer group, with field order matching FieldKeys.
  • Pagination pattern: Use Limit + StartRow to paginate. Limit is usually injected via the {{PAGINATION_PAGE_SIZE}} variable. 2000 per page is a recommended balance between throughput and stability.
  • Incremental pattern: Use FilterString to filter FModifyDate > last_sync_time for incremental queries. To avoid missing records, a safer approach is to combine FCreateDate and perform periodic full reconciliation.

Typical Field Mapping

FieldTypeMeaningPractical Notes
FIDstringInternal Kingdee primary key, unique identifier of a customer groupUsed for internal references and as the anchor for FParentId associations
FNumberstringBusiness code; metadata maps both id and number to itPrimary cross-system mapping key; recommended to carry this as a code field on the CRM side
FNamestringDisplay nameUsed for UI display; watch out for multilingual/encoding differences
FParentIdstringParent group FID; root nodes are typically empty or 0Essential 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

  1. 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.
  2. Process tree structures in hierarchical order: In real projects, we typically first build a FID → Node map in memory, then iterate a second pass to attach parent-child relationships. Root nodes are those whose FParentId is empty/0/"0".
  3. 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.
  4. Don't be greedy with page size: Pages larger than 5000 tend to time out on large datasets. 2000 is a reliable sweet spot.
  5. Watch out for FilterString escaping: If group names contain special characters (like ' or &), pre-escape them; otherwise the entire batch query will return 500.
  6. 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 FParentId is 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 FModifyDate will 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. If FParentId equals 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.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/engineering/hb-p2-090-ok-copy-2c8f

Comments