@nocobase/plugin-ai 2.1.41 → 2.1.44

package/dist/ai/docs/nocobase/users-permissions/sync/index.md

@@ -8,6 +8,13 @@ pkg: '@nocobase/plugin-user-data-sync'
 
 This feature allows you to register and manage user data synchronization sources. By default, an HTTP API is provided, but additional data sources can be supported through plugins. It supports syncing data to the **Users** and **Departments** collections by default, with the possibility to extend synchronization to other target resources using plugins.
 
+## Available data sources
+
+- [DingTalk](./sources/dingtalk.md) — Synchronize DingTalk users and departments, with incremental updates through HTTP callbacks or Stream mode.
+- [LDAP](./sources/ldap.md) — Synchronize LDAP users and optional organizational units by reusing an LDAP authenticator.
+- [WeCom](./sources/wecom.md) — Synchronize users and departments from WeCom.
+- [HTTP API](./sources/api.md) — Push user and department data through the synchronization API.
+
 ## Data Source Management and Synchronization
 
 
@@ -51,4 +58,4 @@ For failed synchronization tasks, you can click **Retry**.
 In case of synchronization failures, you can troubleshoot the issue through system logs. Additionally, raw synchronization records are stored in the `user-data-sync` directory under the application logs folder.
 
 
-![](https://static-docs.nocobase.com/202412041205655.png)
+![](https://static-docs.nocobase.com/202412041205655.png)

package/dist/ai/docs/nocobase/users-permissions/sync/sources/dingtalk.md

@@ -0,0 +1,138 @@
+---
+pkg: '@nocobase/plugin-auth-dingtalk'
+title: "Synchronize User Data from DingTalk"
+description: "Synchronize DingTalk users and departments to NocoBase and receive incremental changes through HTTP callbacks or Stream mode."
+keywords: "DingTalk,user synchronization,department synchronization,Stream mode,event subscription,NocoBase"
+---
+
+# Synchronize User Data from DingTalk
+
+<PluginInfo commercial="true" name="auth-dingtalk"></PluginInfo>
+
+## Introduction
+
+The **DingTalk** plugin synchronizes users and departments from a DingTalk organization to NocoBase. It supports full synchronization on demand and incremental updates through either an HTTP callback or a Stream connection.
+
+## Before you begin
+
+1. Install and enable the **DingTalk** and **User Data Synchronization** plugins.
+2. Create an internal application in the DingTalk developer console.
+3. Grant the contact permissions and configure the data permission scope described below.
+4. Copy the application's Client ID and Client Secret. See [Authentication: DingTalk](/auth-verification/auth-dingtalk/) for the credential setup.
+
+## Configure contact permissions and the data permission scope
+
+Open **Permission Management** for the application in the DingTalk developer console and grant the following contact permissions.
+
+| Permission | Identifier | Required | Purpose |
+| --- | --- | --- | --- |
+| Read department information | `qyapi_get_department_list` | Yes | Read the department list, names, and hierarchy. |
+| Read department members | `qyapi_get_department_member` | Yes | Read the member list of each department. |
+| Read member information | `qyapi_get_member` | Yes | Read member details and department memberships. |
+| Employee mobile number information | `fieldMobile` | When using mobile numbers | Synchronize mobile numbers. This permission is required when **User unique identifier field** is `mobile`. |
+| Email and other personal information | `fieldEmail` | No | Grant this permission when user email addresses need to be synchronized. |
+
+After granting the permissions, configure the application's **Data Permission Scope** (also called **Contact Permission Scope** or **Visibility Range** in some console versions) to include the departments and employees that may be synchronized. Select all employees for a full organization synchronization. If only selected departments or employees are included, NocoBase synchronizes only those entries.
+
+:::warning
+API permissions determine which fields the application can read, while the data permission scope determines which departments and employees it can read. Both must be configured. Event subscriptions do not replace contact read permissions: after receiving an event, NocoBase still calls DingTalk APIs to retrieve the latest user or department information.
+:::
+
+If the same DingTalk application is also used for sign-in, grant the personal-information permissions described in [Authentication: DingTalk](/auth-verification/auth-dingtalk/). Those sign-in permissions are not required solely for user data synchronization.
+
+## Add a DingTalk synchronization source
+
+Go to **Users & Permissions > Synchronize**, click **Add new**, and select **DingTalk** as the type.
+
+Configure the following fields:
+
+| Field | Description |
+| --- | --- |
+| Source name | A unique name for this synchronization source. |
+| Enabled | Starts event reception for this source and enables synchronization tasks. |
+| Client ID | The Client ID of the DingTalk internal application. Environment variables and secrets are supported. |
+| Client Secret | The Client Secret of the DingTalk internal application. Environment variables and secrets are supported. |
+| User unique identifier field | Select `mobile` or `unionId`. Keep the selected field stable after the first synchronization. Users without a value for the selected field are skipped. |
+| Event receiving mode | Select **HTTP callback** or **Stream mode** for incremental user and department changes. |
+
+Save and enable the source, then click **Sync** to complete the initial full synchronization before relying on incremental events.
+
+## Choose an event receiving mode
+
+### Stream mode
+
+Stream mode establishes an outbound persistent connection from the NocoBase server to DingTalk. It does not require a public callback URL, Token, or EncodingAESKey.
+
+1. In the DingTalk developer console, open the application's event subscription settings and select **Stream mode**.
+2. Subscribe to the user and department change events required by the application.
+3. In NocoBase, select **Stream mode**, save the source, and enable it.
+
+The Stream client starts when the source is enabled. Updating, disabling, or deleting the source refreshes or closes the corresponding connection.
+
+:::info
+The NocoBase server must be able to establish outbound connections to DingTalk. A reverse proxy or public inbound callback endpoint is not required for Stream mode.
+:::
+
+### HTTP callback
+
+HTTP callback mode receives DingTalk events through a NocoBase callback URL.
+
+1. Select **HTTP callback** in NocoBase.
+2. Enter the Token and EncodingAESKey configured for the DingTalk event subscription.
+3. Save the source and copy the generated **Event callback URL**.
+4. Configure that URL in the DingTalk developer console and subscribe to the required user and department events.
+
+The callback URL must be reachable by DingTalk. In a production environment, expose it through HTTPS and make sure the reverse proxy forwards the request path unchanged.
+
+## Supported incremental events
+
+Both event receiving modes handle the following DingTalk events:
+
+| Event | Result in NocoBase |
+| --- | --- |
+| `user_add_org` | Create or update the user. |
+| `user_modify_org` | Update the user. |
+| `user_leave_org` | Delete the synchronized user. |
+| `org_dept_create` | Create or update the department. |
+| `org_dept_modify` | Update the department and synchronize its users. |
+| `org_dept_remove` | Delete the synchronized department. |
+
+## Synchronized fields
+
+### Department fields
+
+| DingTalk field | NocoBase field or purpose |
+| --- | --- |
+| `dept_id` | Source-unique department identifier. |
+| `name` | Department name. |
+| `parent_id` | Parent department used to build the department hierarchy. If the parent is outside the data permission scope, the department is synchronized as a root department. |
+
+### User fields
+
+| DingTalk field | NocoBase field or purpose |
+| --- | --- |
+| `mobile` or `unionid` | Generates the source-unique user identifier and username according to **User unique identifier field**. A user without the selected field is skipped. |
+| `name` | User nickname. |
+| `mobile` | Phone number. Requires the **Employee mobile number information** permission. |
+| `email`, falling back to `org_email` | Email address. Requires the **Email and other personal information** permission. |
+| `dept_id_list` | Department memberships. Only departments within the data permission scope are retained. |
+| `dept_order_list` | Primary department. |
+| `leader_in_dept` | Whether the user is an owner of the corresponding department. |
+
+### Department owners
+
+DingTalk uses `leader_in_dept` in the user details to indicate whether the user is an owner of each department they belong to. NocoBase synchronizes this flag separately for each department: the same user can own multiple departments, and an owned department does not have to be the user's primary department. Only departments within the data permission scope are included.
+
+When an owner flag is removed in DingTalk, the corresponding owner flag in NocoBase is removed by the next synchronization. Owner status changed manually in NocoBase may be overwritten by DingTalk data during the next synchronization.
+
+Full and incremental synchronization use the same field mapping. Other DingTalk user fields, such as avatar, job title, and employee number, are not currently synchronized.
+
+## Troubleshooting
+
+- If synchronization returns no data or an entire department is missing, verify the three required contact read permissions and confirm that the department is included in the data permission scope.
+- If a user is present but their mobile number or email address is empty, verify the **Employee mobile number information** or **Email and other personal information** permission respectively.
+- If DingTalk reports that a department or employee is outside the permission scope, expand the application's data permission scope instead of only resubscribing to events.
+- If users are skipped, verify that they have a value for the configured unique identifier field.
+- For Stream mode, check the application logs for `Dingtalk stream client starting`, `Dingtalk stream client started`, or connection errors.
+- For HTTP callback mode, verify that the callback URL is publicly reachable and that Token and EncodingAESKey match the DingTalk configuration.
+- Run a manual full synchronization after changing the application's permissions or visibility range.

package/dist/ai/docs/nocobase/users-permissions/sync/sources/ldap.md

@@ -0,0 +1,87 @@
+---
+pkg: '@nocobase/plugin-auth-ldap'
+title: "Synchronize User Data from LDAP"
+description: "Synchronize LDAP users and departments to NocoBase by reusing an existing LDAP authenticator."
+keywords: "LDAP,user synchronization,department synchronization,Bind DN,Search DN,NocoBase"
+---
+
+# Synchronize User Data from LDAP
+
+<PluginInfo commercial="true" name="auth-ldap"></PluginInfo>
+
+## Introduction
+
+The **Auth: LDAP** plugin can use an existing LDAP authenticator as a user data synchronization source. The synchronization source reuses the authenticator's LDAP connection, Bind DN, Search DN, search scope, and attribute mappings, then writes the resulting users and optional department hierarchy to NocoBase.
+
+## Before you begin
+
+1. Install and enable the **Auth: LDAP** and **User Data Synchronization** plugins.
+2. Create and verify an LDAP authenticator. See [Authentication: LDAP](/auth-verification/auth-ldap/).
+3. Make sure the authenticator's attribute mappings include the fields needed by NocoBase, such as username or email, nickname, and phone number.
+
+## Add an LDAP synchronization source
+
+Go to **Users & Permissions > Synchronize**, click **Add new**, and select **LDAP** as the type.
+
+Configure the following fields:
+
+| Field | Description |
+| --- | --- |
+| Source name | A unique name for this synchronization source. |
+| Enabled | Enables manual synchronization and LDAP synchronization tasks for this source. |
+| LDAP authenticator | The existing LDAP authenticator whose connection and attribute mappings will be reused. |
+| Sync filter | The LDAP filter used to find users during synchronization. The default is `(&(objectCategory=person)(objectClass=user))`. Adjust it to match your directory schema. |
+| Size limit | Optional maximum number of entries returned by an LDAP search. Leave it empty to use the LDAP server's default limit. |
+| Page size | Optional page size for paged LDAP searches. Use this when the directory contains more entries than a single query can return. |
+| Sync departments | Also synchronizes the LDAP organizational hierarchy to NocoBase departments. |
+| Department search DN | Required when department synchronization is enabled. Specify the DN that contains the organizational units to synchronize, for example `ou=departments,dc=example,dc=com`. |
+
+:::info
+The synchronization source uses the selected authenticator's Bind DN and Bind password to search LDAP. It does not store a second copy of the LDAP connection credentials.
+:::
+
+## Synchronize users
+
+Save and enable the source, then click **Sync** to start a full synchronization. Open **Task** to review the result and retry a failed task.
+
+User matching follows the field selected in the LDAP authenticator's **Use this field to bind the user** setting. Keep that setting and the authenticator's attribute mappings stable after the first synchronization to avoid creating duplicate users.
+
+## Synchronize departments
+
+Enable **Sync departments** and enter a **Department search DN** when the LDAP directory contains a hierarchy that should be represented in NocoBase.
+
+The plugin searches organizational units below that DN, preserves their parent-child relationships, and associates users with departments based on their distinguished names. The configured Department search DN must cover the organizational units referenced by the users you expect to synchronize.
+
+## Synchronized fields
+
+### User fields
+
+User fields reuse the selected LDAP authenticator's **Attribute mapping**:
+
+| LDAP attribute or setting | NocoBase field or purpose |
+| --- | --- |
+| Login account attribute | Used as the source-unique user identifier and written to the username or email selected by the authenticator's **Use this field to bind the user** setting. This attribute is usually inferred from `{{account}}` in the authenticator's search filter, such as `uid`, `sAMAccountName`, or `mail`. A user without this attribute is skipped. |
+| Attribute mapped to `username` | Username. |
+| Attribute mapped to `nickname` | User nickname. |
+| Attribute mapped to `email` | Email address. |
+| Attribute mapped to `phone` | Phone number. |
+| `distinguishedName`, falling back to the entry DN | Finds the nearest synchronized department in the DN path and sets it as the user's primary department. This applies only when department synchronization is enabled. |
+
+For a multi-valued LDAP attribute, only the first value is currently synchronized. Other user attributes that are not included in the authenticator's attribute mapping are not synchronized.
+
+### Department fields
+
+| LDAP attribute or structure | NocoBase field or purpose |
+| --- | --- |
+| `objectGUID` | Source-unique department identifier. An organizational unit without this attribute is skipped. |
+| `ou`, `cn`, `name` | The first non-empty value in this order becomes the department name. An organizational unit without a name is skipped. |
+| `distinguishedName`, falling back to the entry DN | Identifies the current department and its parent to build the department hierarchy. |
+
+Department synchronization searches for `organizationalUnit` and `container` objects by default. It does not currently synchronize multiple user departments from attributes such as `memberOf`, or department owners.
+
+## Troubleshooting
+
+- If no users are returned, verify the authenticator's Search DN, search scope, Bind DN permissions, and the synchronization filter.
+- If the result is truncated, configure a page size and verify the LDAP server's size limits.
+- If departments are missing, verify that department synchronization is enabled and the Department search DN covers the required organizational units.
+- Review the synchronization task details and application logs for LDAP connection, bind, and search errors.