Page History
| Widget Connector | ||
|---|---|---|
|
This page describes the migration path that our customers you can follow in order to migrate Xray data from Jira Server/Data Center to Jira Cloud. If you have any questions about which approach best suits your organization, please contact our support team directly.
| Table of Contents |
|---|
| Note | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
Before migrating from Xray Server/DC to Cloud be sure you've completed the steps recommended at "Steps to a successful migration":
Ready for a Checklist? Make Sure you do not forget any step and download our Xray Migration from Server to Cloud Checklist.
Learn more at "Steps to a successful migration". Also make sure you are aware of the differences between Xray Server and Xray Cloud. Be also sure, that if you select the Xray Cloud Standard you are aware of the storage limit. If the storage offered by Xray Standard is not enough, you might consider upgrading to Xray Enterprise. |
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, of course. 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 's of integration points missing, e.g. JQL functions, Project Templates, calculated fields at agile boards (like requirement status), 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 to Xray Server and Xray Cloud.
Jira Cloud Migration
...
Assistant
Atlassian provides the
...
Atlassian provides an app called Jira Cloud Migration Assistant which will to help Jira users assess and migrate all the information from Jira an on-premises premise Jira instance (Server or Data Center) to Jira Cloud. Jira Apps can also integrate with this assistant, making it easier to migrate all the data at once.
Currently, Xray does not yet support the Jira Cloud Migration Assistant. We plan to provide this integration in early 2021.
Xray Cloud Migration Scripts
| Status | ||||
|---|---|---|---|---|
|
Although there isn't support for the Jira Cloud Migration Assistant yet, the Xray team has created some scripts that can help you migrate your data today.
These scripts are written in Python and are using the Xray REST and GraphQL APIs to fetch the Xray information from Xray Server/DC, and then import this information into Xray Cloud.
| Message Box | ||||
|---|---|---|---|---|
| ||||
The scripts will not create new issues in Jira Cloud. The Xray issues must have already been migrated. Therefore, you first need to migrate the issues using the:
|
The scripts will fill the gaps, namely:
- Test specifications
- Test Repository folders
- Relations between Xray issues/entities, e.g. Tests in Test Plans, Tests in Test Sets, Preconditions, etc.
- Test Runs
| Message Box | ||||
|---|---|---|---|---|
| ||||
Depending on the number of issues, the migration scripts can take a considerable amount of time to execute and migrate all the data. Please plan ahead and do Proof-Of-Concept into a Test Jira instance first. |
Clone or Download
These scrips are publicly available and free to use in our Github:
| Button Hyperlink | ||||||||
|---|---|---|---|---|---|---|---|---|
|
https://github.com/Xray-App/xray-cloud-mig
Please clone or download the repository and make any changes as needed.
Feel free to contribute and submit pull requests.
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 are somehow connected, 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.
| Warning |
|---|
Avoid data change during the migration, otherwise the migration might fail. |
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 directly. 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)
Gadget Configuration
Configuration of Xray gadgets will not be migrated.
Xray Notifications
Xray Notifications (events) will not be migrated. Xray Cloud does not provide this feature.
Archived Issues
Xray data belonging to the archived issues are not migrated.
In the past we've seen migrations failing due to archived projects. Xray does not have visibility/permissions into these projects so please check if you are trying to migrate archived projects.
Document Generator
Templates migrated from the Server must be revised once there are some differences between the server and cloud version.
Steps to a successful migration
Licensing
| Note |
|---|
A valid Xray app license is required to migrate Xray data, otherwise, Xray data won't be migrated to the cloud. |
Jira migration stage must be successful
Before the Xray migration stage is executed, all issues and Jira entities are migrated by Atlassian's JCMA. In order to guarantee that Xray migration is successful, all these Jira entities must be 100% migrated, without warnings. If you encounter problems in Jira's migration stage, please contact the Atlassian support team.
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/
| Note | ||||
|---|---|---|---|---|
Due to the way the "Migrate all data at once" option works on JCMA, when choosing this option a few additional steps must be taken to ensure compatibility with the Xray migration. So if you are using the "Migrate all data at once" option, please follow the steps below: - On the Server side, rename all Xray issue types like this (avoid spaces before and after):
- Still on the Server side, and only after the Xray types are renamed, create 6 dummy issue types like the list below:
After carrying out the previous operations, the issue types on the Server should look like this:
After the migration is completed, the dummy issue types created with this purpose can be deleted, and the Xray issue types can be renamed back to their original names.
|
Edit Requirement ↔ Test Link
The Issue Link used for Requirement Coverage is slightly different between Xray Cloud and Xray Server/DC. To ensure that Xray Cloud will recognise these links, the Issue Link type must be edited on Server/DC to match the link used by Xray Cloud:
- Name: Test
- Outward Description: tests
- Inward Description: is tested by
This step must be done manually prior to migrating since the Issue Links are migrated by Jira instead of Xray.
The configuration can be found in MY_JIRA_SERVER_URL/secure/admin/ViewLinkTypes!default.jspa
Some Xray custom fields must be visible
Make sure that the following Xray-created custom fields are added to the Test Execution issue screen and are visible to all users in all projects that you are migrating.
Check Issue Security Levels
The Issue Security Scheme may restrict Xray's access to issues during the migration.
If you are using Security Levels for Xray Issues ( Test, Test Set, Test Plan, Test Execution, Sub-Test Execution and Pre-Condition) - you'll have to temporarily add "Any Logged in user" to all the security levels used by Xray Issue Types or remove all the Security Schemes/Levels from those issues.
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 contains 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 begins.
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 see a table with all the instance projects listed, select all the projects for your migration and then press Validate. If there are no errors, you can 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 issues.
Example: Project Xray Test Project was selected for migration. The preflight checks found that there is a link to another project that is not part of the migration (Xray Dev Test).
We'll select the missing projects for the preflight checks and validate.
There are no more errors, meaning that the projects can be migrated together safely. We can now go back to the Jira Migration Assistant and plan our migration with both projects.
Migrate all users
It is recommended that you select the option "All users and groups from the Jira directory" when choosing which users to migrate in the Jira Migration Assistant. This is due to the way that Jira checks which users are related to a project which will not consider users assigned to Test Runs.
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.
Xray Cloud also provides a page on the app administration section with all the migration plans in progress and done. Here the Jira administrator could see the history of migration and the ongoing migration plans. Learn more about this here.
Unsuccessful Migrations
If the Xray migration is not successful during the Jira cloud migration plan, we highly recommend trying it again. Before trying again, make sure the cloud project is removed. If the issue persists, please contact our support in order to get help.
| Info | ||||
|---|---|---|---|---|
| ||||
To learn more about migration from Xray Server to Xray Cloud you might want to take our dedicated course available for free at Xray Academy: Migration from Xray Server to Xray Cloud | ||||
| Message Box | ||||
| ||||
This page only contains a brief description of how the script works. Don't forget to follow the instructions on the README file in the repository. |
