Skip to main content

Account Synchronization Practical Operation

Setup Path: Administrator Settings — User Management — Account Synchronization (If not enabled, contact Guandata staff to enable)

Update Method: Manual trigger, scheduled tasks

I. User Group Synchronization

1. Prepare User Group Dataset

Need to include the following 3 fields (refer to the figure below):

  1. User Group ID: STRING type, this ID is just a unique identifier ID for external user groups, not the user group ID in BI. Cannot be empty and cannot be duplicated (empty records will be ignored, duplicate records will take the last record as standard)

  2. Name: STRING type, cannot be empty (empty records will be ignored)

  3. Parent User Group ID: STRING type. Correct example as shown in the figure below:

image.png

Note: Don't have parent user group IDs that depend on each other, such as A's parent user group is B, B's parent user group is A. The figure below is an error example, must be avoided

image.png

2. Set User Group Synchronization, Associate Fields

Effect after synchronization as follows.

image.png

Note:

  1. If this user group and its descendant user groups still have some resources as owners, they cannot be deleted.

  2. If system synchronized user A belongs to user group a (manually created user group in BI), user group b (from system synchronization), then when system synchronizes user A next time, user group a will still exist.

II. Account Synchronization

1. Dataset Preparation

Ensure all user attributes to be synchronized are in the dataset, and stored in string text format. If multiple user attributes are distributed in different datasets (or wrong format), it's recommended to use ETL to process data, belonging to a dataset specifically for account synchronization. Already existing account information can be queried in the builtin_user dataset in the Built-in-Dataset folder in the data center, user group information is stored in the user_and_user_group_relation_record table.

image.png

2. Set Dataset Synchronization, Associate Fields

Enter the "Account Synchronization" edit interface, under the user synchronization tab, click "Select Dataset", select the prepared dataset.

Synchronizable fields are divided into 4 categories: basic information, permission information, third-party account association, and other information. Except for password and user status, other attributes can only be associated with corresponding fields from the dataset selected in the previous step according to needs, for fields that don't need synchronization, keep matching field empty, finally save.

image.png

Field Explanation

A. Account: Cannot be empty and must ensure uniqueness (empty records will be ignored)

B. Password: Only effective when creating users for the first time, will not be updated with dataset updates later. If modification is needed, it can be manually modified in administrator settings. If choosing to match with dataset field, password field is required, password field must be encoded with Base64; if using unified initial password, it means all new users created through account synchronization have the same password, there may be data security risks, it's recommended to set complex passwords and set password policies (path: System Management - Login Settings. Please refer to Guandata BI Account Security and Login Settings). Guandata BI doesn't support batch password modification, but has corresponding API interface (batch modify user attributes: POST /public-api/users/modify) for users to develop secondary development to achieve batch password modification.

C. User Status: Divided into enabled/disabled, when choosing to set unified initial value, it will only be effective when creating users for the first time, later modifications can be manually modified in administrator settings; if "Match with dataset field" is selected and field is selected (lowercase English: disable for disabled, lowercase English: enabled or empty for enabled), then status will follow dataset synchronization later.

D. Account Type: Role must be in English (admin/editor/participant), if field value is empty, newly added users will all be read-only accounts by default; only effective when creating users for the first time, will not be updated with dataset updates later, modifications can be manually modified in administrator settings.

E. Belonging User Group ID: Not required, can be empty, if empty the user will not be added to any user group, multiple user groups use English comma ',' to separate; cannot use user group names, can only use user group IDs (external user group IDs in user group synchronization dataset, not user group IDs in BI).

F. Third-party Account Association: After matching dataset fields, supports SSO login account/LDAP login account automatic synchronization. There will be null checking and duplicate verification. But note that this function perfectly supports Guandata's built-in standard SSO integration method, not applicable to other methods or custom-developed single sign-on methods. For example, SSO login account is email, but BI login account is employee number, then you need to first ensure the user email attribute has value, then set SSO login account to associate with the email field in the dataset.

image.png

Synchronization Main Process

● First synchronize user groups, then synchronize users (because of dependency relationship);

● The general process is to get new user (group) information, compare with old user (group) information, or delete/add/update data, handle separately. Refer to the flow chart below.

image.png

Task Management:

1. When submitting tasks, check if there are account synchronization tasks running, if yes then cannot submit.

  1. After synchronization, you can see the running status on the current page, and you can view update history records in the upper right corner. History records will indicate whether it's all failed or partially failed, click "Details" on failed fields to view failure reasons and list. The most common failure reason is that users have untransferred resources causing user deletion failure.

image.png

Notes

  • It's recommended to set "Whether to disable user deletion operations" to "Yes" (after enabling, users will only be disabled, not directly deleted, can be batch re-enabled or cleaned up. Used to alleviate the impact when users are accidentally deleted)

image.png

  • User group cache will be refreshed after all user groups are synchronized (otherwise there are performance issues).

  • User/user group synchronization updates are compared with last synchronization data. Only new/update/delete/disable users (groups) in the dataset, including manually added but later appeared in account synchronization.

  • If the configured dataset is reset, then all synchronized users (groups) will be deleted during synchronization.

  • Users in the user synchronization dataset will be marked with "System Synchronization" label after synchronization. When dataset account is the same as manually created user account in BI, the user synchronization dataset will overwrite and update manually created users, and mark with "System Synchronization" label.

  • When there are accounts with the same data rows in the user synchronization dataset, those accounts will fail to update; when there are data rows with the same email/phone number in the user synchronization dataset, those accounts will fail to add.

  • When there are accounts in the user synchronization dataset that are different from manually created user accounts in BI, but have the same phone number/email, then the accounts in the user synchronization dataset will be added as new accounts. (Version 6.5 effective)

  • In versions before 6.5, when phone numbers or emails are the same, exceptions and errors will be prompted.

Accounts created through API, if not put into synchronization dataset, won't be marked with system synchronization label, won't be affected by account synchronization; after adding these accounts to synchronization dataset through ETL, they will be affected by account synchronization.

Q&A

  • Manually created accounts are not standardized, how to use account synchronization for batch automatic updates and deletions?

Answer: When creating user synchronization dataset with ETL, perform full association or concatenation of built-in dataset builtin_user and external user dataset (such as DingTalk user dataset), so that all manually created accounts exist in the synchronization dataset. After synchronization is complete, all accounts will be marked with "System Synchronization" label, and user attributes will be batch updated according to dataset later; re-modify ETL, set filter conditions to filter out non-standard accounts (or resigned accounts), after synchronization again, non-standard accounts (or resigned accounts) will be batch deleted or disabled.