• Products
  • Documentation
  • Resources

Use Jira Cloud Migration Assistant to migrate (legacy)

This documentation is undergoing changes

Although we’ve marked this page as legacy, the content is accurate and you can still use it, especially if you prefer to see all the information on a single page. If you’d like to see the new experience, where the content is divided into a more granular sequence and clear steps, go to Jira Cloud Migration Assistant.

Prevent migration failure by upgrading to Jira Cloud Migration Assistant 1.7.3 or higher

We are ending support for all older versions of Jira Cloud Migration Assistant.

You won’t be able to use the following versions:

  • Jira Cloud Migration Assistant 1.7.1 and lower

We are improving our migration tooling and expanding their existing capabilities. For a smoother and more stable migration experience, we recommend upgrading to the latest version of Jira Cloud Migration assistant within six weeks of it release.

Learn more about this announcement and how to upgrade.

For any further details or technical concerns, contact us.

The Jira Cloud Migration Assistant helps you migrate your Server and Data Center data to a new or existing Cloud site. You can migrate:

  • Jira Software

  • Jira Service Management

  • Jira Work Management (formerly Jira Core)

  • Advanced Roadmaps plans with linked issue sources (projects and single-project boards). Any plans with issue sources as filters and cross-project boards is not migrated. Learn more about what is migrated and what isn’t

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.

If you are new to migration, use our migration guide to prepare and plan for your migration from Server to Cloud. 

Before you migrate

Here are some key things to be aware of before using this app:

  • 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 don’t recommend this migration strategy because you will need to do a large amount of manual post-migration cleanup work.

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.

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

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

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.

To find the migration assistant:

  1. Go to Settings > System.

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

Note

JCMA Migration Assistant Homescreen

There are four steps to create your migration path:

  1. Assess your apps

  2. Prepare your apps

  3. Review all email domains

  4. Migrate your data

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

If you have no apps to migrate, you can skip to step 3.

 

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.

Learn more about the stages of apps with 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-assess-your-apps

Learn 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

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

  • Connect to your cloud site

  • Install your apps

  • Agree to app migration

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

2.a. 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.

2.b. Install your apps

  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.

2.c. Agree to app migration

