Querying Kingdee Departments: A Practical Tutorial on a Single-Strategy Sync Solution
What This Strategy Solves (Scenario and Value)
In supply chain integration, the department master is the prerequisite for every business document header: purchase orders carry the requesting department, expense reports belong to a cost center, and approval workflows route by department. Many projects underestimate this complexity — assuming one API call will do it — only to find three months later that codes do not match, organizational hierarchies are misaligned, and incremental and full syncs are tangled beyond repair.
The 'Query Kingdee Departments' strategy we landed pulls department master data from the source ERP on a schedule and lands it on the target side, providing a clean, traceable department dictionary for downstream purchase, sales, and approval strategies. It does not write business data; it is a typical read-query-land master data sync.
Data Flow and Field Mapping (Source → Middle Layer → Target)
The core flow is: Source ERP (Kingdee Cloud) → Qeasy Data Integration Platform → Target. The middle layer here acts both as the query scheduler and the field standardizer.
Key field mapping (based on the source executeBillQuery response):
| Business meaning | Source field | Middle-layer field | Notes |
|---|---|---|---|
| Department code | FNumber | dept_code | Primary key; required by downstream |
| Department name | FName | dept_name | For display and matching |
| Department internal ID | FDEPTID | dept_id | System-internal ID; do not expose |
| Using org | FUseOrgId.FNumber | use_org_code | Required in multi-org scenarios |
| Creating org | FCreateOrgId.FNumber | create_org_code | Distinguishes source org |
| Help code | FHelpCode | help_code | Used for fuzzy search |
The source uses Kingdee Cloud's executeBillQuery (POST). On the target side this configuration uses a 'null write' (WebAPI, POST, EXECUTE semantics) — its purpose is to land the dictionary into Qeasy's own repository first, so downstream strategies can consume it.
How to Configure It on Qeasy
We used the Qeasy Data Integration Platform to carry this work. Configuration has three parts:
- Source connector: Pick Kingdee.Cloud, fill in the private-deployment access address and tenant authorization; choose the
executeBillQueryAPI, method POST, and enableautoFillResponseso the returned fields expand automatically, avoiding manual mapping. - Field mapping: Maintain mappings like
FNumber → dept_codecentrally in Qeasy's 'code mapping' module — so when new departments arrive, the rule is changed in one place. This is a common practice among Qeasy customers: keep code rules, field aliases, and cleansing rules in one master mapping table instead of scattering them across strategies. - Target write: We use a 'null operation' first to land the dictionary, which makes Qeasy the master data hub. If you later need to push directly to DingTalk, add a DingTalk connector without touching the source.
Implementation Steps
We split the rollout into three phases:
- Week 1 — Full initialization: Manually trigger one full pull to bring all existing departments over and verify the mapping. Run during off-peak hours, then sample-check codes on both sides.
- Week 2 — Switch to incremental: Move the schedule from manual to automatic; the source uses
*/5 * * * *(every 5 minutes) for incremental pulls. This is the 'incremental + full dual-track' approach: keep the full script but do not run it normally; use it once a week as a reconciliation fallback. - Week 3 onward — Stable run: Monitor alerts and watch the
idCheckfield. In this configurationidCheck=false, meaning the target side does not deduplicate; uniqueness is guaranteed solely by the sourceFNumber. Once the dictionary grows, consider turning idCheck on with upsert.
Pitfalls and Lessons
- Organizational hierarchy flattened: The source
FUseOrgIdreturns the 'using organization', not the 'parent department'. If you build a tree from it directly, approval routing breaks in three months. The safe approach is to maintain a separate org hierarchy mapping table — never use the using org as the parent. - Empty help code causes matching failure:
FHelpCodeis often empty for newly created departments; if the target uses it for fuzzy matching, you will see phantom 'not found' errors. Recommended matching key priority: code → name → help code. - Disabled departments ignored: The source returns disabled departments by default. If you sync without filtering, the target approval flow may route documents to an empty department. We add
FForbidStatus='A'as a filter in the middle layer. - Schedule too aggressive:
*/5 * * * *is fine for a small dictionary, but if the source is org-isolated and every org runs once, database load stacks up. Recommend splitting into per-org strategies with staggered schedules. - Misconception about the null-write target: Seeing
apias 'null write' makes people think nothing was written. In fact Qeasy has already landed the data into its own repository — downstream strategies should read from Qeasy, not go back to the source.
When to Use and When Not to Use
Use when: a single ERP is the sole source of departments, the target needs a consumable department dictionary, and the volume is moderate (< a few thousand departments) on a private deployment. Do not use when: departments move across orgs frequently and require near-real-time (minute-level) sync, multiple source ERPs need to be merged into one dictionary, or the use case is bidirectional — DingTalk maintains departments and writes back to the ERP.