This page describes the migration path that you can follow in order to migrate Xray data from Jira Server / Data Center to Jira Cloud. In case of any questions about which approach best suits your organization, please contact our support team directly.

Server/DC vs Cloud - Product Comparison

If you are looking to migrate from Jira Server/DC to Jira Cloud, you need to consider the differences between Xray Server/DC and Xray Cloud. These differences might affect how your users work and interact with Xray.

The ideas, goals, and major features are the same. However, while there is great similarity between them, there are a few subtle differences between the two versions, this is mainly due to:

Jira architecture - The way apps work in Server and Cloud is completely different. In Server, apps can integrate with many aspects of Jira, while on Cloud, there are a lot of integration points missing, e.g. JQL functions, Project Templates, etc
Product Age - Xray Cloud is a newer product. Therefore, some of the features are not yet present (e.g. Automated Step Library, Historic Test Coverage report), although we plan to include these features in future releases. Also, we took the opportunity to improve some features (e.g. Project Level Settings).

For a full comparison between the Server/DC and Cloud versions of Xray, please refer to Xray Server and Xray Cloud.

Jira Cloud Migration Assistant

Atlassian provides the Jira Cloud Migration Assistant to help Jira users assess and migrate from an on-premise Jira instance (server or data center) to Jira Cloud. However, Atlassian has not yet included apps like Xray in this tool.

Our team has worked with Atlassian to make Xray available within the official Migration Assistant tool and we hope Atlassian will launch this expanded version of the Migration Assistant.

Before going any further, check the official Atlassian documentation and procedure:

https://support.atlassian.com/migration/docs/use-the-jira-cloud-migration-assistant-to-migrate/

https://support.atlassian.com/migration/docs/jira-pre-migration-checklist/

Migrating Xray data through Jira Cloud Migration Assistant

Any Xray related projects that have relations between them must be migrated together within the same migration, otherwise, any Xray link between the projects will not be present in the Cloud after the migration. E.g. all the Tests in the Test Plans of Project A must be part of the migrated Projects.

Known Limitations

Issue History and Test Run Activity

Due to the textual nature of the data in the activity logs, the entries are mostly copied as-is. The language, phrases and markups may differ from Server to Cloud.

Migration drift not supported

All the linked data must be migrated together so data integrity can be guaranteed on the Cloud.

Automated Step Library

Not supported by Xray Cloud and will not be migrated.

Cucumber settings

Will not be migrated to cloud. (Miscellaneous settings section)

Archived Issues

Xray data belonging to the archived issues are not migrated.

Steps to a successful migration

Edit Issue Type Names

The name of the issue types needs to be the same on both Server and Cloud before starting the migration.

The Issue Type Precondition/Pre-Condition may have to be changed as it is named differently in the Server and Cloud versions of Xray.

https://support.atlassian.com/jira-cloud-administration/docs/add-edit-and-delete-an-issue-type/

Preflight Checks

These checks are meant to help you plan your migration by taking into consideration Xray related constraints. The checks will let you know if the group of Projects that you are migrating contain any Xray links to data outside of these Projects.

If there are any such links, Xray will let you know which projects should be added to the migration to avoid ending up with missing links in the Cloud instance. This check should be done before any migration is started.

The preflight checks are available when the Jira Cloud Migration Assistant is installed and a version of Xray supporting the migration to Cloud is also installed. The page can be found in the Administration → Manage Apps → Xray → Cloud Migration. Here you should fill all the projects for your migration and then press Validate. If there are no errors, you may now leave this page and proceed with your migration through the Jira Migration Assistant. If there are any errors you can see the details and steps to fix the issue.

Xray 4.3 > Jira Cloud Migration Guide > image2021-4-7_16-52-21.png

Project XT was selected for migration and the preflight checks found that there is a link to another project which is not part of the migration (XDTP).

We now add the missing project to the preflight checks and validate.

Xray 4.3 > Jira Cloud Migration Guide > image2021-4-7_16-55-18.png

There are no more errors meaning that these two projects can be migrated together safely. We can now go back to the Jira Migration Assistant and plan our migration with both projects.

The pre-flight checks feature was created on Xray app to help customers understanding what must be migrated based on the project they have in mind to migrate. The cloud migration assistant will provide this feature after the EAP, by that time, Xray will move the feature to be fully integrated with the assistant itself. As a consequence of this, the pre-flight check option will be removed from the Xray administration section menu.

The Migration Process

The Xray migration starts right after the Jira migration. While Xray is migrating projects, the Xray app screens/actions will be disabled until the end of the migration. Those screens will show a warning and an action to allow the user to see the current progress of the migration. This progress shows details about what is being done.

(add a screen shot here.)

The Xray cloud also provides a page on the app administration section with all the migration plans done. Here the Jira administrator could see the history of migration and the ongoing migration plans as well.

Unsuccessful Migrations

If the Xray migration is not being done as expected during the Jira cloud migration plan, we highly recommend trying it again but first, the cloud project must be removed. If the issue still happens please contact our support in order to get help.