• Products
  • Documentation
  • Resources

Use the Jira Cloud Migration Assistant to migrate

For a test migration or UAT, we recommend that your test cloud site is not part of the organization that also hosts your prod site. The prod site should be hosted in a different organization. This is to ensure smooth migration of the relevant users and groups.

The Jira Cloud Migration Assistant is an app that helps you easily move projects, users, and groups from Jira Work Management (formerly Jira Core) or Jira Software on server to the cloud. Built and maintained by Atlassian, the app is free to install and use.

Once installed, you can choose what you want to move to the cloud, start migrating at your convenience, and monitor the progress of everything throughout the migration process.

Important changes to our server and Data Center products

We’ve ended sales for new server licenses, and will end support for server on February 2, 2024. We’re continuing our investment in Data Center with several key improvements. Learn what this means for you.

When to use the Jira Cloud Migration Assistant

Use the Jira Cloud Migration Assistant when you:

  • are migrating Jira Work Management (formerly Jira Core) or Jira Software from server to cloud.

  • want to migrate only some projects from server to cloud.

  • are migrating to a new or existing cloud site.

Learn more about the compatibility of the Jira Cloud Migration Assistant. 

The Jira Cloud Migration Assistant does not migrate Service projects or Confluence spaces. Review all the migration methods to find the one that is right for your circumstance.

Use our migration guide to prepare and plan for your migration from server to cloud. 

More about the Jira Cloud Migration Assistant

Using the Jira Cloud Migration Assistant to migrate is different to using Jira Site Import. Here are some key things to be aware of before using this tool:

  • Data won’t be overwritten or deleted
    When the Jira Cloud Migration Assistant migrates your data, it will be added to your cloud site along with any data that is already there. It won’t delete anything from either your server or cloud sites.

  • Data may get linked to avoid duplication
    When you migrate multiple times we will attempt to link your data to avoid duplication. Learn about how we link data

  • Using Site Import and the Jira Cloud Migration Assistant can cause data duplication
    Migrating data in stages, first with Jira Site Import then followed by the Jira Cloud Migration Assistant from the same server or Data Center instance, will cause shared configuration entities (workflows, custom fields, schemes, etc.) to be duplicated on the cloud site. We do not recommend this migration strategy because you will need to do a large amount of manual post-migration cleanup work.

  • Jira Work Management (formerly Jira Core) and Jira Software data only
    With the latest version of the Jira Cloud Migration Assistant, you can migrate Jira Work Management (formerly Jira Core) or Jira Software projects with most fields supported. It does not yet support Jira Service Management (formerly Jira Service Desk) or some custom fields. Check out the latest updates for what can and can’t be migrated.

  • Company-managed projects only
    Migration to Jira Cloud team-managed projects is not supported. 

Check the types of data that the Jira Cloud Migration Assistant can migrate before using it to run your migration. 

Before you begin

Before attempting a test or production migration, ensure you've completed all of the steps for the Jira Cloud Migration Assistant in the pre-migration checklist. The checklist will help you prepare yourself and your data for migration, and ensure you avoid common sources of migration failure.

If you're on Jira version 8.14, the migration assistant is automatically installed in your server instance.

Install the Jira Cloud Migration Assistant app (for Jira 7.6 or newer)

To install the app:

  1. In Jira Server or Data Center go to Settings > Manage apps.

  2. Choose Find new apps and search for Jira Cloud Migration Assistant.

  3. Choose Install and you're all set.

Alternatively, you can install it from the Atlassian Marketplace.

Locate the Migration Assistant

To find the Migration assistant:

  1. Go to Settings > System.

  2. In the left panel, locate the the Import and Export category, and select Migrate to cloud. The Migration Assistant home screen is displayed.

Note

  • If you’re unable to find the migration assistant, check that you’re on a supported version of Jira.

  • If your Jira Server site is behind a firewall, you'll need to allow access to the following domain: atlassian.com

Migration assistant home

