Qeasy Cloud
Get Started

Auto-Creating WeCom Members from Jiandaoyun Onboarding Forms: A Single-Strategy Tutorial

· 陈洁琳· Integration Solutions· 36 views· 4 min read

What this strategy solves

In many companies, HR fills out a Jiandaoyun onboarding form (name, mobile, department, position, etc.) for every new hire, then has to manually create the employee's account in WeCom (WeChat Work) and send the invitation. It looks like a small task, but at dozens or hundreds of new hires per month it is easy to forget, mistype fields, or delay — leaving new employees unable to join groups on day one.

We used Qeasy Data Integration Platform (轻易云) to chain these two steps together: once a Jiandaoyun form is submitted, a scheduled job picks up the new records and calls the WeCom open API to create the member and send the invitation. In one real project, the customer's feedback was: "HR no longer has to log into two systems, and new hires receive the WeCom invitation the same day."

Data flow and field mapping

The overall flow is "Jiandaoyun (source) → Qeasy middle layer → WeCom (target)". The source uses a query-type API to fetch form data; the target uses a WebAPI to write the member into the address book.

Key field mapping (sensitive fields omitted; core mapping logic shown):

Business meaningJiandaoyun source fieldWeCom target fieldMapping note
Document / business no._id—Used as idempotency key to prevent duplicate creation
Member UserIDEmployee number field in formuserid1–64 bytes; digits/letters/-_.@; first char must be digit or letter
Member nameChinese name fieldnamePass-through
MobileMobile fieldmobileUsed for invitation; format validation required
DepartmentDepartment fielddepartmentMultiple depts use comma-separated ID list
PositionPosition fieldpositionPass-through
Whether to invite—to_inviteUsually fixed as true to trigger the WeCom invitation

The mapping itself is best placed in Qeasy's "Field Mapping" module for centralized management. All sync strategies share the same mapping table, so adding or removing a field later only requires a single edit.

How to configure it on Qeasy

There are three configuration layers:

  1. Source connector: Create a "Jiandaoyun" connection with the app ID and form ID, using the /api/v2/app/{app_id}/entry/{entry_id}/data query endpoint with POST, returning 100 records per page (limit=100). The key here is the filter parameter: an incremental condition based on update or create time is mandatory. Otherwise every run scans the full table, which is slow and easily hits rate limits.
  2. Target connector: Create a "WeCom" connection using the /cgi-bin/user/create endpoint with POST. This relies on the corp ID and application secret (obtained from the WeCom admin backend and stored securely). The Qeasy connector already wraps the signature and token caching, so manual authentication is rarely needed.
  3. Data transformation: In Qeasy's data transformation node, map source fields to target fields according to the table above. For fields like UserID that have charset restrictions, a safe approach is to first run a regex cleanup (/^[A-Za-z0-9][A-Za-z0-9\-_.@]{0,63}$/), route non-compliant data into an exception branch, and never let dirty data take down an entire batch.

Implementation steps

We recommend rolling out in three phases to avoid blow-ups at launch:

Phase 1: Align the incremental start point Before going live, capture a "start timestamp" on the Jiandaoyun side. Qeasy then pulls incrementally from that point based on update time, ensuring that historical data is never treated as "new hires" and pushed to WeCom.

Phase 2: Full trigger (optional) If the customer wants existing staff backfilled in one go, you can use Qeasy's "Full Trigger" button. Once it finishes, immediately switch back to incremental mode. A safe approach is to prefix the UserID (for example legacy_xxx) and switch back to the official ID after every member is activated on the WeCom side, avoiding conflicts with later incremental records.

Phase 3: Stable scheduling The source crontab is recommended as */20 2-23 * * * (every 20 minutes, from 02:00 to 23:00), and the target write crontab as */30 2-23 * * * (every 30 minutes). Staggering the two avoids hammering the WeCom API at the same instant. A common pattern among Qeasy customers is the "dual-track incremental + full" approach: rely on incremental scheduling daily, run a monthly full reconciliation, and alarm whenever the two sides disagree.

Lessons learned

  • A typical mistake is leaving the filter empty. Without filter, Jiandaoyun returns the full table — slow, easily rate-limited, and any miscalculation of the incremental start point cascades into chaos. The safe approach is to always pass update_time > ${last_sync_time} as the filter.
  • UserID charset pitfalls are common. HR casually fills in Chinese or whitespace in the form, and WeCom returns 400 directly. The regex cleanup + exception branch mentioned above is not "nice to have" but "mandatory".
  • Mobile number format is often ignored. Country codes, dashes or spaces all cause WeCom to reject the request. Qeasy's built-in string-handling functions can normalize the value to plain 11 digits in one step.
  • Department IDs are pushed without conversion. Jiandaoyun has department names; WeCom needs numeric IDs. A common Qeasy customer pattern is "centralized encoding mapping": build a department mapping table in Qeasy's data dictionary, referenced by both sides, so adding or removing a department is a single edit.
  • No idempotency. When the scheduler hiccups or someone manually retriggers, the same _id may be pushed twice. The source _id must serve as the idempotency key, and Qeasy's built-in "skip duplicates" switch should always be enabled.

Applicable and non-applicable scenarios

Applicable: HR workflows live in Jiandaoyun, the address book lives in WeCom, and new hires need to be in WeCom on day one; or similar "new business form entry → create account on an IM platform" scenarios such as training registration, store staff onboarding, or part-time worker registration.

Not applicable: High-frequency changes for existing employees such as transfers, department moves, or offboarding deletions. This strategy only covers "create"; updates and deletions need a separate one, with different fields and trigger conditions, and cannot be reused directly.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-wecom-pcdd5c6-8957-n775ed839-e3ef40a9

Comments