Querying the Personnel Directory: A Practical Sync Strategy from Feishu to the Integration Platform

What This Strategy Solves

In supply-chain integration projects, the personnel directory is the source of truth for document ownership, approver mapping, and organizational permissions. After a retail company went live with Kingdee Cloud Cosmic, approvers in the workflow no longer matched the Feishu org structure—departed employees were still sitting on approval nodes, and new hires could not get added. The cause was simple: the Feishu directory was never synced into the middleware, so downstream systems could not get a consistent view of "people."

The "Querying the Personnel Directory" strategy periodically pulls Feishu personnel data into the Qeasy integration platform, making it the "person" master-data source for downstream mapping and writes. It does not touch business documents directly; its job is to align people.

Data Flow and Field Mapping

The data flow is straightforward: Feishu → Qeasy integration platform → consumed by other strategies.

Several request parameters deserve attention. department_id defaults to 0, meaning the root department. page_size=1 is Feishu's "items per page" setting. user_id_type is set to union_id, which means the user_id returned by Feishu is actually a union_id—critical for cross-system reconciliation. dep_strategy looks like a Feishu field, but it is actually the ID of a preceding department strategy, used in Qeasy to chain the department and personnel strategies.

Configuring It in Qeasy

When configuring this strategy in Qeasy, we usually classify it under "Master Data Sync" with type QUERY_ONLY and sequence A, indicating it is an upstream strategy.

Key configuration points:

1. Interface selection: The source side uses the Feishu connector; the target side uses "Qeasy integration platform" but is actually a placeholder EXECUTE that lands the data into the platform's own resource pool for downstream consumption.
2. Request parameter mapping: department_id, page_size, and user_id_type can be hardcoded; dep_strategy uses Qeasy's variable resolution mechanism to pull the department ID from a preceding strategy.
3. Response model: With autoFillResponse=false, we must manually define the parsing model for Feishu's response fields, including at least user_id, name, department_id, email, and mobile.
4. Idempotency: idCheck=true, with user_id as the idempotency key, so repeated pulls do not produce dirty data.

Implementation Steps

We typically break the rollout into three stages.

Stage 1: Connectivity validation. Create a debugging job in Qeasy and manually trigger a single find_by_department request to confirm Feishu's token, tenant, and app scopes all work. The most common pitfall here is forgetting to enable the directory permission scope for the relevant departments.

Stage 2: Phased scheduling.

• Incremental start: First run pulls everything, recursively traversing all sub-departments under the root.
• Full sync trigger: Manually triggered at go-live; Qeasy tags it as "full sync" in the background.
• Schedule: Daily schedule during low-peak hours; a crontab like 42 3 * * * triggers at 03:42 every day. Note that the crontab in the source strategy file and the one in index.json serve different purposes—the former controls this strategy's trigger cadence, the latter acts as a fallback for the whole solution group.

Stage 3: Downstream linkage. This strategy does not write to any business system, but once it runs reliably, downstream strategies like "Write Personnel to Downstream" and "Org Structure Sync" can pick up consistent master data. We often recommend that customers centralize code mapping in Qeasy's Mapping Center rather than scattering it across individual strategies.

Lessons from the Field

Pitfall 1: Mistaking department_id for a Feishu department code. Feishu's department_id is an open_id-style identifier, not the department code used in HR systems. Trying to reconcile it directly with Kingdee's department code will never match. The safe approach is to build a "department code mapping table" in Qeasy and translate there.

Pitfall 2: Choosing the wrong user_id_type. Feishu supports open_id, union_id, and user_id. Pick the wrong one and your entire "person" table collapses into a single identity. In real projects we default to union_id because it is stable across apps and will not break if a specific app is decommissioned.

Pitfall 3: Ignoring Feishu's pagination. The directory API is paginated by default. In our material, page_size=1 is actually a counterexample—in production you should set it to 50 or 100 and walk pages with page_token. Otherwise a 5,000-person company will require 5,000 requests and quickly hit Feishu's rate limit.

Pitfall 4: Not separating department and personnel schedules. In one real project we lumped both into a single strategy. The personnel runs began before the department run had finished, leaving many personnel records with unresolvable department_id values. Splitting them—department as sequence B, personnel as sequence A—fixed it instantly.

Pitfall 5: Skipping the dual-track of incremental and full sync. Running incremental daily is fine, but if Feishu undergoes an org adjustment, incremental alone will miss data. The safer approach in Qeasy is to configure a "full reconciliation" task that runs weekly or monthly to validate the incremental results.

When to Use It and When Not To

Use it when: Feishu is the authoritative source for personnel master data, and you need to distribute it to downstream ERPs, HR, or finance systems—especially systems like Kingdee Cloud Cosmic, Yonyou, or SAP that depend on org structure for access control.

Avoid it when: The company already has a mature HR master-data system (such as Beisen or SAP SuccessFactors) and treats HR as the authoritative source. In that case this strategy should serve only as auxiliary validation, not as the primary source.