This home page displays the 3 stages of assessing and creating your migration path:

  1. Assess your apps

  2. Prepare your apps

  3. Migrate your data

The sections that follow explain each of these stages in detail.

 

1. Assess your apps

If you have critical data managed by apps on your server, be sure to check with the app vendor about the best process to migrate that data.

Auditing apps on your server, assessing them and choosing alternative apps (if required) for your cloud site before migration removes the risk of your apps blocking your migration at a crucial time.

At this stage, you can see the apps you have installed on your server and assess your apps in preparation to migrate.

To begin assessing your apps:

On the Migration Assistant home screen, select Assess your apps.

screenshot-JCMA-home-Assess-your-apps-highlight
Migration-assistant-assess-your-apps

For more information on using this table in the Jira Cloud Migration Assistant, you can refer to this information on assessing and migrating apps with the Cloud Migration Assistant

2. Prepare your apps

There are 2 main tasks you’ll perform at this stage:

  • Connect to your cloud site

  • Install your apps

To begin preparing your apps:

On the Migration Assistant home screen, select Prepare your apps.
This takes you to the Connect to cloud screen.

screenshot_JCMA_step2-highlight

Connect to cloud

You can connect to your chosen cloud site at this step. There are three ways to do this.

- Select your existing cloud site from the dropdown.
- Signup for an Atlassian Free plan (max 10 users, free cloud site).
- Set up a free product trial.

Once your destination is selected, click Continue.
This takes you to the Install your apps screen.

Install your apps

  1. Select Install app for each listed app to install it on your cloud site. This screen also links to support and the privacy policy for each app.

  2. Select Done to return to the Migration Assistant home screen.

  • In order to complete the assessment flow, you must install the app/s you need in cloud at this stage.

  • We strongly recommend reading the privacy policy of each app. 

  • The Done button will be disabled if you have not done the following:

    • assigned a status to each app (on the Assess your apps screen)

    • installed apps needed in cloud (on the Install your apps screen)

    Complete the above tasks to enable the Done button.

App migration is now available with the EAP (Early Access Program)
On 13 May 2021, we released the Early Access Program (EAP) for app migration using the Jira Cloud Migration Assistant (JCMA). This means that you can now migrate your apps to cloud.

In summary you can:

  • choose apps to migrate from server to cloud

  • give consent to migrate your app data to cloud

  • view migration preflight checks about users and groups, projects and apps

  • perform the app migration

  • view logs and reports about the migration

If you are interested in joining the app migrations EAP, you can begin here by completing the EAP survey.

3. Migrate your data

There are five key steps to set up and run your migration from server to cloud. They are:

  • Connect to your cloud site

  • Choose your migration options

  • Check for errors

  • Review your migration

  • Migrate

The sections below describe each step in detail and explain some common errors that you may come across. If you have technical questions or issues while using the migration assistant, get in touch with our technical support team.

To begin migrating your data:

  1. On the Migration assistant home screen, select Migrate your data.
    This takes you to the Migrations dashboard.

  2. Select Create new migration.
    This takes you to the How it works screen.

  3. Review the information on this screen, and select Connect to cloud to continue.

screenshot_JCMA_step3-highlight

Connect to your cloud site

  1. In the Name your migration field, add a name for your migration.

  2. In the Choose your destination cloud site field, choose the cloud site you would like to migrate to.

  3. To continue, select Choose what to migrate.
    This takes you to the Choose your migration options screen.

  • You need to be an admin in both your server and the destination cloud sites.

  • If you have already connected a cloud site, you should see it in the dropdown. If there is nothing there, you will need to either connect a new cloud site or sign up for a trial

  • When you’re ready to go, check the box to allow Atlassian to move your data from your server site to your cloud site. If you’re unable to grant Atlassian this access, you won’t be able to migrate with the migration assistant and will need to do a manual import instead.

  • If your Jira Server site is behind a firewall, you'll need to allow access to the domain: atlassian.com. You also might need to allow access to other Atlassian domains

connect to cloud

Choose your migration options

