Querying Kingdee Departments: A Practical Guide to Syncing Master Data from ERP to OA

What This Strategy Solves

In one real project, we ran into this situation: a manufacturing enterprise's approval workflow lived in an OA system, but the authoritative data for organizational structure, personnel assignment, and cost centers always resided in the Kingdee Cloud ERP. The OA department dictionary had been manually imported years earlier and was already out of sync—HR changed department names in OA, but Kingdee didn't know about it; finance created a new cost center in Kingdee, and that record simply didn't exist in OA.

The "Query Kingdee Departments" strategy solves this most basic yet error-prone problem: making ERP department master data the single source of truth, pushing it to the middleware on a schedule, and letting downstream OA, HR, and expense systems consume it as needed. We use the Qeasy Data Integration Platform to host this data channel, and no custom development is required inside the ERP.

Data Flow and Field Mapping

The flow is straightforward: Kingdee Cloud → Qeasy middleware → downstream OA. The source side calls Kingdee's executeBillQuery bill-query interface, and the target is a "write null operation" placeholder node—real consumers are the downstream strategies that depend on this one.

Key field mapping:

Note that source-side buildModel: true means the platform auto-constructs the response model from return values; autoFillResponse: true lets the platform auto-fill response fields into metadata—these two switches are standard for Kingdee query-type strategies.

How to Configure in Qeasy

In the Qeasy Data Integration Platform, this strategy's configuration has three core parts:

First, source metadata. Under the Kingdee Cloud connector, create a QUERY-type strategy, select executeBillQuery for the API, method POST. Then configure the five fields—FDEPTID, FNumber, FName, FUseOrgId.FNumber, FCreateOrgId.FNumber—per the spec. Set number to FNumber, id to FDEPTID, and idCheck to false—because we identify department uniqueness by code, not internal FID.

Second, target placeholder. Because department data isn't written directly to a target system but consumed by downstream strategies at the middleware layer, the target side is configured as a WebAPI "write null operation" node with empty request and response bodies, buildModel: false. This is a common Qeasy customer pattern—"headers settle first, line items follow in stages"—master data lands stably first, business documents reference it later.

Third, scheduling policy. Source cron: */5 7-23 * * *, i.e., every 5 minutes during business hours; target cron: 1 1 1 1 1 (placeholder, not actually triggered).

Implementation Steps

We recommend a three-phase rollout:

Phase 1: Full baseline. First use Qeasy's "manual trigger" to run a full pull, bringing all valid departments from Kingdee to the middleware. The key check here: does the returned record count match the result of select count(1) from t_org_department where FDeleted=0 in the ERP? If not, more often than not, a filter condition is missing—Kingdee's executeBillQuery returns deleted records by default, so a FilterString filter is mandatory.

Phase 2: Incremental start point. Once the full pull completes, use Kingdee's "last modified time" field (usually FModifyDate) as the incremental cursor. In Qeasy, configure "last successful execution time + 1 second" as the next query start point, so subsequent runs only fetch incrementals. Note that Kingdee's time fields carry timezone info—cross-timezone deployments often trip here; the safe approach is to standardize on the ERP server's timezone midnight.

Phase 3: Schedule go-live and monitoring. Loosen the cron from "every 5 minutes" to all day, and observe 24-hour success rates. Kingdee's query interface has concurrency limits—it's recommended to set the per-connector QPS to 2 or below in Qeasy's connector config to avoid triggering Kingdee's rate limiting. On monitoring, watch two lines: per-execution row counts (a spike may indicate bulk organizational changes), and failure retry counts (persistent failures usually mean token expiry or account-set switch).

Pitfalls Retrospective

1. Code mapping not centrally managed—two sides drift apart after 3 months. A classic mistake is hardcoding "FNumber → OA code" directly in field mapping. The recommendation is to build a separate "code mapping table" in Qeasy, maintaining the relationships among ERP code, OA code, and middleware code; subsequent organizational adjustments modify this table only, not the strategy itself.

2. Ignoring the multi-org semantics of "using org" and "create org". Kingdee departments support multi-org—the same department code is a different entity under different orgs. We've seen customers miss this and merge same-named departments from different orgs into one record, causing downstream approval flows to route to the wrong responsible person.

3. Deleted departments getting synced. As mentioned above, Kingdee's query interface includes deleted records by default. A FilterString: FDeleted=0 must be added to the request parameters, otherwise downstream sees a bunch of "ghost departments".

4. Incremental cursor drift. When using FModifyDate as the incremental cursor, clock skew between the ERP server and the Qeasy server can cause "missing data" or "duplicate data". The safe approach is to use Qeasy's built-in "watermark" mechanism, letting the platform manage cursors automatically rather than hand-writing SQL.

5. Data loss during full-to-incremental switchover. If new data arrives between the full pull and the first incremental pull, either use the "full overlay + incremental supplement" dual-track approach, or place the switch during off-peak hours. This is the "incremental + full dual-track" pattern common among Qeasy customers.

Applicable and Non-Applicable Scenarios

Applicable: Private-deployment integration projects where the ERP is the master-data source and organizational/department/personnel master data needs to be stably pushed to downstream OA, HR, and expense systems; multi-org, multi-account-set group enterprises; scenarios requiring high data consistency where manual department maintenance in OA is unacceptable.

Not applicable: Scenarios requiring sub-second real-time (Kingdee's query interface itself has latency, plus scheduling cadence—the fastest is minute-level); enterprises with frequently changing org structures (more than 50 add/delete/modify operations per day)—these are better served by event-driven architectures rather than polling.