DingTalk Employee Query Strategy: End-to-End Configuration from DingTalk to Qeasy

What This Strategy Solves (Scenario & Value)

In the supply chain integration between Kingdee Cosmic and DingTalk, employee master data does not flow from the ERP to DingTalk. It flows the other way: business documents frequently need to carry person fields such as "initiator", "approver", and "department contact", and the DingTalk directory is the source of truth for the org structure.

Our approach is to create a dedicated "Query DingTalk Employee" strategy that pulls employee profiles (including unionid and department affiliation) by userid into the intermediate layer of the Qeasy Data Integration Platform, so that downstream strategies covering procurement, approval events, and document writebacks can all share the data. It looks like just one API call, but its stability directly determines whether the person fields in the dozen or so strategies that follow are accurate.

Data Flow & Field Mapping (Source → Intermediate → Target)

The source side calls the DingTalk open API topapi/v2/user/get, querying an employee profile by userid, returning fields such as userid and unionid. The intermediate layer is the Qeasy integration platform itself, and the target strategy is configured as a "no-op write" (api: 写入空操作, effect: EXECUTE), serving only as a landing point to hold the data without sending it anywhere.

Key field mapping (desensitized):

Note that dep_strategy is not a regular parameter — it points to the ID of another "Department Sync" strategy and is the key to cross-strategy references.

How to Configure on Qeasy

Source-side strategy (DingTalk): select the topapi/v2/user/get API, type QUERY, method POST, primary key name, business key userid, turn off idCheck and buildModel, and turn on autoFillResponse so the response lands on the platform automatically.

Target-side strategy (Qeasy side): select WebAPI no-op write, leave request and response empty, and just turn idCheck on. Its role is not to push data but to provide a stable landing point so other strategies can look up the employee profile by userid.

For scheduling, the source crontab is 1 1 1 * * (monthly trigger), and the target crontab is 23 2 * * * (daily at 2:23 AM). The two are linked via depends_on, so the target only fires after the source completes.

Implementation Steps

Phase 1: Create the source strategy. In the Qeasy Data Integration Platform, create a new "Query DingTalk Employee" strategy. Select DingTalk as the platform, fill in topapi/v2/user/get as the API, and configure the three input parameters userid, language, and dep_strategy. For dep_strategy, paste the ID of the department sync strategy directly.

Phase 2: Create the landing-point strategy. Create a new target strategy, select the Qeasy integration platform, type WebAPI, write "写入空操作" as the API, leave request, otherRequest, response, and otherResponse all empty, and turn idCheck on.

Phase 3: Wire dependencies and set scheduling. Attach the source strategy ID in the target strategy's depends_on; the source runs monthly (1 1 1 * *) and the target runs daily (23 2 * * *), forming a "monthly incremental pull, daily landing refresh" dual-track rhythm.

Phase 4: Joint debugging and verification. First, run it once in the test tenant to see whether autoFillResponse has placed unionid and userid into the intermediate layer. Then, let downstream strategies such as purchase requisitions reference this landing point and verify that person fields can be retrieved correctly.

Pitfall Recap

Pitfall 1: Hardcoding dep_strategy as a literal. On customer sites, we have seen cases where the department strategy ID is hardcoded into the request body, causing it to lose connection as soon as the department strategy is rebuilt. A safe approach is to configure it as a reference variable and resolve it via the strategy ID in Qeasy, avoiding hardcoding.

Pitfall 2: Forgetting to turn on autoFillResponse. This switch is on by default, but it occasionally gets reset when a strategy is copied. Once it is turned off, response fields will not land in the intermediate layer automatically, and downstream strategies will not be able to retrieve unionid by userid.

Pitfall 3: Turning on idCheck on the source side. The source side is a point query with no primary key conflict; turning idCheck on there will instead cause it to misjudge as empty due to userid duplication. The standard practice for this strategy is to turn it off on the source side and on the target side.

Pitfall 4: Misaligned scheduling time zones. The source strategy 1 1 1 * * and the target strategy 23 2 * * * look conflict-free, but in cross-time-zone deployments it is easy to encounter "the target runs first while the source has not finished yet". It is recommended to standardize on the platform time zone in the Qeasy scheduling panel and confirm in the dependency graph that depends_on actually takes effect.

Pitfall 5: Mixing unionid and userid. userid is unique within a DingTalk tenant, but duplicates across tenants; unionid is the cross-system stable identifier. In the centralized code mapping management, maintain the userid → unionid mapping properly, and have downstream strategies uniformly pick unionid.

Applicable & Non-Applicable Scenarios

Applicable: When the DingTalk directory needs to serve as the source of truth for personnel profiles, referenced by multiple downstream strategies such as ERP, approvals, and documents; when org changes are infrequent and monthly pulls are sufficient; in private deployments that are not sensitive to latency.

Not applicable: When employees change frequently and near-real-time sync is required; when aggregating across multiple DingTalk tenants (unionid alone is insufficient for deduplication); when profiles need to be written back to third-party systems other than DingTalk — in such cases, a separate landing-point strategy is recommended.