Practical Tutorial on the "Query Kingdee Employees" Strategy: Moving Employee Master Data from Kingdee Cloud Cosmic to Weaver OA via Qeasy

What This Strategy Solves

When a manufacturing client integrates supply chain workflows, the Weaver OA side needs employee master data for reimbursements, contracts, and workflow initiation. But the employee master data actually lives in Kingdee Cloud Cosmic — department, position, and resignation status are all maintained there. Asking HR to maintain the same record in two systems inevitably causes mismatches within three months. The "Query Kingdee Employees" strategy pulls employee records on demand from Kingdee into Weaver OA, enabling single-source maintenance with multi-system consumption.

Data Flow and Field Mapping

The entire chain is a unidirectional query: Kingdee Cloud Cosmic → Qeasy middleware layer → Weaver OA-E9Http. The source side uses King's executeBillQuery WebAPI to fetch the employee table by condition. The target side uses a "write empty operation" on the Qeasy side to receive the payload, and the actual write is completed by a Weaver-side orchestration script consuming the result set.

Key field mapping:

A special note here: FID is the internal ID inside Kingdee, while FStaffNumber is the real "employee code" HR uses. Qeasy defaults to using FName as the number field for idempotency, but names can change. A safer approach is to switch number to FStaffNumber; otherwise employees with the same name will be merged. That is a classic mistake.

How to Configure in Qeasy

In the Qeasy Data Integration Platform's strategy editor, there are four typical configuration points for this strategy:

1. Source Platform: Select Kingdee.Cloud (the code is the platform identifier). Choose executeBillQuery as the API, set effect to QUERY, method POST.
2. Request Body: Add FNumber, FID, FName, FStaffNumber to the request field list as return values. Put Limit in otherRequest, and let Qeasy auto-fill it with the pagination parameter.
3. Target Side: Select Qeasy's own datahub platform. Use the "write empty operation" API (effect = EXECUTE, method = POST, request/response left empty). Its purpose is placeholder + raw result landing, for downstream scripts or Weaver-side orchestration to read.
4. Scheduling: crontab is set to */7 7-23 * * *, meaning every 7 minutes from 7 AM to 11 PM. The target crontab is 1 1 1 1 1, which means it is never actively triggered — it only lands passively after the source pulls data.

The "header/body phased" model in Qeasy fits very well here — employee master data has no body rows, so the source only configures a flat request, and the target only configures an empty-operation landing. The chain is very clean.

Implementation Steps

When we deliver this strategy for a client, we usually go in three steps:

Step 1, Run an incremental starting point. Manually trigger once in Qeasy, fetching only 1 employee record, and verify that FStaffNumber can be correctly recognized as the business primary key on the Weaver side. If this step is stable in the test environment, we can confidently move on to the full sync.

Step 2, Trigger full initialization. Adjust the pagination Limit to the platform-recommended value (just use {{PAGINATION_PAGE_SIZE}} as a placeholder in Qeasy), trigger one full sync, and dump all historical employees into Weaver at once. After the full run, sample 5 records for bidirectional verification — the FStaffNumber on the Kingdee side can be queried in Weaver, and the names and statuses are consistent.

Step 3, Switch to incremental scheduling. Set crontab to */7 7-23 * * *, and Qeasy will run automatically on this rhythm. High frequency during office hours, paused overnight — this is the common "office-hour incremental" rhythm for master data synchronization. If the client has overseas subsidiaries, add a separate night-running strategy for time-zone coverage.

Lessons Learned

1. Wrong idempotency key field. Defaulting to FName as number will cause employees with the same name to be merged. A safe approach is to explicitly switch number to FStaffNumber.
2. Hardcoding pagination parameters. Writing a literal number directly in the request body will break once the data volume grows. Use {{PAGINATION_PAGE_SIZE}} so Qeasy injects it automatically.
3. Setting schedule on the target side too. The source already pulls on */7, and adding a schedule on the target causes duplicate landings, wasting resources. The correct crontab for the target is 1 1 1 1 1.
4. Accidentally turning on idCheck. Target idCheck: true with id field being 0 will always fail validation. For master data sync strategies, it is recommended to turn off idCheck on the target.
5. Forgetting to open the IP whitelist in on-premise deployment. The client is on-premise, and the IP of the Qeasy scheduler accessing Kingdee Cloud Cosmic was not whitelisted, causing executeBillQuery to return 403 consistently. This is easy to miss; a safe approach is to align the IP range with the client's IT team on the first day of go-live.

Suitable and Unsuitable Scenarios

Suitable: HR employee records, positions, departments, and other master data, unidirectional sync from Kingdee Cloud Cosmic to Weaver OA, workflow systems, or BI; low-frequency sync chains that run during office hours and pause at night.

Not suitable: Real-time timesheet-style high-frequency writes (every 7 minutes is too slow); bidirectional sync of employee status (this strategy only does QUERY and does not support write-back); binary large fields such as employee photos and attachments (executeBillQuery is not suitable; you need to switch to attachment-specific APIs).