When you perform an app migration, the data moves from each Server app to its Cloud version on your Cloud site. The Marketplace Partner (app 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 detailed information the third-party migration agreement in the section that follows.

Third-party migration agreement

When an app migration is performed, the migration moves the app data from each Server app to its Cloud version on your Cloud site. This can take place alongside a migration of a Confluence or Jira instance, or can be run alone.

The Marketplace Partner (vendor) that built each app has created a migration pathway to move the data, via the Atlassian platform known as the App migration platform.

It is very important to understand that the Marketplace Partner (vendor), who developed a particular app, will be performing the data migration. Atlassian has developed the App migration platform to be the conduit between the Marketplace Partner and yourself as the app user.

Data security and allowed access scopes

The App migration platform allows Server apps to export your app data to Cloud, and to access Confluence and Jira mappings. The access is very tightly controlled and restricted to a list of data types, or access scopes.

  • The Marketplace Partners who built the apps installed on your Server instance, have documented the access scopes required to migrate the apps.

  • These access scopes are surfaced in the Cloud Migration Assistant so that you can consent to the Marketplace Partner accessing this data.

You can find the specific information and list of access scopes on the Security and Access scopes pages in Atlassian’s developer documentation. For more context, read the data privacy guidelines for developers that Atlassian recommends.

Agreeing to a migration

Each Marketplace Partner app has different access scopes. You must review and agree to each Marketplace Partner agreement before they can access your data to migrate.

Atlassian’s Cloud Terms of Service and Privacy Policy do not apply to any of the apps installed in your Cloud site. Each Marketplace Partner (previously known as app vendors) writes their own privacy policy and terms of use. You must review and agree to each Marketplace Partner privacy policy and terms of use before they can access your data to migrate.

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.

Agreeing in the migration assistant

The following image shows the agreement screen included in the migration assistant for this EAP.

JCMA_app-migration_agree-screen

Some quick notes on this table:

  • Atlassian’s Cloud Terms of Service and Privacy Policy do not apply to any apps installed on your Cloud site.

  • By installing apps on your Cloud site, you agree to the Atlassian Marketplace Terms of Use and the Marketplace Partners privacy policy and terms of use.

  • You should review a privacy policy in detail before installing an app in your Cloud site. 

  • You can find the privacy policy and terms of use for each app on the app listing in Atlassian Marketplace.

App migration agreement status messages

Status message

What you need to know

You have agreed to third-party automated app data migration for this app.

This app is ready to be migrated.

You must review and agree to this data migration policy, or your app data cannot be migrated.

You must review the supplied Policies and Terms of Service before this app is ready to be migrated.

The policy you agreed to have been updated. Review changes and agree again before your app data can be migrated.

If a Marketplace Partner makes any changes to their policy, you’ll need to review the policy again and agree. Otherwise your app data would be migrated under conditions you hadn’t agreed to.

This app does not require an app data migration to function on your cloud site. Install it, migrate your core data and you’re ready to go.

This means there is no data contained in the app to be migrated from Server to Cloud. You can just install the Cloud version on your Cloud site.

An automated migration path between alternative app selections is not available. Contact the app vendor for migration support.

If you chose an alternative app on the app assessment table to replace an app you have on your Server, there can’t be a migration path. You’ll need to contact both Marketplace Partners if you want to migrate data from one app to another .

This app does not have an automated migration path. Contact the app vendor for migration support.

The vendor has not yet built a migration path for their apps. You should still contact the vendor, as they are likely have a manual migration process that you can follow.

This app version does not support app data migrations. You must update your Server app version in order to agree to the relevant app migration policy.

The app you have installed supports an app data migration, but you need to update your Server app to a version that supports app data migration.

 When you click View policy, you will see a modal with the following details on it:

JCMA_app-migration-agree-modal

The modal above lists the following:

  • Access scope of that particular Marketplace Partner

  • All the information they will need to access/see in order to migrate this app

There are three links in each modal:

  • Atlassian Marketplace Terms of Use (the same for each app)

  • The Marketplace Partner Privacy Policy (unique to each app)

  • The Marketplace Partner Terms of Use (unique to each app)

We strongly recommend you read each one for each app.

Once this is ready, you have completed your app assessment. Select Done to return to the homepage.

3. Review all email domains

Before you migrate, you must review your users' email domains to prevent migrating users from email domains you don’t recognize or trust. This improves the security of your Cloud site. The domains you select here will be applied to all your future migrations.

You can start reviewing your domains from the Migration Assistant home screen. Select Review under the Review all email domains card. This will take you to the Review all email domains screen.

This screen lists all your email domains with the number of users in each domain. You need to mark all your domains as trusted. This ensures that you migrate users only from the email domains you trust.

The list of emails domains for:

  • Jira Software: Shows the email domains of your licensed users

  • Jira Service Management: Shows the email domains of your licensed users (including agents and administrators)

  • Jira Software and Jira Service Management: Shows the email domains of your licensed users (including agents and administrators)

For each listed domain, you need to make one of the following three decisions:

Decision

When do you make this decision?

What you need to do?

Trusted domain

You’re sure that this domain is trusted and doesn’t have any unauthorized users.

You can continue with your migration.

Not trusted domain

  • You don’t recognize this domain and the emails created by this domain.

  • You don’t trust the organization that creates emails using this domain.

You'll need to modify users from the domains you don't trust. Learn how to review users to trust email domains

 

No decision made

You're not sure if the domain is trusted or not.

Check if the domain is trusted and doesn’t have any unauthorized emails. Once you’ve verified your domain, you can mark it as a Trusted domain and continue your migration.

You’ll need to review all your email domains and mark them as trusted. You can continue your migration without trusting all the domains, but you won’t be able to run the migration.

Once you've marked all your domains as trusted, select Done to complete the domain review and return to the Migration Assistant home screen.

If you've any previously saved migrations:

  1. From the migration dashboard, you can either create a new migration or run an existing migration. A message appears telling you to review your email domains.

  2. Select Review domains to review all your email domains and mark them as trusted.

  3. Select Continue without reviewing if you want to review your domains later. You can continue without trusting all the domains at this stage, but you won’t be able to run the migration.

4. Assess and prepare your users

In Cloud, all users must have valid and unique email addresses. Any emails that don’t meet these requirements will block your migration. In this step, you can assess your users and identify those with invalid or duplicate email addresses. Afterwards, you’ll have a chance to decide how fix problems with these emails so you can migrate.

To find and fix invalid and duplicate email addresses:

  1. On the Migration Assistant home screen, find the Assess and prepare your users card.

  2. Select Begin assessing. You’ll be moved to a page with empty results.

  3. To start the assessment, select Begin assessing.

Once the assessment is complete, you’ll see results similar to the following example:

Assessment results with the number of invalid and duplicated email addresses.

You can then view the details to identify important users that should be updated in your user directory, and apply one of the automatic options to fix remaining email addresses during migration.

Learn more about assessing and preparing users

5. Migrate your data

The key steps to set up and run your migration from Server to Cloud are:

  • Connect to your cloud site

  • Select a migration option

  • Run pre-migration checks

  • Review your migration

  • Migrate

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.

  3. Review the information on How it works screen, and then select Connect to cloud to continue.

5.a. Connect to your cloud site

  1. Enter a name for your migration.

  2. Choose the Cloud site you would like to migrate to.

  3. To continue, select Choose migration options.
    This takes you to the 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 Jira site import instead.

5.b. Migration options 

The Jira Cloud Migration Assistant now supports ‘all data at once’ migrations, in addition to the existing project-by-project migration capability. For more information on this announcement, read our Community post.

Migrate all data at once

You can migrate all data in a single migration. This includes app data. You can only use this option when no projects exist in your Cloud site.

Choose what to migrate

You have the flexibility to choose what you want to migrate. This includes options to pre-migrate users and attachments. This takes you to the ‘Choose your migration options’ screen.

Recommendation about migration options

  1. If you’re planning to pre-migrate data, for example, users and attachments, we recommend you:

    1. First, select the migration option Choose what to migrate. This gives you the flexibility to choose what you want to migrate, including options to pre-migrate data.

    2. After you’ve pre-migrated data, select the migration option Migrate all data at once to migrate all your data in a single migration.

      1. The Migration Assistant won’t re-migrate users but it will link project data to the email addresses in Cloud.

      2. The Migration Assistant will recognize any attachments that have already been migrated and skip over these. It will still migrate new attachments, and also remove the links for any attachments that have been deleted. 

Migration options: migrate all data or choose what to migrate

6. Migrate all data at once

Before you begin

This option requires an empty cloud site. You can:

  • delete existing projects from Jira Cloud. Learn more

  • start with an empty cloud site or we’ll give you an option to overwrite existing data in your cloud site. You’ll be required to create a backup for Jira Cloud (within the last 14 days) before overwriting data.

What is migrated and what isn’t migrated

See ‘Migration option: Migrate all data at once’ on What gets migrated with Jira site import.

If you chose to merge duplicated accounts on migration, the fixes won’t be applied when you migrate all data at once. All other fixes for duplicated and invalid accounts will be applied when you migrate all data at once. To make sure duplicated accounts are merged on migration, use the ‘Choose what to migrate’ option.

Supported Jira Cloud Migration Assistant version

Jira Cloud Migration Assistant 1.7.7 and higher.

To migrate all your data, on the Migration options screen, select Migrate all data at once. This takes you to the Pre-migration checks screen.

6.a. Run pre-migration checks

In this step, the Jira Cloud Migration Assistant will review your migration and check if there are any errors or warnings. For example, the checks include:

  • whether projects exist in your Cloud site. Migrating all data at once is only available when no projects exist in your Cloud site.

  • assessing your data size and complexity. If your data is too large or too complex, we may recommend reducing your data size or contacting support.

  • whether you have projects in trash. Migrating all data at once will permanently delete projects from trash. You won't be able to recover the deleted projects. If you don’t want your projects deleted from trash, select the migration option ‘Choose what to migrate’.

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

6.b. Review your migration

You can view details about what is included (users and groups / projects) in your migration.

If everything looks correct and you want to start your migration, select Run. If you would like to start your migration later or you still have errors to fix, select 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.

6.c. Manage and run your migrations

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

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 and progress for each stage of your migration.

Migrating all data at once doesn’t include a link to download error logs from the details page.

Post-migration checks

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.

6.d. Known issues

MIG-1276

7. Choose what to migrate

On the Migration options screen, when you select Choose what to migrate, this takes you to the Choose your migration options screen.

7.a. Choose your migration options

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

  • all Advanced Roadmaps plans and its linked projects or none of your Advanced Roadmaps plans

  • projects, users and groups

  • cross-project boards and filters

  • users and groups only (without any project data)

  • customers

  • all or none of your apps

Cards showing data that can be added to a migration plan, for example projects.

If you are migrating Advanced Roadmaps

  • We recommend you migrate your plans first and then migrate all other projects, users, groups, customers, and apps separately. Learn more about migrating Advanced Roadmaps plans

  • Make sure you have Jira Work Management added in your destination Cloud site if you have Jira Work Management in your Server instance. Depending on the number of Jira Work Management users you've in your Server instance, you may need to upgrade to the Jira Work Management Standard plan.

  1. To select Advanced Roadmaps plans, select the Advanced Roadmaps plans option.

    1. On the Select Advanced Roadmaps plans screen, you’ll see the following options:

      • All: Migrate all your Advanced Roadmaps plans that has linked projects, boards, and filters. We don’t migrate filters.

      • None: No Advanced Roadmaps plans will be selected for migration.

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

  2. To select projects, select the Projects option. (If you aren’t migrating any projects, you can proceed to select users and groups.)

    • 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 projects into multiple migration batches. This will allow you to have smaller maintenance or downtime windows.

    • You can also migrate project attachments before migrating other project data. In general, the more attachments you have, the more downtime you can expect. We recommended that you migrate attachments first. This can help reduce the time window for the remaining project data migration.

      • By default, all project data (configurations, issues, and attachments) is selected for migration. To break your attachment and project data migration into different stages, select Attachments only. Learn how migrating attachments separately reduces downtime You will then need to migrate All project data in a later migration. This will restore the links between issues and their attachments. The migration assistant will recognize any attachments that have already been migrated and skip over these. It will still migrate new attachments, and also remove the links for any attachments that have been deleted. 

    • Apart from other projects, you can also migrate archived projects. Search or use the filter to locate the archived projects. You can also use the filter to locate inactive projects (haven’t been updated in the last 30 or 90 days).

      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.

  3. To select cross-project boards and filters, select the cross-project boards and filters option.

    • You can migrate only cross-project boards and filters related to selected projects. If you haven’t selected all the projects that are linked to cross-projects boards and filters, the cross-project boards and filters will still be migrated to cloud. However, they’ll work only if all the linked projects are migrated to cloud.

    • You can also migrate all cross-project boards and filters present in your server instance

    • You can also choose None to skip cross-project boards and filters migration. This will not include cross-project boards and filters for migration, unless they are an issue source for any Advanced Roadmaps plans you’ve included in your migration.

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

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

    • The Jira Cloud Migration Assistant also migrates the Jira Service Management agents and project administrators via the User and groups option.

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

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

  5. After you have selected projects, you will have the option to select Jira Service Management customers. The Customers option is available only if you have Jira Service Management in your Server instance.

    • You can either select all Jira Service Management customers or a subset of customers related to specific projects. Learn more about customer migration

    • We will not send any emails to customers when they are migrated to Cloud.

    • You can select the No customers option to not migrate customer accounts. This option is available when there are only Jira Software projects added or no projects are added to the migration.

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

On the next screen, you’ll see the following options:

  • All: 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 are done with choosing migration options, select Run pre-migration checks 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 the data by email address rather than re-migrating them. Check out our Learn more about 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. Learn more about the licensing options 

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

7.b. Pre-migration checks

In this step, the Jira Cloud Migration Assistant will review your migration and check if there are any errors or warnings. All checks are listed as part of the following groups:

  • System

  • Users and groups

  • Customers

  • Projects

  • Cross-project boards and filters

  • Advanced Roadmaps plans, and

  • Apps

Learn how to troubleshoot your migration


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

A few examples of checks include whether:

  • the migration assistant is up to date

  • users have valid email addresses

  • users have unique email addresses

  • groups will be merged

  • customers have valid email addresses

  • customers have unique email addresses

  • projects will clash 

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

  • app assessment is complete, app versions are up to date, and apps meet migration success rate criteria

7.c. 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, select Run. If you would like to start your migration later or you still have errors to fix, select 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.

7.d. Manage and run your migrations

Your saved migration will be listed on the migration dashboard, where you can View details, Run, Copy, Edit, and Delete 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.

Migration dashboard

You can also Archive a completed migration.

Archive a migration

You can view archived migrations from the dashboard.

View archived migrations

 

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.

COMPLETE

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. 

Migration complete

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. You can 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. Learn how to troubleshoot your migration

Migration failed

After you migrate

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.

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.

  • Use JQL and quick filters to check 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.

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. Learn more about board filters

More information and support

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

Support for Atlassian Server products ends in February, 2024. Learn more about the Server end of support timeline.

Additional Help