• Products
  • Documentation
  • Resources

Use the Jira Cloud Migration Assistant to migrate

For a test migration or UAT, to ensure smooth migration of the relevant users and groups 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.

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. 

Before using 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

Note about apps in ‘Stage 1’ and ‘Stage 2’

On the ‘Assess your apps’ screen, apps with an ‘Automated path’ can be listed with a Stage 1 or Stage 2 label.

  • Stage 1: Apps in this stage have an unknown, or demonstrated low migration success rates. If you choose to migrate Stage 1 apps and the app data migration fails, you will need to contact the respective Marketplace Partner (app vendor) for support.

  • Stage 2: Apps in this stage have demonstrated high migration success rates.

As you assess your apps, it is important to read our docs to understand the stages of apps with automated migration paths.

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.

 

Use the Jira Cloud Migration Assistant to see the apps you’ve installed on your server and assess apps in preparation to migrate. Assessing your apps and choosing alternatives (if required) for your cloud site before migration removes the risk of your apps blocking your migration at a crucial time.

To begin assessing your apps:

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

screenshot-JCMA-home-Assess-your-apps-highlight
screenshot_JCMA-assess-your-apps

Read more about how to use the ‘Assess your apps’ screen.

When you have finished assessing your apps, select Done. This takes you back to the ‘Migration Assistant home’ screen where you can choose to prepare your apps as the next step.

2. Prepare your apps

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

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

  • Connect to your cloud site

  • Install your apps

  • Agree to app migration

screenshot_JCMA_step2-highlight

Connect to your cloud site

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

On the ‘Install your apps’ screen:

  1. Select Install app for each listed app to install it on your cloud site.

  2. Read the support and privacy policy for each app.

  3. Select Continue. This takes you to the ‘Agree to app migration’ 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.

Agree to app migration

When an app migration is performed, the migration moves the data from each server app to its cloud version on your cloud site. The Marketplace Partner (vendor) that built each app has created a migration pathway to move the data.

During this process, the Marketplace Partner will actually be performing the app data migration, not Atlassian. Because of this, you need to review, and agree to each Marketplace Partner agreement so they can access your data to migrate it.

In order to complete the assessment flow, you must provide consent and agree to app migration for each app.

On the ‘Agree to app migration’ screen:

  1. Select View policy for each app that shows as requiring your consent.
    This opens a card that:

    1. lists all the types of data the Marketplace Partner (vendor) will have access to, such as read core data or read user data.

    2. links to the Atlassian Marketplace Terms of Use, the Marketplace Partners Privacy Policy, and the Marketplace Partners Terms of Use. We strongly recommend you read this for each app you migrate.

  2. Select Confirm on this card.

  3. When you have performed the above action for all applicable apps, select Done to return to the ‘Migration Assistant home’ screen.

You can find more detailed information about this on Introduction to third-party migration agreement.

It’s important to know the following:

  • Only an app with an automated migration path needs you to agree to the migration.

  • If you agree to third-party migration, you can revoke your agreement at any time.

  • If you don’t agree to third-party migration, that app cannot be migrated using the Jira Cloud Migration Assistant.

  • If a Marketplace Partner updates an app, you will need to agree to the migration again.

  • After you agree to app migration, you can still select Revoke agreement. This will remove your agreement to third-party data migration. To agree again, click View policy and re-confirm your agreement.

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)

  • viewed and agreed to the policy for each app (on the Agree to app migration screen)

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 in order to connect to your cloud site.

  • 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

  • users and groups only (without any project data)

  • all or none of your apps

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

screenshot_choose-migration-options
  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 ‘Select projects’ 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.
      This takes you back to the ‘Choose your migration options’ screen.

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

  2. To select users and groups, select the Users and groups option.

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

    • Atlassian will not 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 adds 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 migrates 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.

        When you have made your selection, select Apply changes.
        This takes you back to the ‘Choose your migration options’ screen.

  3. To select apps for migration, select the Apps option.

    On the next screen, the Jira Cloud Migration Assistant gives you the following options:

    • All: This option allows you to choose to migrate all the apps that you marked as ‘Needed in cloud’, and which can be migrated using the Jira Cloud Migration assistant.

    • None: No apps will be selected for migration.

      When you have made your selection, select Apply changes.
      This takes you back to the ‘Choose your migration options’ screen.

When you have completed your selection on the ‘Choose your migration options’ screen, select Check for errors to continue.

Note: 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 whether:

  • 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


All checks are listed as part of the following four groups (see screenshot below):

  • App version

  • Users and groups

  • Projects, and

  • Apps

screenshot_JCMA-error-categories

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

The table below explains what the symbol next to each listed message means.

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.

Understand the ‘Check’ messages

  • App version: The table below lists errors and warning messages related to the Jira Cloud Migration Assistant version.

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.

  • Users and groups: The table below lists errors and warning messages related to users and groups.

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.

  • Apps: The table below lists errors and warning messages related to apps.

Message

Description

App assessment is incomplete

You will be taken back to the app assessment table. You should assign statuses to each of the apps in your assessment. Once the table is completed, rerunning the check will display a green tick.

Some apps marked as 'Needed in cloud' on your server are out of date

You will need to update your apps in server to a version that’s compatible for app migration. Contact your Marketplace Partner for information on app versions that are compatible for app migration.

You have not consented to app data migration

You need to consent to app migration on the ‘Agree’ screen.

Some 'Needed in cloud' apps are not installed on your cloud site

You need to install all the apps that you have chosen as ‘Needed in cloud’ on your cloud site. You can do this on the ‘Install’ screen.

Some apps marked as ‘Needed in cloud’ do not meet the migration success rate criteria

If you have selected apps marked as Stage 1 that have unknown or low migration success rates, you will be given the option to:

  • remove the apps from the migration

  • proceed to migrate with the selected Stage 1 apps

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.

screenshot_JCMA-review-your-migration

You can switch tabs to view details about what is included (users and groups / projects / apps) 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.

STOPPED

Your migration has been manually stopped. Once stopped, it can't be resumed. Any step already in progress will first need to finish before the migration is shown as fully stopped. Some projects, users, and groups may already have been migrated to your Jira Cloud site.

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

Manage your app migration

Within the migration page, you can now see an App section to monitor the progress of app migration. From this progress tracker, you can monitor the progress of the data migration of each app, and review the statuses as the migration completes.

screenshot_JCMA_app-migration-progress

The table below explains the various progress statuses for app migration.

Status

Description

SUCCESS

The app data migration is complete, and was successful.

INCOMPLETE

The app data migration is not complete

FAILED

The app data migration has failed.

RUNNING

The app data migration is still running, and is not complete.

READY

The app data migration is ready to run.

TIMED OUT

The app data migration is not complete. This is because the app has exceeded the permitted time period to migrate data. Please contact the respective app vendor for information on how to proceed with migrating data for the app.

If you have issues with any app for non-completion or failure to migrate, you should contact the Marketplace Partner (the app vendor) directly for support.

Error logs

If your migration is incomplete or has failed, you can download the error logs to understand the errors in detail. After 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 23, 2021
Cached at 2:44 AM on Sep 25, 2021 |

Additional Help