Use the Jira Cloud Migration Assistant to migrate from server to cloud

descriptionStep-by-step instructions on how to use the Jira Cloud Migration Assistant to move your projects from Jira Server to Jira Cloud.

The Jira Cloud Migration Assistant is an app that helps you easily move projects, users, and groups from 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.

When to use the Jira Cloud Migration Assistant

Use the Jira Cloud Migration Assistant to migrate only the projects you need from server to cloud. You can migrate your projects to a new or existing cloud site. The Jira Cloud Migration is compatible with Jira Server and Jira Data Center

Use our resources to get started and plan your migration from Jira Server to Cloud. You can then choose to migrate your data at a time that suits you.

The Jira Cloud Migration Assistant does not migrate Jira Service Desk projects or Confluence spaces. To migrate your Confluence spaces use the Confluence Cloud Migration Assistant.

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.

  • It doesn’t overwrite or delete any data. 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.

  • Some data is linked. When you migrate multiple times we will attempt to link your data to avoid duplication. Learn about how we link data
  • Jira Core and Jira Software data only. With the latest version of the Jira Cloud Migration Assistant, you can migrate Jira Core or Software projects with most fields supported. It does not yet support Jira Service Desk or some custom fields. Check out the latest updates for what can and can’t be migrated.

  • All users and groups every time. Each time you migrate we will copy all your users and groups and send them to your cloud site. This is so we can make sure that issues and their fields get migrated correctly. If a user already exists in your cloud site, we will not re-migrate it. You will get the option to migrate your users without Jira product access. This will enable you to run a test without adding users to your bill. Review our recommendations for migrating large numbers of users

  • Classic projects only. Migration to Jira Cloud next-gen projects is not supported. 

It’s best to check what data Jira Cloud Migration Assistant will be capable of migrating 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.

Install the Jira Cloud Migration Assistant app

To install the app on Jira versions 7.6 or newer:

  1. In Jira Server or Data Center go to SettingsManage 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.

Once installed, you can access the migration assistant by going to Settings > System > look for the Import and Export category > select Migrate to cloud.

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 domain: atlassian.com

Assess and install your apps before migrating

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, then installing apps on your cloud site before migration removes the risk of your apps blocking your migration at a crucial time.

Selecting the option Assess your apps will allow you to see which apps you have installed on your server. Once you've audited what is installed, you can use the table to assess your apps, in preparation to migrate.

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

Set up and run your migration

To set up a new migration, select Manage your migration. You'll then be able to Create a new migration

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

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.

1. Connect to your destination Jira Cloud site

First, you’ll be asked to add a name for your migration and choose which cloud site you would like to migrate to. 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



2. Choose what you'd like to migrate

You can choose to migrate projects, users and groups, or, users and groups only (without any project data). Before choosing what to migrate, make sure you check out what is and isn't migrated with the migration assistant.



You’ll then need to tell us if you want your users to have access to Jira when you migrate. The migration assistant doesn't send any invitation emails, even if you choose to give your users Jira access. If you choose to give Jira access, your users will be individually granted the same access as they have in server. Read through the next section on users and groups for more information. 


Users and groups

The first time you migrate, we will migrate all your users and groups. Every migration after the first we will link data to the existing user in cloud. This includes Jira Core and Jira Software users, as well as Jira Service Desk agents. We need to migrate all your users to make sure things like issues, fields, comments, and mentions stay active.

Deleted users or inactive directories

Any deleted users or users in inactive directories that are referenced in your Jira data will appear as Former user after migration. If you need to migrate the references to these users, reactivate them (or the directory) before migrating.


You will have the option to give your users the same Jira access as they had in server, or to not give your users any Jira access. If you choose not to give them access, you can manually grant access to your cloud site later on.

The first time you migrate, you will need to review and approve group permissions after migrating. When you approve group permissions any active users in your cloud site will be added to your bill.

We won’t send an invitation to your users even if you choose to give your users access during the migration. To invite your users you can choose to send an invitation from the Administration space after you have migrated, or send a link for them to log in themselves.

Other things to be aware of 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

  • 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 or calculate the cost with our pricing calculator. By default, cloud subscriptions are billed on a monthly basis however you can choose annual billing if you prefer. 

  • If you're intending to use an external identity provider in cloud, make sure you've read the guidance on migrating users and groups
  • 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. Learn about how users are managed in cloud.

  • Learn about how groups and permissions are migrated with the migration assistant. 

  • Global settings and global site permissions are not migrated with this tool. You’ll need to set these manually before or 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 and has product access in your server site, they will be granted product access through the migration process.

Projects

If you want to migrate all or some of your projects choose Select project from the options. You will then be able to select which projects you want to migrate. If you aren’t migrating any projects you’ll be taken straight to check for errors.



Select the project you want to add to your migration. 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. 

When you've chosen all your projects, select Add to migration.

3. Check for errors

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

  • users have valid email addresses

  • users have unique email addresses

  • groups will be merged
  • projects will clash 
  • the migration assistant is up to date

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


(tick) If there is a green tick then the check has passed.

(warning) If you get a warning sign then you can continue, but you need to be aware of a potential issue.

(error) If a check comes back with a red error then you will need to resolve the error before you can run your migration.


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


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

4. Review your migration

This is the final step in setting up your 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.

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.



Status definitions:

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. 

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. 



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.

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

  • 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 5000 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 Jul 21, 2020

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.