Practical Tutorial: Pulling Provincial Records from Kingdee Cloud via the "Query-Only" Auxiliary Data Strategy

What This Strategy Solves

In retail supply chain integration, administrative-region archives such as "province / city / district" are shared master data for orders, warehouses, and customers. In one real project, we discovered that when these archives are managed independently across multiple systems, the numbers diverge within three months, and downstream documents keep getting rejected because the corresponding province code cannot be found.

What this strategy does is straightforward — it only pulls the "Auxiliary Data – Province" records from Kingdee Cloud for other write-type strategies to use as code-mapping and reference, without writing anything back to Kingdee. It is a typical "read-only mirror of master data" pattern.

Data Flow and Field Mapping

The data flow is unidirectional: Kingdee Cloud → Qeasy Data Integration Platform → intermediate storage, referenced by other strategies within the same tenant.

The source number field is FDataValue, meaning the "name" is used as the business key anchor; the id field is FEntryID, used as the internal ID for writeback recognition. The target effect is EXECUTE, but the api is configured as a "no-op write," which is the defining feature of this strategy — data is pulled without being persisted, only retained in the middle layer for downstream reference.

How to Configure on Qeasy

Source side: Kingdee Cloud's executeBillQuery interface, POST method, with the request body carrying the pagination parameters Limit=2000 and StartRow={{PAGINATION_START_ROW}}. Setting autoFillResponse=true lets the platform automatically flatten the response structure, eliminating manual parsing.

Target side: attach a "no-op write" WebAPI node on Qeasy, with idCheck=true, so that even without a write action the integrity of the incoming data can still be validated. This configuration is very common among Qeasy customers — using a no-op node to carry metadata, making it convenient for other strategies to depend on and look up mappings.

Centralized management of code mapping is the common pattern Qeasy uses to support such "query-type master data": all province/city/district mappings are consolidated into a single mapping table, so when a new province is added it is maintained only once on the source side and all downstream entries follow.

Implementation Steps

Step 1: Initialize the full pull. Manually trigger a full query with StartRow=0 and confirm that FEntryID, FNumber, and FDataValue all return stably. For the first run, it is recommended to print the first 10 records for manual verification, to avoid mistaking an empty response for a normal one.

Step 2: Pagination and throttling. Set Limit to 2000 (the common single-query ceiling on Kingdee's side), and use Qeasy's loop controller to paginate with StartRow += 2000 until the returned row count is less than Limit, indicating completion.

Step 3: Configure the schedule. The source-side crontab is 0 0 * * *, meaning a full pull runs once a day at midnight. Administrative-region archives change very infrequently, so a daily full pull is more than sufficient; if changes become more frequent in the future, switch to "increment by last-modified time."

Step 4: Configure dependencies and expose references. This strategy has no downstream writes, but it must be marked as "depended-upon" in Qeasy's strategy dependency graph so that all write-type strategies referencing province codes wait for it to complete the daily snapshot before starting themselves.

Step 5: Monitoring and alerting. Set a threshold alert on the actual returned row count of Limit — for example, if the returned row count is zero for an extended period, investigate immediately; in most cases it is because the FDataValue field permission is missing or the auxiliary-data class is disabled.

Pitfall Retrospective

1. Misinterpreting "FDataValue" as a numeric field. It is actually a string storing the Chinese name. A typical mistake is configuring it as a numeric type, causing all Chinese characters to be lost. The safe approach is to strictly declare it as string according to the source metadata.type.

2. Hard-coding pagination parameters. Writing StartRow as a fixed 0 causes the loop pagination to fail, and only the first 2000 records are pulled. The correct approach is to use the {{PAGINATION_START_ROW}} placeholder, which the platform increments automatically within the loop.

3. Actually performing a "write" on the target side. Misconfiguring "no-op write" as a real downstream write interface triggers a reverse write on the Kingdee side. Always confirm that effect=EXECUTE but the api is a no-op node.

4. Crontab time collisions. The source side is fixed at 0 0 * * *. If other strategies in the same tenant are also scheduled at midnight, the Qeasy scheduler will experience queueing delays. The safe approach is to stagger them, for example to 0 5 * * *.

5. Missing dependency configuration. A downstream write-type strategy runs directly, and when it references the province code it cannot obtain the latest snapshot, causing write failure but with the error pointing to the downstream strategy, leading to a long detour during troubleshooting.

Applicable and Non-Applicable Scenarios

Applicable: Auxiliary data with low change frequency such as administrative regions, currencies, units of measure, and payment terms; "basic reference data" scenarios that need to provide code mapping for other write-type strategies in the same tenant; pure-mirror scenarios where reverse write pressure on the source system is not desired.

Not applicable: Write scenarios where data must actually be persisted to Kingdee and consumed directly by Kingdee business modules; archives with high change frequency requiring minute-level increments; deeper-level subdivision data below the province with complex parent-child relationships (a dedicated subdivision master-data strategy is recommended in such cases).