Kingdee Cloud Multi-Organization Query Interface (ExecuteBillQuery · ORG_Organizations) Field Manual & Hands-On Tutorial

What Problem This Interface Solves

In Kingdee Cloud–DingTalk integration scenarios, "organization" is the core dimension for data isolation, permission control, and document ownership. This interface queries the Kingdee ORG_Organizations form via ExecuteBillQuery, incrementally syncing multi-organization master data into the integration platform. It is used for organization structure sync, organization selector data sources, multi-organization mapping, and building correspondence with DingTalk departments. It is a read-only query and serves as the "foundation" in the multi-organization integration chain.

Interface Capability Overview

• Interface Name: ExecuteBillQuery (Kingdee Cloud universal document query API)
• FormId: ORG_Organizations (organization table)
• Request Method: POST
• Strategy Type: QUERY (query only, no writes to the target system)
• Authentication: User authentication via Kingdee Cloud API gateway; on the Qeasy Cloud side, just configure application credentials in the platform
• Request Structure: Core parameters include FormId, FieldKeys (set of fields to return), FilterString (filter condition, supports FModifyDate-based increment), OrderString, Limit, StartRow, TopRowCount
• Pagination Mode: Limit + StartRow combination, Limit defaults to 100, StartRow defaults to 0; TopRowCount returns total row count for assessment
• Incremental Mode: FilterString uses FModifyDate>'{{LAST_SYNC_TIME|datetime}}' to roll forward by modification time
• Execution Frequency: Every 3 hours (crontab: 3 * * * *)

Typical Field Mapping

How to Configure on Qeasy Cloud

In the Qeasy Cloud Data Integration Platform, this interface is encapsulated as a "Kingdee Cloud Query" adapter. For the source action, simply select ExecuteBillQuery and set FormId to ORG_Organizations. The platform provides a visual metadata browser that automatically exposes fields like Number / Name / ParentOrg_* / FModifyDate as draggable columns.

• Credentials: Maintain the Kingdee Cloud application ID and secret in Qeasy Cloud's connection management; the platform handles signature and session automatically.
• Field Mapping: Use Qeasy Cloud's field mapper to map Kingdee's Number to organization_code on the target platform, Name to organization_name, ParentOrg_Number to parent_organization_code, FModifyDate to last_modified_at. Audit chain fields (ending with _Id/_Name/_Number) can be expanded with one click in the mapper.
• Incremental Strategy: Qeasy Cloud supports injecting {{LAST_SYNC_TIME|datetime}} directly into FilterString as a variable, automatically rolling forward based on the last successful sync time.
• Scheduling: Set the crontab to 3 * * * * in Qeasy Cloud's scheduler and enable "failure retry + checkpoint resume".

Cross-Project Practical Points

1. Number is the only "anchor": Both id and number are configured as FNumber on the Kingdee side; cross-system matching must use Number, not Name, since names can duplicate.
2. Incremental condition only uses FModifyDate: Don't mix CreateDate or AUDITDATE for increment—only FModifyDate covers all types of changes.
3. ParentOrg is mandatory: When mapping multi-organizations to DingTalk departments, ParentOrg_Number is key for building the tree structure; missing it will break downstream hierarchy.
4. Dual filter on disable and status: It is recommended to append FForbidStatus='A' AND FDocumentStatus='C' to FilterString to sync only approved and non-disabled organizations, avoiding dirty data downstream.
5. Don't set Limit too large: Too large a Limit on the Kingdee side tends to cause timeouts; the safe approach is Limit=200 with Limit+StartRow pagination.
6. Flatten audit fields before mapping: Fields like CreatorId_* are object structures; expand them into _Id/_Name/_Number triplet in Qeasy Cloud's mapper first, otherwise the downstream receives nested objects.

Troubleshooting

1. Incorrect FilterString time format: Kingdee requires yyyy-MM-dd HH:mm:ss; passing an ISO string returns empty results. This is a common pitfall—the safe approach is to use Qeasy Cloud's built-in datetime formatter.
2. Missing data in increment: Filtering only by FModifyDate without considering time zones can cause missed records when server and Kingdee time zones differ. Recommend unifying via FTimeZone before sending the request.
3. ParentOrg_Number is empty: Top-level legal entities have empty ParentOrg; downstream mapping needs null-value protection or the tree structure loses its root.
4. Limit truncation: When Limit is set above 2000, Kingdee forcibly truncates and only returns the first N rows—this can be mistaken for "all data fetched". Always check TopRowCount to determine if there is a next page.
5. Audit chain fields are objects, not strings: Mapping CreatorId_Name directly as a string will fail; in Qeasy Cloud, enable the "object flatten" option.

When to Use

Apply this interface when you need to sync Kingdee Cloud's multi-organization master data downstream (DingTalk, HR, ERP, BI) to build organization selectors, data permissions, or approval flows. Boundary: it only "queries organization master data" and does not write to any target system; if you need to push organizations to DingTalk or write back to Kingdee, combine it with other write-type strategies.