HR Personnel Update Sync to DingTalk: Solution Design & Field Mapping

Feature Overview

We designed this feature to solve a recurring problem: HR master data changes frequently, but DingTalk contacts rarely get refreshed in time. In mid-sized and large organizations, onboarding, transfers, and contract entity adjustments happen every day. Maintaining DingTalk manually is error-prone and almost never keeps the extension attributes consistent.

"HR Personnel Update Sync to DingTalk" is a standard synchronization template shipped inside the Qeasy DataHub. Its responsibility is straightforward: take the HR employee table on MySQL as the source, call DingTalk's topapi/v2/user/update API, and write incremental changes back into the DingTalk user's extension field.

The data flow is MySQL → DingTalk, and the mode is incremental. The increment predicate is based on the employee upd_time column with a 15-day buffer to prevent data loss caused by clock drift or short polling windows. The recommended schedule polls the source every 30 minutes, with the target offset by 3 minutes to avoid simultaneous requests on both ends.

Typical Use Cases

The typical scenario is: HR is the single source of truth for personnel master data, while DingTalk serves as the identity backbone for collaboration. Whenever the following events occur, HR updates the row and stamps upd_time, and this template propagates the change:

• Contract entity changes, for example an employee moving from subsidiary A to subsidiary B.
• Future extensions, such as writing employee number, job title, or hire date into DingTalk extension.
• Repairing missing or incorrect DingTalk extension attributes caused by historical issues.

It is important to note: this template only handles updates. New hires and offboarding should be handled by dedicated "create" and "delete" templates so each policy stays single-purpose and easy to maintain.

Configuration Guide

1. Source Objects

The source is composed of three joined tables:

• base_user: the main employee table, providing dingtalk_user_id, name, upd_time, whether_in_office, and other critical columns.
• file: employee attachment/file table, providing avatar or identifier metadata.
• base_contract_company: contract company table, providing company_name.

Three filters must all hold; missing any of them causes data quality issues:

• a.whether_in_office = 1: only active employees are synchronized.
• a.dingtalk_user_id is not null: the employee must already be bound to DingTalk, otherwise the update API cannot locate the user.
• c.company_name is not null: a contract company must exist, so empty values are not pushed to extension attributes.

2. Target Object and Field Mapping

The target is the DingTalk contact user, updated via topapi/v2/user/update. Currently the template maps two fields:

DIRECT uses {{source field}} interpolation; CONSTANT writes a fixed value; COLLECTION looks up via a code mapping table; TRANSFORM applies an expression or function. The current template uses direct mapping only, with no code tables involved.

3. Prerequisites for the DingTalk extension Field

DingTalk extension is an object with a maximum length of 2000 characters. Before activating this template, you must first add the corresponding extension attribute (for example, "公司") in the DingTalk admin console under "Contacts → Internal Contact Settings → Member Field Management". Even if the DataHub side is perfectly configured, calls will fail silently if the target field does not exist on the DingTalk side.

Also note that DingTalk's update API performs a full replacement of extension: any attribute not present in the payload will be cleared. If you later need to sync multiple fields such as company, employee number, and job title, you must map them all in a single template so that nothing is wiped out.

4. Schedule and Incremental Window

Default recommendations:

• Source: 2-59/30 * * * *, starting at minute 2 of every hour, every 30 minutes.
• Target: 5-59/30 * * * *, starting at minute 5 of every hour, offset by 3 minutes.

The incremental window is implemented as a.upd_time > adddate(:upd_time, -15), providing a 15-day buffer. The 15-day window is designed to cover the following edge cases:

• The source clock runs slower than the target.
• A row's upd_time is rewritten backward by a manual data fix.
• Upstream batch jobs write at night while the schedule missed the cycle.

Notes and Caveats

1. No create, no offboard: Do not try to extend creation or deletion logic beyond extension. Use dedicated create/delete policies.
2. extension is a full replace: Each call overwrites all extension fields. Make sure every field is mapped.
3. Pre-create the field on DingTalk first: DataHub cannot register custom fields in the DingTalk admin console. Skipping this step leads to failures that are hard to diagnose.
4. All three filters are mandatory: Especially whether_in_office = 1; otherwise stale data from offboarded employees may overwrite DingTalk.
5. Stagger is a recommendation: When multiple target systems exist (for example, DingTalk and WeCom together), widen the offset between them to avoid rate-limiting.
6. Extension keys must match exactly: If the admin console defines "公司", the template key "公司名" will be rejected.
7. _findCollection, _mongoQuery, and _function are not used here: If you later need external lookups by business key, complex joins, conditional logic, or format conversion, refer to DataHub's advanced documentation and add those capabilities inside this template instead of creating a parallel one.

With the above configuration, HR master data changes are reliably propagated to DingTalk contacts every 30 minutes, keeping the two systems in sync.