You can migrate everything together or break it up into different stages. You can choose:

  • projects

  • users and groups

Before choosing what to migrate, make sure you check out what is and isn't migrated with the migration assistant.

  1. To select projects, tick the Projects option. (If you aren’t migrating any projects, you can proceed to select users and groups.)
    This takes you to the Choose the projects you’d like to migrate screen.

    • You can choose to migrate all or some of your projects.

    • You can search for a particular project, or select the top box to select all projects.

    • You won’t be able to migrate projects with project keys that already exist in your Jira Cloud destination site.

    • If you have lots of projects and attachments, you might want to break the migration up into a few smaller migrations. This will allow you to have smaller maintenance or downtime windows.

    • Apart from other projects, you can also migrate archived projects. Search or use the filter to locate the archived projects.

      When you've chosen all your projects, select Apply changes.

  2. To select users and groups, select the Users and groups option.
    After you have selected your projects you will have the option to select your users and groups.

    • You can’t select a subset of users without any projects. This is because the Jira Cloud Migration Assistant must use the project data to determine which users to add to the migration. Learn more about user and group migration. 

    • We will never send invitation emails to your users during the migration process.

    • If you select Only users and groups related to the selected projects, you’ll get the option to add additional users based on project roles and groups. Use our guide to help you make a selection.

    • Before continuing, you will need to select whether you want to preserve group membership or migrate your users separately to their groups.

      • Preserve group membership. This option will add your users to their groups as part of the migration. Your users will have access to their projects and will be added to your Jira Cloud license.

      • Migrate users and groups separately. This option will migrate the selected users and groups, but the users will not be added to the groups as part of the migration. Your users will be given Atlassian Accounts, but they won’t have access to projects and they won’t be added to your Jira Cloud license.

        Once you have made your selection, select Apply changes.

When you return to the Choose your migration options screen, click Check for errors to continue.

When migrating users and groups

  • Users are migrated using email address as the source of truth. On subsequent migrations, the migration assistant will link users by email address rather than re-migrating them. Check out our tips for migrating a large number of users

  • You must validate all your user accounts (email addresses) before migrating to cloud. Migrating unknown user accounts can potentially allow unauthorized access to your cloud sites. For example, if you had users in your server instance with emails that you don’t own, say “email@example.com”, you might be inviting someone who owns “@example.com” to your site in cloud.

  • Jira Cloud is subscription-based and billed on a per-user basis. If you plan to migrate your users, make sure you check the licensing options available

  • If you use an external user management system, we recommend synchronizing it with your local directory before migrating. This is to make sure that your users and groups are up to date before you transfer any data.

  • Users with disabled status in your server site will be migrated as active but without any product access. This means they will not be counted as active Jira users for billing purposes.

  • If we find a group in your server site that has the same name as a group in your cloud site, we will merge the users from the server group into the cloud group.

  • Global settings and global site permissions are not migrated with this tool. You’ll need to set these manually after migration.

  • If you have users that already exist in your destination cloud site and you choose to migrate users with this app, the following will occur:

    • If a user has product access in cloud, but has disabled status in your server site, they will continue to have product access in cloud after migration.

    • If a user does not have product access in cloud, but is enabled in your server site, they will be granted product access through the migration process.

If you use Jira as a knowledge base for Jira Service Management (formerly Jira Service Desk), your Jira Service Management users may also be migrated along with your Jira users. This will happen if you can see your Jira Service Management users in the cwd_user table in Jira.

Check for errors

In this step, the Jira Cloud Migration Assistant will review your migration and check for common errors. It will check if:

  • the migration assistant is up to date

  • users have valid email addresses

  • users have unique email addresses

  • groups will be merged

  • projects will clash 

  • projects, boards, and filters are publicly available and searchable online

You may also encounter other issues during the migration process; this step only checks for the issues mentioned here.

Symbol/Message

Description

Action required

screenshot_error-screen_green-tick

A green tick means that the check has passed.

Proceed to the next step in your migration.

screenshot_error-message_yellow-warning

