Since v3.3, Xray provides a built-in importer for Zephyr Squad for Jira.
Xray built-in importer is only available for Zephyr Squad. Zephyr Scale (previously known as TM4J) is not supported by this migration utility. All references to Zephyr in this documentation only apply to Zephyr Squad. |
As of Xray v3.3, the importer only performs inline migration of data (i.e. Zephyr's Test issues are "moved" to Xray's Test issues).
Please check, beforehand, the below versions compatibility between the Import tool and Zephyr, the necessary requirements and also the existing features and its limitations.
Xray Version | Supported Zephyr Squad Version |
---|---|
v3.3.0 - v3.6.X | v4.X.X |
From v4.0.0 | v4.0.0 - v5.5.X |
From v4.2.0 | v4.0.0 - v5.6.X |
From v5.1.0 | v4.0.0 - v6.2.X |
From v6.5.0 | v4.0.0- v9.2.0 |
The current process performs an inline migration, i.e. Tests and data is migrated to Xray and the original entities are "lost". Thus, we recommend to backup your Jira instance before performing the migration. Also, as the amount of data to migrate may be considerable large, we advise you to perform this on non-working hours. Please also make sure that users are not changing data on the project while the migration is being done. |
Below, please find a list of the support features and current limitations.
Most information will be migrated seamlessly but please check the following table in more detail.
Supported Features | Unsupported |
---|---|
Inline migration (not cloning) of:
|
|
(*) Cycle folders will be migrated to Test Executions, since the semantics on Xray are a bit different in terms of entities/organization. |
Within this section you're able to find the exact mapping of entities from Zephyr to Xray.
Zephyr entity | Xray entity | Notes |
---|---|---|
Test
| Test
|
|
Cycle | Test Plan (optional)
Test Execution, linked to the previous Test Plan
| The Test Execution created here will contain the Executions assigned directly to the Cycle, since in Zephyr you can have Executions at that level besides on each folder. Please note that...
|
Cycle's folder | Test Execution, linked to the Test Plan created earlier from the Cycle
| |
Ad-hoc Cycle | Test Plan (optional)
Test Execution, linked to the previous Test Plan
| |
Execution
| Test Run
|
All issues will be created in the project where the migration is being performed. |
Performing the migration is easy; however, it is currently limited to Jira administrators.
The migration follows a wizard like interface; after going through the steps, some additional tasks required to ensure consistency of data.
Suppose you have a project that you wish to migrate from Zephyr for Jira to Xray and that the requirements mentioned above are met.
To start the importation process:
If you see the following error message, then it's because Zephyr is using the same issue link types between Test<=>Defect and Requirement<=>Test.
Xray needs have different relations, so that is able to understand the different cases. Thus, you need to change the "Linktype for Test → Relation" to something different from the value "LinkType for Requirement → Test". For example, you can leave "LinkType for Requirement → Test" with "Relates" and change the "Linktype for Test → Relation" to "Defect".
These relations are configurable in Add-ons > Zephyr for Jira > General Configuration > Issue and Remote Links Configuration.
After ensuring that the link types are configured with distinct values, you may proceed once again with the migration process.
The importer will show you some brief information, that we advise you to read carefully.
Then, you need to choose the project where to perform the migration; this will be same where the Xray entities will be created in.
You may fine-tune the process by (un)checking some flags:
If Zephyr Cycles to Xray Test Plans and Zephyr Ad Hoc Cycles to Xray Test Plans are unchecked then no Test Plans will be created; nevertheless, Test Executions will always be created if Zephyr Executions exist.
You need to map Zephyr's Test Statuses to Xray counterparts.
Likewise, you also need to map Zephyr's Test Step Statuses.
A final confirmation dialog presents information about the total number of Xray entities that will be created.
At the end, a brief summary is shown mentioning the total number of Xray issues created and any warnings that occurred during the process.
Please have a look at the following section for some additional steps before concluding the migration process.
After migrating data from Zephyr to Xray you will need to perform some additional operations to recalculate the status of Tests and the coverage of the related requirements.