Kingdee Cloud BD_OPERATOR Operator Query API Field Handbook Tutorial

What This API Solves

The Operator (Salesperson) master data is the bridge connecting CRM and business documents in Kingdee Cloud. This API retrieves BD_OPERATOR records in batches via the executeBillQuery WebAPI, used for CRM-user-to-Kingdee-operator mapping, sales order owner synchronization, customer owner mapping, and organization initialization. Across multiple real integration projects, the biggest blocker on the sales chain is user-master inconsistency between CRM and ERP—missing or mismatched operators break order ownership and performance accounting. This API is the starting point for bridging CRM↔ERP personnel master data.

API Capability Overview

• Authentication: Kingdee Cloud WebAPI uses appId + appSecret + acctId signature authentication; some environments also support user-ticket login.
• Request Method: POST /k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.executeBillQuery.
• Request Structure: Form parameters (FormId, FieldKeys, FilterString, OrderString, TopRowCount, Limit, StartRow) submitted as form-data.
• Response Structure: Returns a JSON array; each element contains the requested fields. Metadata is configured independently in QeasyCloud source-metadata.
• Pagination Mode: Offset-based pagination via StartRow + Limit, looping until the returned row count is less than Limit.
• Incremental Mode: Implemented through FilterString such as FModifyDate>='{{LAST_SYNC_TIME}}' or FCreateDate>{{LAST_SYNC_TIME}}.

Typical Field Mapping

How to Configure on QeasyCloud

In QeasyCloud Data Integration Platform, the Kingdee Cloud Operator query typically follows this encapsulation pattern:

1. Data Source Adapter: Choose the "Kingdee Cloud (Public)" adapter, fill in the endpoint, appId/appSecret, organization code, and other authentication parameters.
2. Form/API Configuration: Set FormId to BD_OPERATOR and select the executeBillQuery operation.
3. Metadata (source-metadata): Configure id as FEntity_FEntryId or a composite key based on FOperatorId; number as FNumber; list FieldKeys in request as needed.
4. Field Mapper: QeasyCloud's field mapper automatically splits Kingdee FName-style fields (suffix _FName = display value, _FNumber = code, Id = object reference) into separate code/name columns, ready for downstream binding.
5. Incremental & Filter: Insert {{LAST_SYNC_TIME|dateTime}} placeholder into FilterString; the platform injects the last sync timestamp automatically when scheduling.
6. Target Configuration: Select "Write No-Op" to indicate a query-only strategy; data flows into the platform for downstream CRM user-mapping strategies to consume.
7. Scheduling: Use crontab such as 25 3 * * * (daily at 03:25) or 0 10 * * 1 (weekly Monday 10:00), tuned to business volume.

Cross-Project Practical Points

1. Pick the right primary key for multi-org: Kingdee operators have multi-org/multi-type entries. A single FOperatorId is not unique across orgs. Use FEntity_FEntryId or the composite {{FOperatorId}}{{FBizOrgId}}{{FName}}{{Fdept}}.
2. Prefer FModifyDate over FCreateDate: FCreateDate only catches creation, missing enable/disable/edit. FModifyDate covers all changes.
3. Stack three filter layers: enable status (FForbiddenStatus='0' or FIsUse='1') + operator type (FOperatorType_ETY='XSY') + business-org whitelist (FBizOrgId.FNumber in (...)). All three together prevent dirty data.
4. Map by code, not by name: Always use FNumber for cross-system mapping. Names are duplicated and renamed; codes are stable.
5. Use platform pagination variables: Use {{PAGINATION_START_ROW}} and {{PAGINATION_PAGE_SIZE}} instead of hard-coding to enable flexible paging and resume.
6. Business-org code is the core of multi-org isolation in Kingdee: Without FBizOrgId.FNumber, you pull group-wide data, triggering permission errors or pollution. Always include it in FilterString.

Pitfalls & Fixes

1. "No permission" error on query — Root cause: FilterString missing FBizOrgId.FNumber; cross-org data is rejected. Fix: add a business-org whitelist.
2. Duplicate users appear in CRM after sync — Root cause: FNumber used as primary key while multiple entries exist under the same code. Fix: switch to FEntity_FEntryId or a composite key, and deduplicate downstream.
3. Incremental data loss — Root cause: FCreateDate used for incremental, but edits do not update creation time. Fix: switch to FModifyDate.
4. Forbidden operators pulled, downstream errors — Root cause: no forbidden-status filter. Fix: add FForbiddenStatus='0'.
5. Field listed in FieldKeys but returns null — Root cause: Kingdee Cloud returns null for unauthorized fields or custom fields not in the permission list. Fix: enable the field in user authorization, or remove it from FieldKeys.

When to Use

Use this API when you need to synchronize salesperson/business-user master data between a CRM (e.g., a CRM integrated with Kingdee Cloud such as Xiaoman OKKICRM) and the ERP, to establish unified order-owner, customer-owner, and performance-accounting semantics. Boundaries: applicable only to Kingdee Cloud Public deployment; this is a query-only strategy and must be paired with a downstream "write to CRM user" strategy; not suitable for sub-second real-time scenarios—recommend batch sync at minute-level or coarser.