On this page:
| Table of Contents |
|---|
...
Apply transformations to users
With the Cloud Migration Tool, you can smoothly migrate Jira Server or Data Center users to the cloud. It helps you fix missing or invalid email addresses and resolve conflicts during the process. Once you create a migration, select projects, and reach the Analyze changes phase, you'll have the tools and control to migrate the desired users to the cloud without any errors.
See how users are reported during the migration analysis phase in the screenshot below.
...
Which users are migrated to the cloud?
Jira users, groups, and roles are integral to the project configuration - permissions, notifications, workflows, etc. Therefore, any users, groups, and roles used in the project will be included in the migration.
After adding projects to the migration, users linked to these projects through configuration elements are also included. For example, users assigned to issues in a particular project, assigned as project leads, or single users assigned to project permissions, will be included in the migration.
Learn more about the migration process in our articles.
How are Jira Server/Data Center users migrated to the cloud?
When it comes to migrating Jira Server/Data Center users to the cloud, the Cloud Migration Tool covers the following scenarios:
Users who don’t have an account on the Jira Cloud site will be invited to join after the migration.
Users with emails that exist on Jira Cloud won’t be migrated and are marked as existing.
Users without an email address or with an invalid email address will be reported as a problem.
In these cases, the migration can’t continue as the Cloud Migration Tool can’t determine if the user exists on the Jira Cloud site. To continue the migration, you will need to resolve these errors first. The Cloud Migration Tool gives you the option to fix user problems without leaving the migration wizard.
Fix problems by customizing user mapping
The Analyze changes > Users tab reports the users in the migration and their details. It also gives you the option to edit user details without leaving the wizard. There are four user states you can observe in the Users tab:
A user that doesn’t have an account on the Jira Cloud site and will be invited to join.Status colour Green title NEW
A user with this email exists in this Jira Cloud site.Status colour Purple title existing
A user who doesn’t have a valid email address and it cannot be determined if the account exists in the Jira Cloud site. The user either doesn’t have an email address or its email address is invalid.Status colour Red title unknown
A user whose details are updated and this way it is mapped to an account in the Jira Cloud.Status colour Yellow title customized
The option to overwrite user details is accessed through the Customize mapping button in the wizard. It allows you to change the default mapping between the details of server and cloud users and default source Jira users’ details. By uploading a CSV file with usernames and email addresses, you can correct problems like missing and invalid email addresses.
With that option, you can also You can apply transformations to users the same way you do to the rest of the configuration in the migration. Basically, you can overwrite user details with the Customize mapping button at the top right of the Analyze changes page in the migration wizard. You can learn more about customizing configuration mapping and the mechanisms to do it.
| Info |
|---|
What is mapping or configuration mapping? Mapping or configuration mapping is an extensive map formed during the analysis process. It holds information on how the configuration elements in the migration scope will be moved to the cloud. The elements will either be created anew or updated if there’s a match between the source and destination counterparts. |
Learn more about the transformations our Cloud Migration Tool offers.
...
User transformation use cases
You can use the Customize mapping option to:
Correct user problems
The Customize mapping feature allows you to correct user problems like missing and invalid email addresses when mapping users during a server-to-cloud deployment. You can also remap server and cloud users this way.Merge user accounts
You can also use the transformations to map multiple source users to a single Jira Cloud account. To achieve it, you need to change the email addresses of multiple Jira Server/Data Center user accounts to
...
be the same
...
. This way, the Cloud Migration Tool will map all of them to a single
...
Jira Cloud
...
account.
| Info |
|---|
Users that are not customized but have the same email will also be mapped to a single Jira Cloud account. |
...
How to apply transformations to users?
To address the use cases above, you just need to upload a file with the desired user transformations. For example, if an email address is missing, you’ll be able to prepare and apply a file with a corrected email for a particular user.
Downloading and uploading a file with user transformations
To apply transformations to users:
Start a migration.
On the Analyze changes phase, move to the Users tab. Read more about migrating users.
Check for any users with missing or invalid email addresses.
To resolve any problems with unknown users or if you want to change the default user information, click the Download mappingbutton at the top right. You will get a CSV JSON file with the default user mapping.
The downloaded file named cmt_usermapping.csv contains the server users’ email addresses and usernames.Modify the CSV mapping of all configuration elements in the migration including users.
Modify the JSON file to correct missing or invalid email addresses. Also, if you would like to map several server users to a single Jira Cloud account, change their email addresses to match the email address of that Jira Cloud user. Check the guidelines about customizing mapping.
Click Customize mappingto , upload the CVS JSON file with the user changes.
changes, and click Confirm.
After the customizations are applied, you’ll return to the Users tab , where you’ll to see that users with changes from the CSV JSON file have the
tag.Status colour Yellow title customizedCUSTOMIZED
| Note |
|---|
Losing user mapping changes If you rerun the analysis, you’ll lose any customizations to the user mapping. So, first, resolve conflicts and errors in projects and configuration elements, and then introduce changes to users by customizing their mapping. |
...
The video below shows how to upload and apply transformations from a JSON file.
After you’re done making changes to the user mapping, click Migrate to move on with the migration.
| Info | ||||||
|---|---|---|---|---|---|---|
After you click Confirm on the Customize mapping window, the Cloud Migration Tool performs a new analysis of the migrated configuration and applies the transformations from the file. Each project, configuration element, and user that has been changed by the JSON file will have the
|
Constructing a JSON file mapping
In the migration wizard, you can download a file that contains all the information about the users and how they’ll be migrated to the cloud. Then, you can either make changes to that file to include your desired user transformations or you can construct your own file and apply either of the files to the configuration.
The applied file always must be in JSON format. Also, there are some requirements on how to list the intended transformations in it. Check the guide we’ve prepared to quickly get you started on building your transformations.
For users, the transformation you can apply is changing an email address. This way, you can create new users, merge multiple users into a single account, and remap source and destination users.
The important thing to note is that source and destination users are matched by their names. What this means is that you always need to provide the source user’s name in the JSON file in order to apply a transformation to it.
Required JSON records to transform a user
The example below shows the specific records required to change a user’s email address.
| Code Block | ||
|---|---|---|
| ||
"users" : [ {
"source" : {
"id" : "invalidEmail@demo",
"name" : "usernameInvalidEmail",
"email" : "invalidEmail@demo"
},
"transformation" : {
"email" : "validEmail@demo.com"
}
}
] |
Editing a user in a downloaded JSON file
You can achieve the same by downloading the current mapping file and editing it. If this is the case, the records for the user most probably will look like this:
| Code Block | ||
|---|---|---|
| ||
"users" : [ {
"source" : {
"id" : "invalidEmail@demo",
"name" : "usernameInvalidEmail",
"email" : "invalidEmail@demo"
},
"destination" : {
"newObject" : true
},
"transformation" : {
"email" : "validEmail@demo.com"
}
}
] |
This is in the case that you only add a transformation record without changing the default source and destination user records in the downloaded file. For more details about editing or constructing a mapping file, check this guide.