Kingdee Cloud Employee Query API (executeBillQuery / BD_Empinfo) Field Mapping Handbook: An Authoritative Tutorial for MES & WDT Integration

What Problem Does This Interface Solve

In ERP-to-MES and ERP-to-WMS integrations, "where does employee master data come from" is typically the first question. Kingdee Cloud (金蝶云星空) acts as the source of truth for HR master data, and its employee basic info (BD_Empinfo) must be subscribed by multiple downstream systems: MES systems use employee codes for work-order dispatching and reporting, while WDT (旺店通) uses salesperson codes for purchase/sales document mapping. executeBillQuery is the unified query entry exposed by Kingdee for these consumers, reliably fetching core fields like primary key, code, name, department, and organization.

Interface Capability Overview

• Authentication: Standard Kingdee Cloud API auth (AppId + AppSecret + Account ID + User) via a private gateway.
• Request: HTTP POST with a JSON body; key parameters wrapped in otherRequest.
• FormId: Fixed as BD_Empinfo (employee basic info, single-table structure, employee-level granularity).
• Pagination: Limit + StartRow pagination; TopRowCount=0 returns the total row count. In the Qeasy metadata adapter, placeholders {{PAGINATION_PAGE_SIZE}} and {{PAGINATION_START_ROW}} automatically drive the loop.
• Incremental Sync: Based on audit date FAuditDate>='{{LAST_SYNC_TIME|datetime}}'; the Qeasy field mapper auto-injects the last sync timestamp. Filtering by code, name, mobile, or department is also supported.
• Response: An array of employee records. In metadata, id points to FID (primary key) and number points to FName (name). In real projects, prefer FNumber as the cross-system business key over FName.

Typical Field Mapping

How to Configure on Qeasy

On the Qeasy data integration platform, the Kingdee employee query is typically composed as a "Kingdee Cloud adapter + Write-null" upstream node.

1. Adapter: Pick the "Kingdee Cloud executeBillQuery adapter" with FormId BD_Empinfo. Pagination, FilterString injection, and result parsing are pre-encapsulated.
2. Field Mapper: In the Qeasy visual canvas, map FID → target primary key, FNumber → employee_code, FName → employee_name. Use the "Expand Related Field" node to extract FPostDept.FNumber.
3. Incremental Variable: The built-in LAST_SYNC_TIME context is available. Just reference {{LAST_SYNC_TIME|datetime}} in FilterString for audit-date-based incremental sync.
4. Schedules: Common cron expressions are * 7-22 * * * (MES scenario, hourly during working hours) and */10 7-23 * * * (WDT scenario, high-frequency short cycle). The Qeasy scheduler supports both natively.
5. Target Node: Set Target to "Write-null" — this is a pure query strategy. The real write happens in downstream MES / WDT strategies consuming the output.

Cross-Scenario Practical Points

• FNumber is the real business key: Across nearly all customer projects, using FName as the join key leads to duplicates or broken links after personnel transfers. Standardizing on FNumber dramatically improves stability.
• Expand .FNumber on department fields: FPostDept is a related object; the default response is an object reference, not a code string. Always extract FPostDept.FNumber explicitly in FilterString or the field mapper.
• Use FCreateOrgId for multi-org isolation: In private deployments with multiple accounts/orgs, add FORGID.FNumber='xxx' to FilterString or map FCreateOrgId to prevent cross-org data leakage.
• Keep pagination controllable: Do not exceed Limit=2000 per page; Kingdee side tends to time out beyond that. The Qeasy paginator auto-computes total pages from TopRowCount — just confirm PageSize.
• Prefer audit date over modify date: Use FAuditDate as the incremental field — it represents business-confirmed timing and is more stable than FModifyDate, avoiding draft-state data pollution.
• Strong coupling with downstream strategies: This interface is usually upstream only. Its real value lies in chaining with "Kingdee dept → MES dept", "Kingdee employee → MES personnel", and "Kingdee employee → WDT salesperson" strategies. Always confirm dependency order (sequence A/B) at deployment.

Pitfall Playbook

1. Using name as number caused duplicate primary keys: One retail customer set FName as metadata.number, leading MES deduplication to fail on two employees sharing a name. Keep metadata.number as FName per Kingdee convention, but use FNumber separately as the cross-system business key.
2. Forgot to expand .FNumber on department: FilterString FPostDept='Production' returns nothing because the field stores an object reference. Use FPostDept.FNumber='SC001' instead.
3. Incremental timestamp timezone mismatch: Kingdee audit date is UTC+8, but Qeasy's default LAST_SYNC_TIME is UTC, causing the last few hours of the previous day to be missed. Append |datetime with explicit timezone.
4. FCreateOrgId without fname: The default returns an object reference, leading downstream to print [object Object]. Configure FCreateOrgId.fname to get the string.
5. Schedule window missed night-shift data: With * 7-22 * * *, any personnel audited at night are skipped. Switch to */10 * * * * for full coverage or run a manual sync at end of night shift.

When to Use

Use this interface when Kingdee Cloud is the authoritative source of employee master data and you need stable sync of employee code / department / org to MES, WDT, or similar downstream systems in a private deployment. Avoid it when you need to write back to Kingdee, require real-time push (this is polling-based and query-only), or run on non-Cloud versions like EAS or K/3.