A yellow warning means that you can continue, but you need to be aware of a potential issue.

Expand the error and warning messages to reveal more details and links.

screenshot_error-message_red-error

A red error means that you need to resolve the error before you can run your migration.

Expand the error and warning messages to reveal more details and links.

Message

Description

Action required

The Migration Assistant is out of date

This message indicates that the version of the Cloud Migration Assistant that you’re using is out of date.

Update to the latest supported version of the Cloud Migration Assistant.

 

Message

Description

Action required

Some groups already exist in your cloud site

Users from groups on server will be merged into the groups on cloud with the same name, and will inherit their permissions.

If you have chosen to migrate all users, we will check to see if you have any groups with the same name already in your cloud site. If we find groups with the same name, we will merge the users from the server group into the cloud group with the same name.

You can continue, but if you want to prevent this, make sure all groups across server and cloud have unique names. Learn more

You can continue with your migration without fixing this issue, but it’s important to check that this won’t cause permission escalation.

Multiple uses have the same email address

All users will need to have a valid and unique email address. If we detect invalid emails or multiple users with the same email, you will get an error.

You will need to fix these email addresses before you can run your migration.

Invalid email addresses

All users will need to have a valid and unique email address. If we detect invalid emails or multiple users with the same email, you will get an error.

You will need to fix these email addresses before you can run your migration.

To migrate, all users will need to have a valid and complete email address (e.g. example.name@atlassian.com). Click on the username to update the user’s email address.

The following groups manage admin access and are blocklisted:

  • "site-admins"

  • "system-administrators"

  • "atlassian-addons"

  • "atlassian-addons-admin"



The following groups will not be migrated at all.

Users in these groups will still be migrated.

If you want them to be in one of the blocklisted groups, you’ll need to manually add them after migration.

If you have selected to migrate a subset of your users, the check may take a little longer to run as it will need to scan through all your project data.

If you decide to Continue and fix later, you can come back to view the errors once you have saved your migration.

Review your migration

This is the final step in setting up your migration.

Review migration first tab

You can switch tabs to view details about what is included (users and groups / projects) in your migration or to download the pre-migration report, post migration report, and error logs.

In the Logs and reports tab, you can download the pre-migration report (.zip file) to scan through data before migrating it to your cloud site. The report includes the following information:

  • Summary -  This lists the summary data on what is expected to migrate and not migrate.

  • Requires attention - This lists items that require your attention, for example, items that are not supported via migration.

  • Users and groups - This lists users and groups that will be included in your migration.

  • Configuration items -  This lists all the custom fields and workflows that are part of the migration.

If everything looks correct and you want to start your migration, click Run. If you would like to start your migration later or you still have errors to fix, click Save.

If you choose to run your migration, it will still be saved to your migration dashboard. There, you can view the progress and details of all your migrations.

Once your migration is complete, you can download the post migration report (.zip file) to know the status of the migrated data in your cloud site. The report includes the following information:

  • Summary - This lists the summary data on what successfully migrated and what didn't migrate.

  • Requires attention - This lists items that require your attention, for example, items that were not supported via migration.

5. Manage and run your migrations

Your saved migration will be listed on the migration dashboard, where you can View details or Run it. You can also check the status of a migration, monitor the progress, or create a new one.

You can create as many migrations as you need. At this time, migrations can't be edited or deleted, so if you create a migration that can't be used, just create a new one.

screenshot_migrations-dashboard

The table below describes the possible statuses for migrations.

Status

Description

SAVED

Your migration is saved and ready to run.

RUNNING

Your migration is currently in progress.

FINISHED

All tasks in your migration have been completed.

INCOMPLETE

Some tasks were completed but there are some errors or some things that couldn’t be migrated. Importantly, this status means that some data (users, groups, projects, issues etc) has been migrated and you may need to clear this data from your cloud site if you re-migrate the same projects.

FAILED

We were unable to complete the migration. This might be because a project key already exists in the destination site, or the migration hit an unexpected error.

 

Migration details

