Authoritative Tutorial: Kingdee Cloud Department Query API Field Manual

What This Interface Solves

In Kingdee Cloud–DingTalk integration scenarios, department master data is the cornerstone of organization synchronization. The ExecuteBillQuery interface (FormId: BD_Department) on Kingdee Cloud queries department master data, providing a data source for Kingdee–DingTalk department mapping, employee affiliation mapping, and department selection in approval flows. This interface uses a pure query mode with an empty-write operation at the target end, and it commonly serves as a trusted data source for downstream synchronization strategies (such as pushing departments to DingTalk).

Interface Capability Overview

• Authentication: Based on Kingdee Cloud API gateway authentication, requiring valid app tickets and user tokens. The Qeasy adapter encapsulates the signing logic.
• Request Method: HTTP POST with a JSON body. The core parameter FormId is fixed as BD_Department.
• Response Structure: Standard Kingdee Result response. Business data is wrapped in the Result.Result.Results array, where each row corresponds to one department record.
• Pagination: Implemented via Limit (rows per page), StartRow (starting index), and TopRowCount (total row count). Qeasy defaults to 2000 rows per page and automatically paginates and merges.
• Incremental Mode: Uses audit-date-based incremental filtering. The FilterString looks like FAuditDate>='{{LAST_SYNC_TIME|dateTime}}', combined with multi-organization filtering in ('04','0402','0401').
• Execution Cycle: Scheduled task runs every 2 hours (* */2 * * *), aligning with the frequency of master data changes.

Typical Field Mapping

In Qeasy's field mapper, these fields are automatically registered as draggable source fields. Engineers only need to draw lines between "Kingdee field → DingTalk field" on the canvas.

How to Configure on Qeasy

Qeasy provides deep encapsulation of the Kingdee Cloud ExecuteBillQuery interface. The configuration steps are as follows:

1. Adapter Selection: Choose the "Kingdee Cloud" adapter in the data source configuration and fill in the service URL, app ID, and secret.
2. Form ID: Enter BD_Department. Qeasy will automatically pull the metadata and field list for this form.
3. Primary Key and Code Fields: In the metadata configuration, point id to FDEPTID and number to FName. Qeasy generates the mapping relationship accordingly.
4. Incremental Filtering: Use the {{LAST_SYNC_TIME|dateTime}} placeholder in the FilterString template. Qeasy automatically replaces it with the last successful sync time on each run.
5. Empty-Write Target: Select QUERY as the strategy type and configure the target end as "empty write operation." Query results are only cached in the Qeasy data middle platform for downstream strategy consumption.
6. Scheduled Task: Configure crontab as * */2 * * *. The Qeasy scheduler pulls the latest data on schedule.

Cross-Scenario Practical Essentials

From multiple customer Kingdee–DingTalk integration solutions, we have distilled the following common experiences:

1. Primary Key First: Always use FDEPTID as the cross-system unique identifier, not FName, because department names can be duplicated.
2. Code Alignment: Kingdee's FNumber and DingTalk's department codes must be mapped one-to-one to avoid duplicate creation during downstream sync.
3. Multi-Organization Filtering: Always include FUseOrgId.FNumber in (...) in the FilterString. Otherwise, all departments across the group will be pulled, causing data explosion.
4. Incremental Field Selection: Prefer FAuditDate over FModifyDate because the audit date is more stable; unapproved records should not flow downstream.
5. Pagination Cap: Kingdee's interface typically returns up to 2000 rows per call. Qeasy auto-paginates, but you still need to monitor whether the total row count is abnormal.
6. Leverage Hierarchy Fields: FFullName contains the complete path and can be directly used for hierarchical display in DingTalk organization structure without downstream stitching.

Pitfall Retrospective

1. Filter Condition Failure: A customer once used FUseOrgId.FNumber instead of FUseOrgId in the FilterString, causing the multi-org filter to be ineffective and pulling all departments. The safe approach is to first use Qeasy's "Test Execution" to verify whether the returned row count matches expectations.
2. Incremental Time Drift: {{LAST_SYNC_TIME|dateTime}} is replaced in UTC by default. If the Kingdee server is in UTC+8, an 8-hour deviation occurs. It is recommended to explicitly configure the timezone in Qeasy or use FAuditDate>='{{LAST_SYNC_TIME|dateTime:+08:00}}'.
3. Primary Key Conflict: Kingdee's FDEPTID may be duplicated under multi-org scenarios. You need to combine FUseOrgId to form a composite primary key; otherwise, downstream DingTalk departments will be overwritten.
4. Pagination Data Loss: Kingdee's interface may skip pages due to StartRow offset in concurrent scenarios. Qeasy's paginator handles idempotency, but it is still recommended to disable incremental mode during the first full sync and switch after completion.
5. Empty Organization Name: FUseOrgId_FName is empty in some historical data. Integration mapping needs to handle null fallback; otherwise, DingTalk will display "undefined".

When to Use

This interface is suitable for organization synchronization between Kingdee Cloud and DingTalk (or the Qeasy middle platform), department mapping table maintenance, and employee affiliation mapping scenarios. If the business only needs a one-time full export, it is recommended to use the Kingdee backend export directly; if continuous incremental synchronization is needed, ExecuteBillQuery + Qeasy QUERY mode is the most reliable combination.