Overview
Version
| Report Server Version | Functional Change |
|---|---|
11.0 | / |
11.0.1 | Changed the default duplication verification field from Name to ID. For details, see section "User Duplication Verification Field." |
11.0.2 | For WeChat Management and DingTalk Management plugins of V11.0.54 and later versions: Added the Disable User status setting item. For details, see section "Disabling a User." WeChat and DingTalk integrated with FineReport supported user information synchronization to the platform. For details, see section "User Source." |
11.0.27 | Retained the user information configuration when you restored synchronization after deleting a synchronized user. (Namely, you do not need to configure the user information again.) |
Application Scenario
In a company with numerous employees, the user information is constantly changing due to personnel mobility. Thus, manually updating the information every time will be highly labor-intensive.
The Synchronize User function which synchronizes user data from datasets allows you to achieve dynamic updates of user information on the platform.
Function Description
The admin can create a server dataset and configure it to periodically synchronize user information from the dataset to keep user information up to date.
Notes
1. If you have started user synchronization, do not cancel the process or modify the synchronization data source without careful consideration. This is because the data related to the relationship between roles and users will not be soft-deleted and cannot be recovered.
In FineReport 11.0.27 and later versions, the user information configuration is retained when you restore synchronization after deleting a synchronized user. (Namely, you do not need to configure the user information again.)
2. For details about the precautions and error messages during user synchronization, see User Sync/Import FAQs.
User Data Preparation
The user data for synchronization comes from server datasets which support hierarchical and non-hierarchical department structures.
You can choose one type of data based on your user structure.
Departments and Positions with Non-Hierarchical Structures - SQL Dataset
This example uses a user information table where no hierarchical structures exist between departments and positions, as shown in the following figure.
1. User Information Table Preparation
Prepare a user information table. The following figure shows the table structure.
Download the user information table: Import_users1.xlsx.
Note:1. During user importing, Username, Name, and Password are required fields, and other information can be left blank.
2. Mobile supports mobile numbers in Mainland China, Taiwan (China), Hong Kong (China), Turkey, South Korea, Japan, Singapore, and Malaysia.
Mobile numbers in Mainland China do not require area codes (you can add the code if you want), while those in other regions and countries do.
3. For a user with multiple roles or of multiple departments, you can add multiple rows of data in the detail table. After synchronization, these items will be automatically merged into multiple roles for the user.
2. Server Dataset Creation
You can use a third-party database management tool to import the above table into a database and establish a data connection between the decision-making system and the database. The following takes the FRDemo database as an example.
1. Log in to the decision-making system as the admin, and choose System Management > Data Connection > Server Dataset > Create Dataset > SQL Dataset, as shown in the following figure.
Set Dataset Name to Synchronize Users1, select FRDemo as Data from Data Connection, and enter the SQL statement:
SELECT * FROM Import_users1
Departments and Positions with Non-Hierarchical Structures - File Dataset
This example uses a user information table where no hierarchical structures exist between departments and positions. The departments of the users to be synchronized are all listed under All Departments in parallel.
1. User Information Table Preparation
Prepare a user information table. The following figure shows the table structure.
Download the user information table: Import_users1.xlsx.
Note:1. During user importing, Username, Name, and Password are required fields, and other information can be left blank.
2. Mobile supports mobile numbers in Mainland China, Taiwan (China), Hong Kong (China), Turkey, South Korea, Japan, Singapore, and Malaysia.
Mobile numbers in Mainland China do not require area codes (you can add the code if you want), while those in other regions and countries do.
3. You can also use TXT/XML files. For details, see File Dataset.
2. Server Dataset Creation
Save the table locally or upload it to the report project path %FR_HOME%\webapps\webroot\WEB-INF\reportlets.
Log in to the decision-making system as the admin, and choose System Management > Data Connection > Server Dataset > Create Dataset > File Dataset, as shown in the following figure.
Set Dataset Name to Synchronize Users-File, and select the table mentioned above.
Note:1. If you select Server File, you need to select from the files in the report project path %FR_HOME%\webapps\webroot\WEB-INF\reportlets.
If you select Local File, the uploaded file will be automatically saved to the report project path %FR_HOME%\webapps\webroot\WEB-INF\reportlets\excel.
2. You can also use TXT/XML/remote URL files, which support dataset parameters. For details, see File Dataset.
Departments and Positions with Hierarchical Structures - Tree Dataset
This example uses a user information table where hierarchical structures exist between departments and positions.
1. User Information Table Preparation
Prepare a user information table. The following figure shows the table structure.
Download the user information table: Positions_with_a_Hierarchical_Structure.xls.
Note:1. When you synchronize user datasets, if the server dataset is a tree dataset, the value of the parent organization of the top-level organization should be Null (rather than an empty value). For example, the fid field for Anna is Null, as shown in the following figure.
2. You can still generate a tree dataset and synchronize users even if no users exist in a department. For example, the headquarters only has subordinate departments without direct positions or users.
3. Mobile supports mobile numbers in Mainland China, Taiwan (China), Hong Kong (China), Turkey, South Korea, Japan, Singapore, and Malaysia.
Mobile numbers in Mainland China do not require area codes (you can add the code if you want), while those in other regions and countries do.
2. SQL Dataset Creation
You can use a third-party database management tool to import the above table into a database and establish a data connection between the decision-making system and the database. The following takes the FRDemo database as an example.
1. Log in to the decision-making system as the admin, and choose System Management > Data Connection > Server Dataset > Create Dataset > SQL Dataset, as shown in the following figure.
Set Dataset Name to Synchronize Users2, select FRDemo as Data from Data Connection, and enter the SQL statement:
SELECT * FROM Positions_with_Hierarchical_Structures
3. Tree Dataset Creation
1. Log in to the decision-making system as the admin, and choose System Management > Data Connection > Server Dataset > Create Dataset > Tree Dataset, as shown in the following figure.
Set Dataset Name to Synchronize Users-Hierarchical Structures, and select Synchronize Users2 as Source Dataset. Set Creation Method to Create Tree Depending on Parent Tag Field of Selected Dataset, and select did as Original Tag Field and fid as Parent Tag Field, as shown in the following figure.
Note:
Update Settings for the First User Synchronization
Note:1. If you have synchronized users before, the pop-up window in this section will not appear, and you can skip this section.
This section introduces the data update rules for users performing an initial user synchronization or an initial user synchronization with Status set to Disabled.
2. The synchronized users can coexist with manually added/imported users.
Log in to the decision-making system as the admin, choose System Management > User Management > All Users, and click Synchronize User.
A prompt box displaying "Sure to retain existing asynchronous data, including imported/added users, departments, positions, and roles?" will pop up, as shown in the following figure.
The following table describes the update logic for different options.
| Option | Definition |
|---|---|
Retain | If the existing user is not in the synchronized server dataset, the user's information and permissions will be retained without modification. If the existing user (with the same username) is in the server dataset:
|
Clear | All the usernames, names, passwords, mobiles, mailboxes, departments, positions, roles, and permissions of manually added/imported users on the platform will be deleted. Users need to be resynchronized. |
Note:Based on the selected update logic, some user information is updated after the initial synchronization.
Only users changed to the synchronous type can be automatically updated in the later synchronization.
The dataset cannot overwrite and update built-in data in the later synchronization, otherwise errors will be reported.
User Synchronization Configuration
Configure information of the synchronized dataset, as shown in the following figure.
Synchronization Frequency
You can set Sync Frequency to Fixed Interval or Expression Setting.
1. Fixed Interval
If you select Fixed Interval, the fixed interval of automatic user synchronization from the server dataset is 43,200 seconds by default.
After you set the synchronization frequency for user synchronization, multiple synchronizations can be automatically performed when the set frequency is reached, continuously updating the platform with any changes from the server dataset.
Note:
If you select Expression Setting, you can set the execution time of a task through the Cron expression. The task can be executed based on various triggering frequencies such as every day, every two days, or only once.
For details about the Cron Expression, see Cron Expression.
User Editability
User Info Editable in Sync Status is deselected by default. When it is selected, user information can be edited in the synchronous status.
Users can edit their names, passwords, mobiles, and mailboxes. The Forgot Password function is available. For existing users, the above fields will no longer be updated during automatic/manual synchronization. The following table shows the specific function.
Note:1. Password policy setting takes effect for synchronized users.
2. If you use the Forgot Password function when you deselect User Info Editable in Sync Status, a prompt displaying "Your password cannot be changed. Please contact the administrator." will pop up when you modify the password.
| User Role | Description |
|---|---|
Super admin | 1. During resynchronization, the Name, Password, Mobile, and Mailbox fields of existing users on the platform will no longer be updated. 2. The super admin can edit the names, mobiles, mailboxes, and passwords of existing users on the platform, but cannot edit the synchronized roles. 3. The super admin can edit the name, password, mobile, and mailbox in Account Setting. 4. The super admin can use the Forgot Password function on the login page. |
Subordinate admin | 1. The subordinate admin can modify the names, mobiles, mailboxes, and passwords of users on which the subordinate has permissions, but cannot edit the roles of these users. 2. The subordinate admin can use the Forgot Password function on the login page. 3. The subordinate admin can edit the name, password, mobile, and mailbox in Account Setting. |
Ordinary user | 1. Synchronized users can edit the name, password, mobile, and mailbox in Account Setting. 2. The ordinary user can use the Forgot Password function on the login page. |
User Source
Select the corresponding source of the user information.
1. Server Dataset
The source of synchronized users can be the current server dataset being synchronized. Simultaneous synchronization from multiple server datasets is not supported. When you switch the server dataset, the previously synchronized information will be cleared.
After successful synchronization, the department, position, and role of synchronized users can only be modified in the server dataset.
2. Synchronization from the LDAP Server
If you select LDAP Authentication as Authentication Method for Synchronized User, you can directly select Synchronize from LDAP Server during user synchronization after you installed the Synchronizing Users from the LDAP Domain plugin.
For details, see Synchronize LDAP Domain User.
3. Sync from WeCom
After configuring Member Management under System Management > WeChat Management, you can select Sync from WeCom as User Source. Select the WeChat APP to be synchronized, and click OK.
Note:1. Choose WeChat Management > Member Management, click Update or set auto update in WeChat Contacts to synchronize users.
2. Due to the constraints of WeCom APIs, the passwords cannot be synchronized and the initial passwords for report users are randomly generated. If you want to log in to the platform through the account and password on the DataAnalyst app or PC, you need to click Forgot Password, and reset a password for login.
4. Sync from DingTalk
After configuring Member Management under System Management > WeChat Management, you can select Sync from DingTalk as User Source. Select the DingTalk APP to be synchronized, and click OK.
Note:
5. Sync from Lark
In FineReport designer V11.0.10 and later versions with the Lark Management plugin V11.0.75 and later versions, user information from the Lark Contacts can be synchronized to the User Management page and stored on the platform.
Choose Lark Management > Member Management, click Update or set auto update in Lark Contacts to synchronize users.
User Duplication Verification Field
To prevent the occurrence of users or job titles with the same name across different departments, FineReport provides the User Duplicate Verification Field function.
Two verification methods are available, namely User ID and Username.
Note:In FineReport versions earlier than 11.0.1, the default field for duplicate verification was Username.
In FineReport 11.0.1 and later versions, the default field for duplicate verification is User ID.
1. Storage Location of User Information
| Field | Table |
|---|---|
User ID, Username | fine_user |
Job ID, Position Name | fine_post |
Department ID, Dept. Name | fine_department |
Role ID, Role Name | fine_custom_role |
2. Description
| User Duplicate Verification Field | Logic | Scenario | Note |
|---|---|---|---|
User ID Department ID Job ID Role ID | If you select ID, both ID and name fields will be synchronized. The value of the ID field in the corresponding table is the ID in the server dataset during user synchronization. | If the username corresponding to a certain ID in the dataset is modified, the username on the platform will also be modified accordingly, and the permissions will be inherited. The same applies to the department, position, and role. | In non-tree datasets, if you select ID as the duplicate verification field, the ID and name of a position need to be a unique one-to-one relationship that is not repeated. One ID to correspond to multiple names or one name to correspond to multiple IDs is not allowed. The same applies to the user, department, and role. In tree datasets, the name and ID of users, positions, and roles need to form a unique one-to-one relationship that is not repeated. Note: |
Username Department Name Position Name Role Name | If you select the name, the name field will be synchronized. The ID field in the corresponding table will be randomly generated by the system. | If you modify the username of a user in the dataset, the username on the platform will also be modified accordingly. The corresponding user ID will be randomly generated by the system. The user with the new username will lose the previous permissions configured separately. The same applies to departments, positions, and roles, which will lose the permissions inherited from their departments, positions, and roles. | If you select Position Name as the duplicate verification field, the positions with the same name but different IDs in the data source will be treated as one position. For example, if two different positions coexist with the name Finance in the same department, the positions will be displayed as a single position and the users of them will be merged together. If the two Finance positions belong to different departments, the positions will still be treated as a single position. However, due to different department-position relationships, the users of them will not be merged together. The same applies to the user, department, and role. |
Field Name
Username, Name, Password, Department Name, Position Name, Role Name, Mobile, and Mailbox are the field names in the corresponding server dataset.
Note:1. Mailbox can include symbols # and &.
2. You can configure departments but cannot configure positions.
Encryption Method Setting
You can encrypt the user passwords stored in the FineDB configuration database in the system. The above operations can ensure that the user's actual login information cannot be obtained even if the database is decrypted.
You can select Built-in SHA Encryption or Custom Password Encryption from the drop-down list of Encryption Method.
1. Built-in SHA Encryption
Application scenarios: Select Built-in SHA Encryption when the password in the synchronized server dataset is in plaintext.
Encryption description: The decision-making platform applies the SHA256 encryption to ensure password security. After you customize a password through an API, the password will be automatically encrypted using SHA256.
Login password: The login password is the password in the above downloaded user Information table, and not the encrypted password in the fine_user table.
2. Custom Password Encryption
Application scenarios: Custom Password Encryption must be used when the password in the synchronized server dataset is a custom encrypted ciphertext.
Encryption description: Customize a password encryption class.
The encryption method is described in the class and saved in the classes folder in %BI_Home%\webapps\webroot\WEB-INF.
The decision-making system will perform a second SHA256 encryption based on the user's custom encryption algorithm to ensure the password security.
Login password: The login password refers to the plaintext obtained after the ciphertext in the server dataset is decrypted.
For details about custom encryption examples, see Password Encryption Settings for Synchronized Users.
Note:1. Custom encryption algorithms need to inherit the AbstractPasswordValidator class.
2. If you select User Info Editable in Sync Status, set an encryption method, and click OK, the ciphertext in FineDB cannot be updated and users will be unable to log in when you change the encryption method again.
3. After modifying the encryption method for users to be synchronized, you do not need to restart the project since the changes will take effect immediately.
Disabling a User
In FineReport 11.0.2 and later versions, the Disable User setting (optional) has been added, facilitating administrators to manage user status through user data synchronization.
If you need to use this setting, add a new field in the data source in the section "User Data Preparation" with the value of 0 or 1.
0: Disable the user.
1: Enable the user.
1. If you do not configure this setting, you can manually select Enable Users or Disable User on the platform.
2. If you configure the setting, selecting Enable Users or Disable User is entirely dependent on the data source. Manual configuration is not supported on the platform.
Note:
User Sync Management
After synchronization, four drop-down options will be added to the Manage User Sync button.
Immediate Synchronization
Click Sync Now to immediately synchronize the user dataset.
Note:Edition
Click Edit to enter the Synchronize User dialog box. You can modify the configuration of the synchronized user dataset.
Switch user sources carefully, which will result in the clearance of previously synchronized users and their departments, positions, roles, and permissions. If you switch the user source dataset for synchronization, when you click OK, a prompt displaying "After the dataset is switched, the original synchronized data will be cleared, including users and their departments, positions, roles, permissions, etc. Confirm to switch the dataset?" will pop up.
If you deselect User Info Editable in Sync Status in section "User Editability", the admins can set Disable User, add/delete/modify Dept.-Posit. and Role in the Edit User setting box, but cannot delete users. (Dept.-Posit. and Role are not to be synchronized.)
If you select User Info Editable in Sync Status in section "User Editability", the admins can edit users and set Disable User, but cannot delete users.
Synchronized Data Clearance
You can click the Clear Sync Data button to cancel synchronized users. The user synchronization will be cancelled.
Clearing synchronization data will delete all synchronized users, departments, positions, roles, and related permissions, and discontinue synchronization. The system will no longer restore to the unsynchronized status.
Sync Upon Data Exception Discontinuation
User synchronization is highly dependent on the data source. If the data source is faulty (for example, malicious clearance of database tables), the users synchronized to the system will be cleared, which cannot be restored.
Therefore, FineReport added the Discontinue Sync Upon Data Exception button.
After the administrator enables Discontinue Sync Upon Data Exception, the percentage (X%) of reduced users can be set to trigger synchronization cessation. X is a positive integer ranging from 1 to 100.
For example, if there are originally 100 synchronized users in the system (excluding manually added/imported users), set the percentage to 30%, then synchronization will be stopped if 30 (100 * 30%) or more users are reduced during synchronization.
If the synchronization fails, a prompt will be displayed, as shown in the following figure.
Failure Reason: 21300031 - Synced users will be reduced by 67% (6), reaching the set value 30% for triggering sync interruption. Check whether the data from the data source is normal, or temporarily disable Discontinue Sync Upon Data Exception.
Next Sync Time
The system will remind admins of the next automatic synchronization time based on Sync Frequency set in section "Synchronization Frequency."
Sync Failure Reminder
During user synchronization, errors may occur due to conflicts, resulting in partial or complete failure to synchronize user, department, position, and role data, which can lead to outdated permissions.
In the above situations, you need to notify the corresponding admins timely. Therefore, FineReport provides the sync failure reminder function.
Setting Method
Log in to the decision-making platform as the super admin, choose System Management > User Management > Global Setting, configure the recipient of the sync failure reminder, and click Save, as shown in the following figure.
Note:1. To remind users by SMS, click Enable SMS Function to enable the SMS service first. For details, see SMS Service.
2. To remind users by emails, click Enable Email and configure email settings first. For details, see Email Service.
Effect Display
After the first manual or automatic synchronization failure, the system will send an SMS, email, or platform reminder to the admin. The system will continue to send reminders upon later synchronization failure until the next successful synchronization.
Note:If multiple consecutive synchronization failures occur, the reminder message will only be sent for the first failure.
The reminder monitoring status will be reset only when the synchronization is successfully performed, the system is restarted, or the synchronized users are disabled.
After that, if there is another synchronization failure, reminders will be sent again.
1. SMS Reminder
2. Platform Message
3. Email Notification
