Migrate Jira Software Server or Data Center to Jira Software Cloud

This article provides an overview of Jira Cloud migrations options for Jira Align users. When migrating your connected Jira Software instance from Server or Data Center to Cloud, there are currently two options, each with different considerations and levels of effort. 

On this page:

• Roles involved
• Migration options
• Migrate with the Jira Cloud Migration Assistant (JCMA)
• Migrate with Jira Server XML site export and import
• Things to know

Roles involved

Depending on the method used, one or more individuals and teams may assist with your migration request:

• Jira Align Enterprise Solutions Specialist (ESS), or Solution Architect (SA): Assists with coordination between you, Jira Align Support, and Jira Align Engineering.
• Cloud Migrations Manager (CMM): Assists with planning, coordination, and working with members of Atlassian's migration team.
• Jira Align Support: Intakes and manages your migration request through a submitted support ticket.
• Jira Align Engineering: Assists with scripting when the JCMA migration option is used.
• Partners: May assist with planning and executing a migration, if your licenses were purchased through a partner. 
• Your team: Assists with administration and configuration in Jira Software and Jira Align. Please ensure you have contacts in your organization ready with administrative privileges for each product ready to performa any requested changes. 

Migration options

You may choose one of the following methods to migrate your Jira Software site to the cloud:

1. Jira Cloud Migration Assistant (JCMA): Atlassian recommends this method in most situations. Note that for Jira Align users, this method requires significantly more work from your staff and Jira Align teams, as the ID values and custom field names are not preserved when moving a Jira Server / Data Center instance to Jira Cloud. This includes ProjectID, BoardID, IssueID, SprintID, and more. While this method is supported by Jira Align, please note that there is an elevated level of risk due to changing ID and field values.  
2. Jira Server XML site export & import (to Jira Cloud): This method is currently recommended when using Jira Align, but will be discontinued at the end of November 2023. With this method, the underlying ID values are preserved in most cases. Please confirm your exact use case with your Jira Cloud Migrations Manager (CMM). Specifically, inform your CMM if you are migrating data to an existing Jira Cloud instance. See more information about the upcoming discontinuation of site import from the Jira team below:

   Note: Site Import for server-to-cloud migrations will be discontinued

   In November 2023, we’ll discontinue Site Import for server-to-cloud migrations.

   We recommend that all customers use the Jira Cloud Migration Assistant. The Migration Assistant includes options to migrate project-by-project or migrate all data at once.

   The new option to migrate all data at once will migrate the same data types as Site Import with a more seamless experience and higher reliability. Learn about the Migration Assistant.

   We've already discontinued server-to-cloud migrations using Site Import if you’re looking to migrate 1-1000 users. If you’re looking to migrate more than 1000 users, Site Import will be available until it is discontinued in November 2023.

   To view the number of licensed Jira Server or Data Center users, see the Viewing your licensed user count section on the Licensing your Jira applications page. For more information on this announcement, read our community post.

3. Custom: APIs and 3rd party apps are available, but will not involve the Cloud Migrations team.

Migrate with the Jira Cloud Migration Assistant (JCMA)

To migrate using JCMA, complete the following steps for pre-migration, migration, and post-migration:

Pre-migration

1. Contact the Cloud Migrations team, your Enterprise Solutions Strategist (ESS), or Solutions Architect (SA) to review your requirements, and submit a ticket to Jira Align Support. Your CMM, ESS, or SA should include:
   1. The desired migration timeline
   2. A link from the request to the MOVE tickets, to ensure both activities are included in migration tests.
2. Schedule a test environment migration with Jira Align Support to ensure they are available and involved in the required Jira Align backend work.
3. Schedule a production environment migration with Jira Align Support.
4. Set up a new connector for Jira Cloud inside Jira Align. Jira Align Support can assist with the following:
   1. The new connector service for Jira Cloud needs to be enabled by support. Note that the connector remains deactivated at this stage.
   2. Verify that the connector service account is set up on Jira Cloud and has the proper permissions for all projects and boards designated for integration with Jira Align.
   3. Confirm the connector connectivity with Jira Cloud is established. Please refer to this article to learn more about Jira Cloud connectivity. Keep the connector deactivated.
