Authoritative Tutorial on the Kingdee Cloud Assistant Data Query Interface Field Manual

What This Interface Solves

The Kingdee Cloud 'Assistant Data Detail' interface is used to bulk-pull system-internal dictionary-style master data such as countries, provinces, regions, industry classifications, and customer tiers. In CRM-ERP integration scenarios, address, industry, and tier dropdowns on the CRM side typically need to stay aligned with Kingdee. This interface is the canonical entry point for synchronizing such dictionaries from Kingdee to the CRM master data layer, preventing drift caused by dual maintenance.

Interface Capability Overview

• Authentication: Kingdee Cloud WebAPI. The caller must pass acctId, userName, password (or a signed ticket) to obtain a SessionToken, then invoke the query interface with that Token.
• Request Structure: Built on the generic document query interface executeBillQuery. The body assembles query conditions via formId, fieldKeys, filterString, and orderString.
• Response Structure: Returns a JSON array where each record corresponds to one assistant data detail row; the outer envelope contains Result (data) and ResponseStatus (status code, error info).
• Pagination: Controlled by limit and startRow. A single batch of 200–500 records is recommended to avoid timeouts on large volumes.
• Incremental Mode: Kingdee does not natively expose a timestamp-based incremental field. In practice, teams typically use a daily scheduled 'full + status-filtered' sync, or leverage the FModifyDate field for a chain-incremental approach.
• Default Filters: FId.FNumber in ('Country','SSQY','Provincial') together with FDocumentStatus='C' and FForbidStatus='A', ensuring only reviewed and non-disabled geographic data is synchronized.

Typical Field Mapping

How to Configure on Qeasy

On the Qeasy data integration platform, Kingdee Cloud is wrapped as the 'Kingdee Cloud Adapter', and the platform already ships metadata for the BOS_ASSISTANTDATA_DETAIL business object. After selecting this object under 'Data Source → Business Object' on Qeasy, the field mapper auto-lists every field in the table above, eliminating the need to hand-craft fieldKeys. Filter conditions can either inherit the platform default triple — category + reviewed + not disabled — or be extended with FUseOrgId_FNumber under 'Custom Filter' for multi-org trimming. Because the response is an array, Qeasy's 'Array Exploder' component automatically flattens each row into a single record, ready to feed the CRM write node downstream.

Cross-Scenario Practical Points

1. Converge categories before syncing: Confirm with business owners which assistant data categories are actually needed (e.g., only country and province, not industry), then narrow down via FId.FNumber in (...) to avoid polluting the CRM dictionary pool with everything.
2. Keep both status filters: FDocumentStatus='C' and FForbidStatus='A' are the data quality guardrails. On Qeasy, place them under 'Base Filter' rather than 'Business Filter' so subsequent config changes do not overwrite them.
3. FParentId requires a second lookup: Kingdee returns only the parent ID, not the parent name. When building tree dropdowns, the CRM side must either join locally or re-query Kingdee, otherwise the UI renders undefined.
4. Use the code, not the name, as the unique key: Cross-system reconciliation should always anchor on FNumber; use FDataValue purely for rendering. Business users may rename a value, but the code stays stable.
5. Balance page size and timeout: A page size of 500 has been observed to intermittently timeout in high-volume customer environments. A safe value is 200; if Qeasy run logs frequently show Read timed out, dropping limit to 100 usually helps immediately.
6. Use FModifyDate for incremental sync: Kingdee does not officially document an incremental field, but we have verified across multiple projects that FModifyDate is reliable. On Qeasy, add it to the chain-incremental condition.

Pitfall Retrospective

1. Category code case mismatch: In one customer's Kingdee environment, both ssqy and SSQY existed, so the filter only matched half. Before syncing, run SELECT DISTINCT FId_FNumber to confirm the actual codes.
2. Missing disabled filter causes stale dropdowns: Disabled dictionary items remain in the cache, and CRM users select them only to fail at save time. Always include FForbidStatus='A' in the default filter.
3. UseOrg overreach in multi-org: Without a FUseOrgId_FNumber filter, the system pulls dictionaries from other organizations, exposing internal entries on the CRM side. Always trim by the using organization.
4. Tree structure only fetched one level: Only Country was queried, leaving provinces dangling directly under countries and breaking the hierarchy. Make sure both parent and child categories are included in the category list.
5. Underscore field naming breaks CRM writes: Kingdee returns FId_FNumber, but if the CRM write node mistakenly uses FId.FNumber, it fails with 'field does not exist'. Qeasy's field mapper auto-normalizes camel/snake case, but handwritten SQL writes must remain careful.

When to Use

This interface is ideal for scenarios where the CRM needs to pull enum/dictionary master data from Kingdee and stay aligned — especially long-lived, stable data such as geographic regions, industries, and customer tiers. If business owners require real-time updates to Kingdee dictionaries, switch to Kingdee's change notifications or message center instead of polling this interface at high frequency. When the dataset is extremely small (just a few entries), manual maintenance is more appropriate than building an integration pipeline.