On this page:
|
Managing and migrating users
With the Cloud Migration Tool, you can intelligently migrate Jira Server or Data Center users to the cloud by correcting missing and invalid email addresses and resolving conflicts along the way. After creating a migration, selecting projects to migrate, and reaching the Analyze changes phase, you have the necessary tools and control of migrating the desired users to the cloud without errors.
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 you are attempting to migrate will be included in the migration.
After adding projects to the migration, users referenced by configuration elements associated with these projects are 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?
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 who either don’t have an email address or have 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. Therefore, you first need to resolve these errors and then continue the migration.
Customize mapping between Jira Server/Data Center and Cloud users
Users can be mapped to an account on the Jira Cloud site via custom user mapping. By uploading a custom user mapping CSV file, you can customize the Jira Server or Data Center users’ configuration to fix users without email addresses or with invalid email addresses during migrations.
...
|
Apply transformations to users
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 mapping or configuration mapping is 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 as new ones or modified 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, such as 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.
...
User mapping during a migration
After starting a migration and reaching its Analyze changes phase, you’ll be able to view all the users from the projects in the migration and customize user details if necessary.
Additionally, you’ll be notified of any errors in the user accounts, like missing and invalid email addresses. Besides correcting errors, you could map several Jira Server/Data Center users to a single Jira Cloud account if you would like to.
The Users tab on the Analyze changes phase contains all that information described above, plus the option to customize the user mapping.
How can you customize the default user mapping?
Customizing mapping allows you to change the default mapping between server and cloud users or default source user information. By uploading a CSV file with the server user usernames and email addresses, you can correct missing and invalid email addresses and map several Jira Server/Data Center users to a single Jira Cloud account.
| Info |
|---|
Users that are not customized but have the same email will be mapped to a single Jira Cloud account. |
There are four user states you can observe in the Users tab on the Analyze changes pages:
User doesn’t have an account in this Jira Cloud site and will be invited to join.Status colour Green title NEW
User with this email exists in this Jira Cloud site.Status colour Purple title existing
User doesn’t have a valid email address and it cannot be determined if the account exists in this Jira Cloud site. The user either doesn’t have an email address or its email address is invalid.Status colour Red title unknown
User is mapped to an account in this Jira Cloud site via custom mapping.Status colour Yellow title customized
Map to a chosen destination user
You can also apply a transformation to map a source user to a destination user of your choice. To do so, you just need to provide the destination user’s ID.
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.
You can also check out the following use case page on Appfire's website to find more useful information and view a demo of how to customize the configuration mapping.
https://appfire.com/products/use-cases/modify-configuration-mapping-cloud-migrationDownload and upload 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 to change the default user information, click the Download mappingbutton at the top right. You will get a JSON file with the default
...
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 mapping
...
, upload the
...
JSON file with the
...
changes, and click Confirm.
...
After the customizations are applied,
...
return to the Users tab
...
to see that users with changes from the
...
JSON file have the
Status colour Yellow title
...
tagCUSTOMIZED
...
| 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
|
Guidelines for creating JSON user transformations
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 must always 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.
With the Customize mapping option in the migration wizard, you can apply two types of transformations to users being migrated:
Change email address
Map to a destination user by ID
By changing the email address, 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 we refer to source users by their names. This means that you always need to provide the source user’s name in the JSON file in order to apply a transformation to it.
Let’s look at the examples below to make it clearer.
Required JSON records to transform users
You can construct your own JSON file with user transformations and apply it to the configuration being migrated. The examples below show you the records you need to have in the file to change a user’s email address or to map it to a destination user.
Required JSON records to change the user’s email address
The example below shows the specific records required to change a user’s email address.
| Code Block | ||
|---|---|---|
| ||
{
"users": [
{
"source": {
"id": "User's name",
},
"transformation": {
"email": "validEmail@demo.com"
}
}
]
} |
Required JSON records to map a source user to a destination user by ID
The example below shows the specific records required to map a source user to a destination user by ID.
| Code Block | ||
|---|---|---|
| ||
{
"users": [
{
"source": {
"id": "User's name",
},
"transformation": {
"id": "5da444878f33800c416f30ed"
}
}
]
} |
Edit a user in a downloaded JSON file
You can apply the same transformations from above by downloading the current mapping file and editing it. For more details about editing or constructing a mapping file, check this guide. The examples below show you how the user records will look in the downloaded file and the additional transformation record you need to add.
Transformation to change the user’s email address
When you download a mapping file, the source and destination records for the user will look like in the example below. You only need to add a transformation record with the new email address without changing the default source and destination user records. After applying the edited file, the user being migrated will have a new email address.
| Code Block | ||
|---|---|---|
| ||
{
"users": [
{
"source": {
"id": "usernameInvalidEmail",
"name": "usernameInvalidEmail",
"email": "invalidEmail@demo"
},
"destination": {
"newObject": true
},
"transformation": {
"email": "validEmail@demo.com"
}
}
]
} |
Transformation to map a source user to a destination user by ID
When you download a mapping file, the source and destination records for the user will look like in the example below. You only need to add a transformation record with the destination user’s ID without changing the default source and destination user records. After applying the edited file, the source user will be mapped to that destination user.
| Code Block | ||
|---|---|---|
| ||
{
"users": [
{
"source": {
"id": "sourceUser",
"name": "sourceUser",
"email": "sourceUser@demo.com"
},
"destination": {
"newObject": true
},
"transformation": {
"id": "5da444878f33800c416f30ed"
}
}
]
} |