User Transformations

On this page:

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.

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.

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:

1. Start a migration.

2. On the Analyze changes phase, move to the Users tab. Read more about migrating users.

3. Check for any users with missing or invalid email addresses.

4. To resolve any problems with unknown users or if you want to change the default user information, click the Download mapping button at the top right. You will get a JSON file with the default mapping of all configuration elements in the migration including users.

   

5. 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.

6. 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 CUSTOMIZED tag. The video below shows how to upload and apply transformations from a JSON file.

   CMT-customize-mapping.mp4

7. After you’re done making changes to the user mapping, click Migrate to move on with the migration.

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.

{
    "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:

{
    "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.