I. Overview
1. Version
| Report server version | JAR | Function changes |
|---|---|---|
| 10.0 | - | - |
| 10.0 | 2019-12-05 | "Mailbox" supports the symbols # and & |
| 10.0 | 2020-06-08 | Added user editable options, after checking, user information can be edited in the synchronized state.After checking, the synchronized user can edit the name, password, mobile phone, email, and use the forget password function. The above fields of existing users will no longer be updated during regular synchronization.For details, please refer to section IV.2 of this article |
| 10.0.10 | - | Supports multi-source users, can "synchronize users" when adding/importing users, and multiple types of users on the platform can coexist. |
| 10.0.11 | - | Timing synchronization frequency supports the use of expressions. |
| 10.0.12 | - | Support using "File Dataset" to synchronize users The user's mobile phone number supports the binding of mobile phone numbers in China, Taiwan China, Hong Kong China, Turkey, South Korea, Japan, Singapore, and Malaysia. |
| 10.0.14 | - | Section V.3, support to clear the synchronization data When synchronizing users, support only the department can be configured, not the job title. |
| 10.0.17 | - | Chapter VI., "Sync Failure Reminder" is added |
| 10.0.18 | - | Section V.4, add "abnormal data interrupt synchronization" |
| 10.0.19 | 2021-10-14 | Section IV.3, the "Server Dataset" configuration is renamed to "User Source" |
2. Application scenarios
The number of employees in an enterprise is quite large, and due to the mobility of personnel, user information is always changing. If you manually add and modify each time, the workload will be very large.
The FineReport user synchronization dataset function can dynamically update the user information in the platform so that it changes with the user information in the database.
3. Function introduction
The administrator can first create a server dataset, set to synchronize users from the dataset regularly, and keep user information updated in a timely manner.
4. Matters needing attention
1) If the synchronization user is set, please do not easily cancel the synchronization/adjust the synchronization data source. Because the relationship data between role users will not be soft deleted and cannot be restored! ! !
2) For some precautions and errors when synchronizing users, please refer to: Error reporting when synchronizing users
II. Prepare User Data
Synchronized user data comes from the server dataset, and supports user departments with hierarchical and non-hierarchical.
Users can choose one of them according to their own user structure.
1. Non-hierarchical structure between department positions-SQL dataset
The user information table used in the example in this section has no hierarchical structure among departments, as shown in the following figure:
1)Prepare user information table
Prepare a user information table, the table structure is as shown in the figure below:
Click to download the user information sheet:
Note 1: When importing users, the user name, name, and password are required, and the content can be left blank.
Note 2: Report project versions prior to 10.0.12 only support binding to mobile phone numbers in Mainland China, without the area code.
10.0.12 and later version of the report project, the user mobile phone number can be bound to the mobile phone number of China, Taiwan China, Hong Kong China, Turkey, South Korea, Japan, Singapore, Malaysia.
You can choose whether to add an area code to your mobile phone numbers in mainland China, and you need to add an area code to mobile numbers in other regions.
2)Create Server Dataset
Use a third-party tool such as Navicat to import the above table into the database and establish a data connection between the system and the database. The following will take the FRDemo database as an example.
The administrator logs in to the decision-making platform and clicks Manage>Data Connection>Server Dataset to create a SQL Dataset. As shown below:
Set the dataset name to Synchronized User 1, select FRDemo for the data connection, and the SQL statement as:
select * from Import_user1
2. No hierarchical structure between department posts-file dataset
Note: 10.0.12 and later report projects support user synchronization through "File Dataset".
The user information table used in the example in this section has no hierarchical structure among departments. The departments of the synchronized users are all listed under "All departments", as shown in the figure below:
1)Prepare user information table
Prepare a user information table, the table structure is as shown in the figure below:
Click to download the user information sheet:
Note 1: When importing users, the user name, name, and password are required, and the content can be left blank.
Note 2: Report project versions prior to 10.0.12 only support binding to mobile phone numbers in Mainland China, without the area code
10.0.12 and later version of the report project, the user mobile phone number can be bound to the mobile phone number of China, Taiwan, Hong Kong, Turkey, South Korea, Japan, Singapore, Malaysia.
You can choose whether to add an area code to your mobile phone numbers in mainland China, and you need to add an area code to mobile numbers in other regions.
Note 3: TXT / XML files can also be used, please refer to the file dataset for the setting method.
2)Create Server Dataset
Save the table locally or upload it to the %FR_HOME%\webapps\webroot\WEB-INF\reportlets directory of the report project.
The administrator logs in to the decision-making platform and clicks Manage> Data Connection> Server Dataset to create a File Dataset. As shown below:
Set the data set name to "Sync User-File", and select the form prepared above.
Note 1: If you select the server file, select the file in the %FR_HOME%\webapps\webroot\WEB-INF\reportlets directory of the report project.
If you select a local file, the file will be automatically saved to the %FR_HOME%\webapps\webroot\WEB-INF\reportlets\excel directory of the report project after uploading.
Note 2: TXT/XML/remote URL files can also be used, and data set parameters are supported. For the setting method, please refer to: file dataset.
3. There is a hierarchical structure between department positions-tree dataset
The user information table used in the example in this section has a hierarchical structure among departments, as shown in the following figure:
1)Prepare user information table
Prepare a user information table, the table structure is as shown in the figure below:
Click to download the user information table:
Have_a_hierarchical_structure.xls
Note 1: When synchronizing user datasets, if the server dataset is a tree dataset, the parent organization of the top organization should be a null value. For the Anna user as shown in the figure below, the fid field is empty.
Note 2: Report project versions prior to 10.0.12 only support binding to mobile phone numbers in Mainland China, without the area code
10.0.12 and later version of the report project, the user mobile phone number can be bound to the mobile phone number of China, Taiwan, Hong Kong, Turkey, South Korea, Japan, Singapore, Malaysia
You can choose whether to add an area code to your mobile phone numbers in mainland China, and you need to add an area code to mobile numbers in other regions.
2)Create SQL Dataset
Use a third-party tool such as Navicat to import the above table into the database and establish a data connection between the system and the database. The following will take the FRDemo database as an example.
The administrator logs in to the data decision system and clicks Manage>Data Connection>Server Dataset to create a SQL Dataset. As shown below:
Set the data set name to Sync User 2, select FRDemo for the data connection, and the SQL statement as:
select*from Have_a_hierarchical_structure
3)Create a tree dataset
The administrator logs in to the decision-making platform and clicks Manage>Data Connection>Server Dataset to create a Tree Dataset. As shown below:
Set the dataset name to Synchronized User-Hierarchical, constructed from the dataset Sync User 2, the original tag field is did, and the parent tag field is fid, as shown in the following figure:
III. Synchronize for the first time
Note 1: This chapter applies to data update rules for users who have never synchronized data before and users who perform the first synchronization when they are not enabled.
If users have been synchronized before, a pop-up dialog box will not be displayed and synchronization will not be performed according to the update rules in this section.
Note 2: JAR package version before 2020-11-02, synchronized users and "manually add/import users" can not coexist.
JAR package version in 2020-11-02 and later projects, synchronous users and "manually add/import users" can coexist.
1. Version before 2020-11-02
Admin logs into the platform, click Manage > User Management > All Users and click [Synchronize users].
Pop up the User Update Setting prompt box, as shown in the figure below:
The update logic corresponding to different choices is as follows:
| Selection | Logic |
|---|---|
| Update only existing user basic information, do not change permissions, etc. | If existing user is not in the sync dataset, this user will be deleted. If existing user is also in the sync dataset (with the same username):
|
| Clear existing user information and permissions settings, rewrite | All existing user information and permission is deleted first. Users will be synchronized all from the sync dataset. Existing roles not in the sync dataset will be retained. |
Note: According to the selected update logic, some user information is updated after the first synchronization.
Only users who have changed to the synchronous type can then be automatically updated.
After the synchronization, the dataset can no longer overwrite the update built-in data, otherwise the conflict will report an error.
2. Version of 2020-11-02 and after
Admin logs into the platform, click [Manage > User Management > All Users] and click [Synchronize users].
The prompt box Keep the existing data unsynchronized or not, including imported/added users, department titles, and roles pops up, as shown in the following figure:
The update logic corresponding to different choices is as follows:
| Selection | Logic |
|---|---|
| Reserve | If existing user is not in the sync dataset, this user and permissions will be retained. If existing user is also in the sync dataset (with the same username):
|
| Clear | All existing user information, dept-position role, and permission are deleted first. Users will be synchronized all from the sync dataset. |
Note: According to the selected update logic, some user information is updated after the first synchronization.
Only users who have changed to the synchronous type can then be automatically updated.
After the synchronization, the data set can no longer overwrite the update built-in data, otherwise the conflict will report an error.
IV. Configure Sync Users
Configure the synchronization data set information, as shown in the following figure:
1. Sync frequency
Projects with versions before 10.0.11 support simple repeat execution of synchronized user operations.
Projects with version 10.0.11 and later support simultaneous user operations in two ways: simple repeat execution and expression setting.
1)Simple repeat execution
The interval time for automatically synchronizing users from the server dataset, the default is 43200 seconds.
The synchronization user has set the synchronization frequency, which can automatically synchronize multiple times, and automatically synchronize after reaching the set frequency, and continuously synchronize the changed data of the server data to the platform.
Note: The synchronization frequency should not be too high, otherwise the background log will be constantly refreshed and the log volume will expand indefinitely.
2)Expression setting
Supports setting the time point of task execution through Cron expressions. The task can be repeated every day, every other day, or a single execution, and other trigger time points of various combinations.
2. User Editable
2020-06-08 and later JARs have added a Editable button. This button is not checked by default. After it is checked, the user information can be edited in the synchronized state.
The user can edit the name, password, mobile phone, email, and use the forgot password function. The above fields of existing users will no longer be updated during automatic/manual synchronization. The specific functions are shown in the table below:
Note 1: For systems where the JAR package version is between 2020-06-08 and 2020-11-02, after the user is synchronized, the password policy function is not effective for the synchronized user, except for the forgot password function.
For systems whose JAR package version is 2020-11-02 and later, the password policy function is effective for synchronized users.
Note 2: If the Editable button is not checked, but the forgot password function is used, a prompt will appear when changing the password: Your account cannot change the password. If you have any questions, please contact the administrator.
| User | Description |
|---|---|
Super administrator | 1) When synchronization is conducted once again, the name, password, mobile and mailbox of an existing user on the platform will not be updated. 2) The name, mobile, mailbox and password of an existing user are editable. Role is not editable. 3) A super administrator can edit his name, password, mobile and mailbox under [Account Setting]. 4) The forget-password function is available on the login page. |
Sub-administrator | 1) A sub-administrator can modify the name, mobile, mailbox and password of an authorized user, but cannot edit the role. 2) The forget-password function is available on the login page. 3) A sub-administrator can edit his name, password, mobile and password under [Account Setting]. |
User | 1) A synchronized user can edit his name, password, mobile and mailbox under [Account Setting]. 2) The forget-password function is available on the login page. |
If it is unchecked, then relevant user information, such as password, mobile and mailbox, cannot be directly modified on the platform, and can only be altered in the server dataset.
3. User source
Select the source corresponding to the user information.
1)Server dataset
The source of the synchronized user can be the currently synchronized server dataset. Simultaneous synchronization from multiple server datasets is not supported. After switching the server dataset, clear the previous synchronization information.
After the synchronization is successful, it is not supported to modify the synchronization department's job title and synchronization role information to which the synchronized user belongs, and can only be modified in the server dataset.
2)Synchronize from the LDAP server
If LDAP authentication is selected for the authentication method of the synchronized user, by installing the "Synchronize LDAP Domain User" plugin, you can directly select Synchronize from LDAP Server when setting up the synchronized user.
4. User repeated verification field
Duplicate verification field contains two verification methods: name and ID.
1)User information storage location
Note: User information is stored in a table in the FineDB database.
| Field information | Database-table |
|---|---|
| Username,user ID | fine_user |
| Position name,position ID | fine_post |
| Department name,department ID | fine_departament |
| Role name,role ID | fine_custom_role |
2)Specific instructions
| Duplicate verification field | Synchronization logic | Modification logic | Duplication logic | |
|---|---|---|---|---|
| Name | Userame | 1. Synchronize the field corresponding to [Name]. 2. The corresponding ID field will be generated randomly by the system. | 1. If the username of a user in the dataset is modified, then the username on the platform will be modified accordingly. As the corresponding user ID is generally randomly by the system, permissions configured separately for the user will be lost. 2. Similarly, if name is selected as the department/position/role duplicate verification field, then permissions inherited from the department/position/role will be lost after the name is modified. | 1. If the duplicate verification field is position name, then positions with the same name but different IDs in the data source will be deemed as a single position. If there are two different positions named [Finance] in a department, they will be displayed as a single position and users under the two positions will be merged. 2. However, if the two [Finance] positions are in different departments, the two positions will be deemed as a single position, but users under them will not be merged due to the difference in department-position relationship. 3. It is the same case with user, department or role. |
Department name | ||||
Position name | ||||
Role name | ||||
| ID | User ID | 1. Synchronize the fields corresponding to [ID] + [Name]. 2. The corresponding ID field value is the ID in the bound server dataset. Note: a super administration’s ID will be generated by the system. | If the username corresponding to an ID in the dataset is modified, then the username on the platform will also be changed, but permissions will be inherited. It is the same case with department, position or role. | 1. In a non-tree dataset, position ID and name must be one-to-one without repetition: an ID corresponding to multiple names or a name corresponding to multiple IDs is not allowed. It is the same case with user, department or role. 2. In a tree dataset, user/position/role name and ID must be one-to-one without repetition. Department data is not so required. Note: no position ID can be seen in foreground, and permissions are distinguished or configured through position names. If two different position IDs in a department are corresponding to the same name, permissions cannot be distinguished or configured. |
Department ID | ||||
Position ID | ||||
Role ID | ||||
5. Field name
Username, Name, Password, Dept., Position, Role, Mobile, and Mailox are the field names in the corresponding server dataset.
Note 1: For jar that 2019-12-05 and later, mailbox support the symbols' # 'and' & '.
Note 2: In the report project of version 10.0.14 and later, only department can be configured, but position cannot be configured.
Report project before version 10.0.14, if you wanna configure the department, you must configure the position.
6. Encryption Methods
There are two encryption methods, "built-in SHA encryption" and "custom password encryption".
1)Built-in SHA encryption
Applicable scenario: When the password in the synchronized server dataset is in plain text, select the built-in SHA encryption
Encryption introduction: The decision-making platform uses SHA256 encryption to ensure password security. After the user customizes the password through the interface, it will automatically perform SHA256 encryption.
Login password: The login password is the password in the user information table in section II.1. of this article, and the encrypted password in the non fine_user user table.
2)Custom password encryption
Applicable scenario: The password in the synchronized server dataset is a ciphertext after custom encryption, and you must use custom encryption.
Encryption introduction: Custom password encryption, that is, customize a password encryption class.
The encryption method is described in the class and saved in the %BI_Home%\webapps\webroot\WEB-INF\classes folder.
The decision-making platform will perform SHA256 secondary encryption on the basis of the user-defined encryption algorithm to ensure password security.
Login password: The login password is the plaintext after decrypting the ciphertext of the server data set
Note 1: For details of custom encryption examples, see: Password Encryption for Simple Permissions.
Note 2: The custom encryption algorithm must inherit the AbstractPasswordValidator class and add a return method to determine whether the plaintext password and the ciphertext password are consistent.
Note 3: If the Editablen is checked and the encryption method is set, after the save is successful, change the encryption method again, the cipher text in FineDB cannot be changed synchronously, and the user will not be able to log in successfully.
Note 4: After modifying the synchronization user encryption method, there is no need to restart the project, and it will take effect immediately.
V. Synchronized user management
After the synchronization is complete, there will be multiple drop-down options at the synchronization user management button, as shown in the following figure:
1. Sync now
Once clicked, a user dataset synchronization will be performed immediately.
2. Edit
Open the synchronization user dialog box, you can modify the synchronization user dataset configuration.
If the Editable setting in section IV.2. is not enabled, the administrator disable user is supported, but edit user and delete user are not supported.
If the Editable setting in section IV.2. is enabled, the administrator disable user and edit user are supported, but delete user is not supported.
3. Clear sync data
For projects where the JAR package version is 2021-03-17 and later, a Clear Sync Data button is added to support one-click cancellation of sync users.
Clearing the synchronization data will delete all synchronized users, department titles, roles, and related permissions, and will no longer continue to synchronize, and restore the unsynchronized state.
For projects whose JAR package version is between 2020-11-02 and 2021-03-17, synchronized users and "manually added/imported users" can coexist.
It is not supported to cancel the synchronization of users directly, but you can switch the server dataset synchronized in section IV.2. to an empty dataset.
For projects with a JAR package version before 2020-11-02, synchronized users and "manually added/imported users" cannot coexist.
If you need to cancel the synchronization of users, perform the "Add User" or "Import User" operation to cancel the synchronization of users.
4. Abnormal data interrupts sync
Synchronized users are highly dependent on the data source. If there is a problem with the data source, for example, a database table is maliciously emptied, the users synchronized to the system will be emptied, and the operation cannot be reversed.
Therefore, FineReport provides a synchronous fusing strategy. For report projects of 10.0.18 and later versions, the button "Abonormal fata interrupts sync" is added.
After the administrator turns on "Abonormal fata interrupts sync", the number of users can be reduced by X% to stop the synchronization. X is a positive integer from 1-100.
For example, the original 100 synchronized users in the system (not including the number of manually added/imported users) are set to 30%, that is, if the synchronization is reduced by 30 (100*30%) users or more, the synchronization will be stopped.
The reminder of synchronization failure is shown in the figure below:
Failure reminder:
21300031-The number of synchronized users this time will be reduced by XX% (XX), reaching the set interrupt value XX%. Please check whether the data source data is normal, or temporarily turn off the "abnormal data interrupt synchronization" function.
5. Next synchronization time
The system will remind the administrator of the next automatic synchronization time according to the "Sync Frequency" set in Section IV.1..
VI. Sync failure reminder
In the process of synchronizing users, there may be errors due to conflicts, causing some or all of the users, departments, positions, and roles to fail to synchronize data, and the permissions will not be updated.
The above situation needs to be notified to the corresponding administrator in time. Therefore, for the projects of 10.0.17 and later versions, the "Sync Failure Reminder" function is added.
1. Setting method
The administrator logs in to the data decision system, clicks "Management System>User Management>Global Settings", configures the recipients of the notification push notification of synchronization failure, and clicks "Save", as shown in the following figure:
Note 1: Before using SMS reminder, you need to activate the SMS service. Please refer to the document: SMS
Note 2: Before using email reminders, you need to configure your email address. For specific steps, please refer to: Email.
The system will send a SMS/email/platform reminder to the administrator after the "first" manual synchronization/automatic synchronization fails. The reminder will not be sent again until the next synchronization is successful, and then the synchronization fails.
Note: If the synchronization fails several times, the reminder message will only be sent in the "first synchronization failed".
The reminder monitoring status will not be reset until the situation of "Synchronization Successful/Restart Project/Close Synchronized User" appears.
After the synchronization fails again, the reminder will be sent again.
2. Effect preview
The system will send a SMS/email/platform reminder to the administrator after the "first" manual synchronization/automatic synchronization fails. The reminder will not be sent again until the next synchronization is successful, and then the synchronization fails.
Note: If the synchronization fails several times, the reminder message will only be sent in the "first synchronization failed".
The reminder monitoring status will not be reset until the situation of "Synchronization Successful/Restart Project/Close Synchronized User" appears.
After the synchronization fails again, the reminder will be sent again.
1)SMS reminder
2)Platform reminder
3)Mail reminder
