Migrate users and qualifications from previous platform versions
A migration tool is available as part of the platform installer, enabling you to seamlessly migrate users, groups, qualifications, roles, and related mappings.
How it works
The migration tool completes user migration automatically in the course of upgrading. The figure below illustrates the interactions of the tool with Work.AI components.
The underlying migration flow is as follows:
- Data is obtained from CT and Workspace (WS) databases.
- The data is converted into a proper format for importing to Keycloak.
- The
WorkfusionRealm-realm.jsonfile is updated to inject group, role, user, and qualification declarations.
Once the upgrade is over, check the migration results in a dedicated log at INSTALL_DIR/logs/user-migration.log.
Log example:
2020-11-27 09:45:56,341 INFO [main] c.w.u.m.m.t.j.JdbcUserExtractor [JdbcUserExtractor.java:148] Users with the following usernames were merged: [autotest18, autotest19, autotest16, autotest17].
2020-11-27 09:45:56,350 INFO [main] c.w.u.m.m.t.m.UserDataConfigurationMapper [UserDataConfigurationMapper.java:65] Converting user related data.
2020-11-27 09:45:56,440 INFO [main] c.w.u.m.m.t.s.RealmSerializer [RealmSerializer.java:49] Serializing realm data.
2020-11-27 09:45:56,780 INFO [main] c.w.u.m.m.t.App [App.java:30] Migration results: 403 user(s), 4 role(s), 5 group(s)
What you get after migration
Users from a previous platform version are fully migrated into the new user management system together with their roles, permissions, and related mappings, subject to the following considerations.
Merge WS and CT users with identical names
If users with the same username existed in CT and WS before migration, the tool merges the CT and WS users into one. The merged user utilizes the CT password. When needed, the Administrator can create a separate account for accessing WS.
You can find information about such merges in the migration log, for instance:
2020-11-27 09:45:56,341 INFO [main] c.w.u.m.m.t.j.JdbcUserExtractor [JdbcUserExtractor.java:148] Users with the following usernames were merged: [autotest18, autotest19, autotest16, autotest17].
Supplement CT roles
Suppose a CT role had the MANAGE_USERS permission. In that case, it is supplemented with the following roles from the realm-management client in Keycloak: view-users, manage-identity-providers, query-clients, query-users, manage-clients, manage-users, query-groups, view-identity-providers, view-clients.
If a CT role had the PM_VIEW_STATISTICS or PM_EXECUTE_ACTIONS permissions, it is supplemented with the Admin role from the wf-kibana client in Keycloak.
Skip disabled groups
Keycloak doesn't support the enabled or disabled states for groups in platform versions prior to 10.2. So, the migration tool skips all disabled groups from CT.
Enable shared email for CT and WS users
Users from CT and WS with different usernames can have the same email. To enable the feature after migration, go to WorkFusion realm > Realm settings > Login and make sure the Duplicate Emails toggle is on.
Migrate qualifications
Qualifications for Manual Tasks (MT) in WS are migrated as user groups, and Qualification names—as qualifications/\<qualification_name>. Each worker becomes a user in a proper group based on their Qualifications.
For instance, Worker 1 had Qualification 1, and Worker 2 had Qualifications 2 and 3 in CT. After migration, the Qualifications are available on the Groups tab as user groups under the names qualifications/Qualification_1, qualifications/Qualification_2, and qualifications/Qualification_3, accordingly. Worker 1 becomes a user in the group named qualifications/Qualification_1, and Worker 2 becomes a user in the two groups—qualifications/Qualification_2 and qualifications/Qualification_3. To сheck the workers are in their proper groups, follow the instruction.
Mind the difference between the qualification and user group logic. Qualifications employ the AND logic: if an MT has several qualifications, it is visible only to the users who have all of them. User groups work based on the OR logic: if an MT has several qualifications, it is visible to the users who have any of them.
Migrate password hashes
Password hashes of CT and WS users are automatically migrated using BCrypt defined in the bcrypt-support-plugin module. When a user changes a password, BCrypt is substituted for PBKDF2-SHA256, which is used in Keycloak by default.
For more information about data import with Keycloak, refer to the Keycloak official documentation.
Migrate LDAP and IDP users
The described tool also enables automatic migration of LDAP (Active Directory) and IDP users configured for previous platform versions in the course of upgrading. However, to use them, comply with the additional requirements detailed in the sub-sections below
LDAP users
Configure LDAP access according to the instruction, selecting the custom ldap-with-local-users-override provider. The latter is designed specifically for the migration case and is not supposed to be used for any purposes other than migration.
For details on the ldap-with-local-users-override provider, refer to the Configure LDAP guide.
Mind that you will have the possibility to log in both with LDAP users and local Keycloak ones. The Keycloak users will prevail.
IDP users
For migrating IDP users, meet the following prerequisites:
Configure IDP access according to the instruction.
Go to the Settings page of the configured SAML provider and select Link Trusted Provider for the First login flow.
The flow is designed specifically for the migration case and is not supposed to be used for any purposes other than the migration process. For a new installation, use First broker login. For details on the Link Trusted Provider flow, refer to the Configure Identity Providers instruction.
Go to the Mappers section and add the following mappers:
email
first name
last name
Set up the SMTP server settings.
Migrate Business Processes with qualified MTs
The migration tool enables automatic migration of existing users and qualifications, but not Business Processes (BPs).
To migrate a BP with a qualified MT, create a BP package and deploy it to the upgraded platform. As a result, the BP is migrated with MT qualifications transformed into user groups. The names for the resulting groups match the pattern qualifications/\<qualification_name>. The same names are added to the Workspace Preview Scheme as a default value for the _sys_user_groups attribute.
The Preview Scheme is used to create filter attributes and set access levels based on the _sys_user_groups attribute values. For details, refer to the guide on setting filter attributes.
The Workspace Preview Scheme for the qualified MT is modified and saved with the (Qualifications Migrated) postfix. If the MT doesn't have a Preview Scheme, it is created with the User Groups (Qualifications Migrated) name.
For example, a BP comprises a Manual Task with the Worker Adult qualification and a Preview Scheme named MT WS Scheme. After migration, the _sys_user_groups attribute is added to WS Preview Scheme with its default value set to /qualifications/Worker Adult. The Preview Scheme will have a new name—MT WS Scheme (Qualifications Migrated).