You can review all the details of your migration by selecting View details from the migration dashboard. On the details page, you will find a summary of your migration and detailed progress for each project in your migration. 

running-migration

Error logs

If your migration is Incomplete or Failed you can download the error logs to understand the errors in more detail. Once the migration has stopped running, you will find a link to download the error logs on the top of the details page.

Migration failed

After migrating

You can view the project on your cloud site as soon as all the project data is migrated — even if your attachments haven't finished: Select the project name on your migration details page.

Depending on the type of migration, there may be some things you need to do once your migration is finished. For a full list of post-migration recommendations, refer to the migration planning guide.

Users and groups

To make sure your users and groups are set up correctly:

  • Review members of groups and approve their permissions by going to Administration > User management.

  • Add users to the general administrator groups if necessary. The generic groups are: "site-admins", "system-administrators", "atlassian-addons", "atlassian-addons-admin".

  • If you use an external user management system, check that your users have synced correctly.

  • When you are ready, invite your users. Go to Administration > Users > Show details and then Resend invite. When they first log in they may be prompted to set a new password and add personal details.

If you have the improved user management experience, go to Administration > Directory > Users > Show details and then Resend invite.

Projects

To check that your projects have migrated successfully:

  • Review projects and issues, or ask your users to review their own projects.

  • Check for any unusual instances of Former User. This means that we were unable to match content to a user.

  • Check your JQL and quick filters for any instances of the phrase (migrated). If you find this, you will need to merge the (migrated) field with the existing version in cloud for your filter to work. 

  • Link your other Atlassian products by going to Settings (cog icon) > Jira settings > Products > Application links.

  • You can then install any other apps you wish to use and onboard your users.


Known issues and troubleshooting

Topic

Description

Data integrity

If your Jira server site is highly customized, you may face additional issues when migrating. For example, if you have any required field with a null value the migration will fail because this is not supported on your cloud site. We recommend cleaning up your server data before migrating.

Extra-large projects

Single projects with more than 100,000 issues may cause the Jira Cloud Migration Assistant to time out. We recommend only migrating projects with less than 100,000 issues. You can still migrate multiple smaller projects with more than 100,000 issues between them. 

Migrating all users and groups

We will migrate all your users and groups every time you run a migration. If you have lots of users and groups, this could take a significant amount of time.

You can migrate up to 20000 active users and an unlimited amount of inactive users. However, the more users you migrate, the more issues you will face and the longer it will take.

Incomplete migrations and projects

An incomplete status means that some things have been migrated but there was at least 1 entity that we couldn’t migrate. For example, we might be able to migrate a project but 1 issue fails because there is a null value in a custom field. In this case, the project will show up as incomplete even though all the actual data is complete. Many times this status will not be a problem for your migration. Download the error logs to determine what is causing the failure. 

Changes on server before migrating

If you make any changes on your server site, wait at least 10 minutes before migrating to allow all data to be updated. 

Changing projects keys

If you choose to change a project key on your server before or during migration, make sure that all configuration, filters and boards are updated with the new project key before attempting a new migration. 

Links to projects and issues not in the migration

If you have chosen to migrate in smaller batches, links to projects or issues that haven't yet been migrated will be missing until that linked item is migrated. 

History entries with missing references

If a history entry refers to a missing link or attachment, the history entry won't be migrated. If a linked issue or project is migrated at a later date, the history entry will be updated. 

Jira Software boards not returning correct results

The migration assistant does not check that  the JQL issue filters on boards are returning the correct results after migration. If a board has a filter that mentions a project or field that is not yet migrated, the board may not return the same results after it is migrated. To fix this issue, edit the board's JQL filter after migrating. 

Jira new issue view

If your cloud site uses the new issue view, you might want to run some training or create a tutorial video to explain the differences that your users may experience between the two views. You can change between the old and new issue view following the steps here

More information and support

We have a number of channels available to help you with your migration.

Last modified on Sep 7, 2021
Cached at 9:02 PM on Sep 16, 2021 |

Additional Help