Feishu Employee Master Data Integration: Pulling Users into Qeasy Data Hub

What This Strategy Solves

Feishu employee master data needs to be reliably cached and exposed for cross-strategy lookup. In one of our actual projects, the customer's pain point wasn't writing employees into the ERP — it was how to let downstream documents like purchase orders, sales orders, and reimbursement forms stably retrieve Feishu user IDs in the "handler" field and then map them to Kingdee Cloud Xingchen employee codes. This strategy does exactly that: recursively pull employees from Feishu by department and write them into the Qeasy Data Integration Platform hub, then expose them to downstream strategies via _findCollection or _mongoQuery.

Data Flow and Field Mapping

Data flow: Feishu → Qeasy Data Hub.

The source calls /open-apis/contact/v3/users/find_by_department to recursively pull employees by department. The target is a "write-null operation" — the source response is stored 1:1 into the hub.

Other fields (avatar, city, country, gender, join_time, open_id, work_station, enterprise_email, etc.) are all stored via DIRECT mapping.

How to Configure on Qeasy

When configuring this strategy on the Qeasy Data Integration Platform, there are several typical points to note:

Source configuration: Select api /open-apis/contact/v3/users/find_by_department, effect QUERY, method GET. Set id field to user_id, number field to name, idCheck to true. Request parameters: department_id=0 (start from root department), page_size=50, user_id_type=union_id. The dep_strategy parameter references the "Get Feishu Departments-OK" strategy ID, and the platform will recursively pull employees from sub-departments. Pagination key is has_more, data path is data.items.

Target configuration: Select api "write-null operation", effect EXECUTE, leave request and response empty. This is an elegant mechanism in Qeasy — the target doesn't call any external API, data is persisted directly into the platform hub by strategy_id, available for other strategies to cross-query.

Schedule configuration: Source crontab is 3 2 * * * (daily at 02:03). Target crontab is 1 1 1 1 1 (placeholder, never actually triggers).

kd_number extension field: Defaults to {{name}}, but in production it should typically be changed to _findCollection against the Kingdee Cloud Xingchen employee sync strategy's hub, or use a code-mapping table for COLLECTION mapping to stably map Feishu user_id/employee_no to Xingchen employee codes.

Implementation Steps

Step 1: Confirm the department strategy is ready first. "Get Feishu Employees" strongly depends on "Get Feishu Departments-OK", because recursive employee pulling requires the department ID list. First confirm the department strategy has been running stably and the hub has a complete department tree.

Step 2: Configure and test single-department pull. Change department_id to a specific department ID (not 0), leave dep_strategy empty, and run once to confirm single-department employee pulling works. A common pitfall here is Feishu App contacts permission scope — if the app is only authorized for some departments, the root department 0 pull returns an empty array.

Step 3: Switch to root department recursive mode. Change department_id back to 0, fill in dep_strategy with the department strategy ID, then run the full pull. Observe whether pagination completes correctly (whether has_more triggers the next request), and whether the hub record count matches the Feishu backend employee count.

Step 4: Configure downstream cross-query strategies. In the employee fields of downstream strategies like purchase orders and sales orders, use _findCollection from this strategy's hub by user_id or employee_no, then map to Kingdee Cloud Xingchen employee codes.

Step 5: Schedule go-live and monitoring alerting. Set crontab to 02:03 daily, offset from downstream business document sync windows. Configure hub record count monitoring and API success rate alerts.

Pitfall Review

Pitfall 1: Incomplete permission scope. If the Feishu app's contacts permission only includes some departments, the root department 0 pull returns an empty array. The safe approach is to first confirm the app's visibility scope on the Feishu open platform, or validate department-by-department with specific department IDs.

Pitfall 2: Wrong user_id_type selection. If you select open_id, the same user has different open_ids across apps, which breaks cross-app mapping. We recommend union_id, which is unique across apps and supports stable mapping with Kingdee.

Pitfall 3: kd_number directly using name. Using {{name}} as the Kingdee employee identifier in production leads to mismatches when duplicate names or personnel changes occur 3 months later. The safe approach is to change kd_number to _findCollection against the Kingdee Cloud Xingchen employee strategy, or maintain a code-mapping table for COLLECTION mapping.

Pitfall 4: Pulling employees before the department strategy runs. When the department hub has no data yet, dep_strategy recursion won't get the sub-department list and employee pulling will be incomplete. During implementation, always let the department strategy run stably for at least one schedule cycle first.

Pitfall 5: Ending before pagination completes. When has_more is true, pagination must continue, otherwise data will be lost. The Qeasy platform handles this automatically, but during manual validation, confirm that total record count matches the Feishu backend.

Applicable and Non-Applicable Scenarios

Applicable scenarios: Master data caching for foundational records, cross-system employee code mapping (Feishu ↔ Kingdee), downstream business document handler/approver field lookup, data preparation before org structure sync.

Non-applicable scenarios: Scenarios requiring real-time employee change notifications (use Feishu event subscription instead), scenarios requiring writing into external business systems (this strategy's target is a null operation and won't call external APIs), scenarios with extremely deep department hierarchies where recursive performance is unacceptable (switch to batch pulling by business line instead).