5. Provide the Jira Connector IDs in scope for migration to Jira Align Support, i.e the source (connector pointed to Jira Server / DC) and destination (Jira Cloud connector created in step #4 above).
6. Deactivate the Jira Connector in Jira Align for the old Jira Software Server or Data Center connection.
7. Confirm that Jira user email addresses are not changing as part of the Jira migration. If addresses are changing, please provide a mapping of Jira Server user email addresses to Jira Cloud user email addresses.

Migration

1. Before the migration is kicked off, provide data from your Jira Software Server/DC instance, specifically ProjectIDs, BoardIDs, IssueIDs, and StateIDs. Jira Align Support will share SQL queries required for these entities. This data is needed in a CSV format.
2. Begin the migration in Jira Software.
3. Let Jira Align Support team know once the Jira migration is complete.
4. Jira Align Support will query your Jira Cloud data to gather Jira Cloud ProjectIDs, BoardIDs, IssueIDs, etc.
5. Jira Align support will generate mapping validation files for review and request your sign-off before handing over to the Jira Align engineering team for backend updates
6. Jira Align engineering will perform backend work (backups, updates etc.)
7. Jira Align engineering runs data migration scripts.
8. Jira Align Support runs a script to clear old Jira Align - Jira Software user mapping.

Post-migration

1. Perform validation steps with test cases provided by Jira Align Support.
2. Activate the newly-created Jira Connector for the Cloud instance. 

Migrate with Jira Server XML site export and import

To migrate using site export and import, complete the following steps for pre-migration, migration, and post-migration:

Pre-migration

1. Contact the Cloud Migrations team, your Enterprise Solutions Strategist (ESS), or Solutions Architect (SA) to review your requirements, and submit a ticket to Jira Align Support. Your CMM, ESS, or SA should include:
   1. The desired migration timeline
   2. A link from the request to the MOVE tickets, to ensure both activities are included in migration tests.
2. Schedule a test environment migration with Jira Align Support to ensure they are available and involved in the required Jira Align backend work.
3. Schedule a production environment migration with Jira Align Support.
4. Perform an XML site export from your Jira Software Server / Data Center test and production instances. See this article for details.
5. Deactivate the Jira Connector currently used in Jira Align that was connected to your Jira Server or Data Center instance.

Migration

1. Perform an XML site import to your Jira Software Cloud instance.
2. Let Jira Align Support team know once the import is complete.
3. Jira Align Support runs a script to clear old Jira Align - Jira Software user mapping.

Post-migration

1. Update the Jira Connector settings in Jira Align to point to your new Jira Software Cloud instance.
2. Confirm that connector connectivity is established in Jira Cloud. See this article for details. 
3. Confirm, and if necessary, update state mappings in the Jira Connector settings. 
   Note: If there are custom fields that are integrated that do not yet exist in Jira Cloud, they will need to be created. 
4. Activate the updated Jira Connector in Jira Align.

Things to know

To ensure your migration runs smoothly with any method, please be aware of the following:

• It is important to plan your Jira Software migration in conjunction with Jira Align. We can proceed with the migration of a Jira Align connector, only once your Jira instance has been successfully migrated to Cloud. 
• Preferably, migrations are scheduled with Jira Align teams at least 1-2 months in advance.
• Our teams will try to avoid scheduling migrations during feature release weekends. 
• The Jira Connector does not support rich-text when syncing with Jira Software Cloud. If you are using Jira Software Data Center and currently syncing rich-text bidirectionally, we recommend using the Jira to Jira Align only sync direction after migration. If you want to sync bidirectionally with Jira Cloud, plain text must be used in work item fields. 
• When Jira Align Support provides mapping validation files, note the following:
  • Projects: The project(s) listed within the files will not be migrated to the Jira Software Cloud instance.
  • Issues: The issue(s) listed within the files are likely a result of not running the Jira Deleted issues report in Jira Align, prior to migration. These issues exist in Jira Align, and no longer exist in Jira Software. A solution to fix these issues is to run the Jira Deleted issues report prior to migration.