Kingdee Cloud Auxiliary Data – District Query Interface Field Handbook: executeBillQuery Practical Tutorial

What This Interface Solves

In the supply chain integration scenarios between WDT and Kingdee Cloud, district-level administrative regions are unavoidable dictionary-type master data for addresses, receiving regions, and customer/supplier profiles. Different systems have their own encodings and names for "districts". If a unified master data mapping is not established at the beginning, follow-up customers, orders, and receiving documents will easily have address misalignment and unmatched regions. This interface uses Kingdee's WebAPI executeBillQuery to batch-pull the "district" details from Kingdee under auxiliary data category D01, providing downstream systems with code cross-reference and name display. It is a typical "query-only, no write" master data synchronization prerequisite action.

Interface Capability Overview

• System: Kingdee Cloud (BOS platform).
• Call: HTTPS POST through Kingdee WebAPI's unified executeBillQuery entry.
• Request Parameters: Core trio — FormId=BOS_ASSISTANTDATA_DETAIL (auxiliary data detail table), FilterString=FId.FNumber='D01' (only query the "district" category), FieldKeys (returned field set).
• Pagination: Kingdee's standard StartRow + Limit (default 2000/page, some environments support 5000). Loop pagination is required for large datasets until the return is empty.
• Incremental Mode: The native executeBillQuery does not provide time-based incremental fields. FEntryID or last-modified-time is usually used as an external watermark, with a daily 0:00 full re-pull and difference comparison on the consumer side.
• Response Structure: Each record is a dictionary item detail, containing FEntryID (primary key), FNumber (code), FDataValue (name), and other core fields, with the outer layer carried by the Result list.

Typical Field Mapping

On the Qeasy Cloud Data Integration Platform, this interface is usually wrapped as a "Kingdee Auxiliary Data Query" adapter. The field mapper automatically identifies FEntryID as the primary key and FNumber as the business code, without manual re-declaration in scripts.

How to Configure on Qeasy Cloud

1. Data Source Adapter: Choose the "Kingdee Cloud" connector, fill in authentication information (data center ID, app ID, secret, user). The platform has a built-in executeBillQuery call template.
2. Strategy Type: Select "QUERY only", configure Target as "Write Empty Operation", which is the standard usage of this interface.
3. Filter Condition: In the visual configuration panel, write the FilterString as FId.FNumber='D01'. The platform will transparently pass it to the Kingdee API without extra script preprocessing.
4. Field Mapper: Map the returned FEntryID, FNumber, FDataValue to the target's district_id, district_code, district_name fields. The Qeasy Cloud field mapper automatically handles type conversion.
5. Scheduled Task: Per the strategy's default 0 0 * * *, fully pull once a day at 0:00, placed in the prerequisite position of WDT address-type sync strategies to ensure master data is ready when downstream consumes.

Cross-Scenario Practical Essentials

1. D01 Is Not Universal: In different customer environments, the auxiliary data category code for "district" is not always D01. Be sure to confirm in Kingdee first with queries like SELECT * FROM T_BAS_ASSISTANTDATA_L WHERE FName LIKE '%区%' before deciding the FilterString.
2. Do Not Mix FNumber and FDataValue: In multiple customer projects, we have seen engineers mistakenly use FDataValue (name) as the business code to build master data mappings, causing collisions between districts with the same name. The code is always FNumber; the name is only for display.
3. Do Not Guess the Parent-Child Hierarchy: Kingdee auxiliary data supports province/city/district hierarchy. When pulling across systems, only take the leaf-level "district". Pulling provinces and cities into the master data pool too early will leave address field filling at a loss.
4. Do Not Max Out Pagination: 2000 records/page is the Kingdee recommended value. Although some environments can go to 5000, when reusing strategy templates across customers, the safe approach is to uniformly use 2000 to avoid one environment hitting the limit and throwing an error.
5. Explicitly Declare Dependency Order: In supply chain integration projects, "district" master data should be explicitly declared as depends_on prerequisites for "customer address", "supplier address", "receiving address" and other strategies. Otherwise, downstream will get empty mappings during initial sync.
6. Cost of Full Re-pull: The D01 category usually has thousands to tens of thousands of entries, and the full re-pull pressure on the Kingdee API is manageable. However, if extended to the "province" or "city" level (a single category over 100k), it is recommended to switch to modified-time-based incremental pull, otherwise rate limiting on Kingdee can be triggered.

Pitfall Retrospective

• Pitfall 1: Writing FId.FNumber in Chinese: Mistakenly writing D01 as "区" in the FilterString causes Kingdee to return empty, but the platform does not error, leading downstream to always receive empty master data. Response: Filter conditions must use category codes, not category names.
• Pitfall 2: Using FDataValue as Primary Key: Using name strings like "Chaoyang District" as primary keys causes all foreign key references to break when Kingdee-side names change. Response: Unified use of FEntryID as primary key and FNumber as business code.
• Pitfall 3: Ignoring Parent-Child Hierarchy: Pulling provinces, cities, and districts all at once creates confusion about which level to fill in WDT address fields, resulting in dirty data like "province written into district field". Response: Strictly limit FilterString to D01, only take the leaf level.
• Pitfall 4: Missing the Last Page in Pagination: The loop only checks "data is non-empty" without checking "row count < Limit", causing the last page to be pulled repeatedly or even enter an infinite loop. Response: Loop condition should also validate len(rows) < Limit for graceful exit.
• Pitfall 5: Schedule Time Overlapping with Downstream: Daily full pull at 0:00, but downstream customer sync strategies also run around 0:00, creating "master data not yet pulled, downstream already consuming" null pointer scenarios. Response: Move the master data strategy to 23:30, or explicitly configure depends_on for downstream strategies.

When to Use

Suitable for supply chain integration scenarios where dictionary-type master data needs to be batch-fetched by category from Kingdee Cloud and consumed by WDT or other external systems, especially where address-type fields have strong dependencies on administrative region codes. If you need "province" or "city" instead of "district", or custom auxiliary data categories, simply replace the FilterString to reuse the same interface template. However, for very large-scale (100k+) categories, consider switching to an incremental interface.