Since v3.3, Xray provides has provided a built-in importer for Zephyr Squad for Jira.

...

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

Table of Contents

Before using the Zephyr Import tool

Please check, beforehand, the below versions' compatibility between the Import tool and Zephyr, the necessary requirements, and also the existing features and its limitations.

Versions compatibility

Requirements before proceeding

• Zephyr and Xray should be both installed.
• Project, where migration is being done, must have Xray issue types types (at least the Tests, Test Executions, and Test Plans):
  • You may use the "Add Xray Issue Types" action shortcut available in on the project settings page.
• Requirement issue Issue types used in Zephyr must be configured in Xray:
  • All the different issue types Issue Types that Zephyr Tests cover should be configured in Xray's Issue Type Mapping settings.
• Defect issue types Defect Issue Types used in Zephyr must be configured in Xray:
  
  • All the different issue types Issue Types that are being used as defects in Zephyr should be configured in Xray's s Issue Type Mapping settings.
• Create similar Test Statuses and Test Step Statuses in Xray; this is not mandatory but may ease the process, which will always ask you to make the mapping between Zephyr statuses and Xray counterparts.
• Make sure Zephyr is using different issue Issue links between Test<=>Defect and Test<=>Requirement, by going into Zephyr's configuration settings.
• Do not change, create, or delete any issue in the Project while the importation is running.
• The only mandatory field fields in Xray's Test, Test Execution, and Test Plan should be the issue Issue Summary and issue Issue Reporter.
• Make sure that the Jira workflow states , that are being used by "Zephyr Test" issue Issue type, are editable. Click here for the the official Jira documentation on this subject.
• We strongly recommend you to make a backup of your Jira instance before migrating the data.

...

...

How it works

Within this section, you're able to find the exact mapping of entities from Zephyr to Xray.

...

Migrate the Zephyr Test Set and Execution Custom Fields

When importing a project, Xray performs a detailed check of the possibility of migrating custom fields. This verification follows the criteria and steps described below:

1. Recreation and Reuse of Fields
   • Xray will recreate the migrated custom fields, keeping the same name, type, and options where applicable.
   • If the custom field to be migrated already exists in Xray with the same name and type, it will be reused, avoiding duplications.
     
2. Recreating Fields with the Same Name and Different Types
   • If a custom field with the same name already exists in Xray but with a different type, Xray creates a new custom field by prefixing it with Zphr_Xray_<field_name>
   • This process is recursive. For example, when migrating the cf_1 field (a toggle in Xray), and if a single-line text type cf_1 already exists in Xray, Xray will attempt to create Zphr_Xray_cf_1. If Zphr_Xray_cf_1 already exists as a number type field, the system will continue applying the prefix (Zphr_Xray_Zphr_Xray_cf_1) until it can create a field with the desired name and type.
     
3. Field Type Conversion
   • During migration, Zephyr Checkbox type fields will be converted to Multiselect. All other field types are matched directly, retaining their original type.
4. Treatment of Options in Existing Fields
   • When a Zephyr field has options and this field already exists in Xray, the system will add the missing options to the existing options list in Xray, without overwriting the current options.
5. Warning in Case of Excessive Fields (Only applied to Test Set Custom fields)
   • If the sum of existing custom fields in Xray and new Zephyr fields exceeds the maximum allowed limit (6), Xray will cancel the migration process and notify the user of the exceeded limit.

How to use

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 are required to ensure consistency of data.

...

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 to have different relations , so that is able to it can understand the different cases. Thus, you need to change the "Linktype for Test → Test → Relation" to something different from the value "LinkType for Requirement → Requirement → Test". For example, you can leave "LinkType for Requirement → Requirement → Test" with "Relates" and change the the "Linktype for Test → Test → Relation" to "Defect".

These relations are configurable in Add-ons > Zephyr for Jira > General Configuration > Issue and Remote Links Configuration.

...

Then, you need to choose the project where to perform the migration; this will be the same where the Xray entities will be created in. 

You may fine-tune the process by (un)checking some flags:

• Links between requirements and tests to respective Xray Issue Link Type used for requirement coverage: creates the link Xray uses for tracking coverage between Tests and requirements; by default, Xray used the "testsTests" issue Issue link typeType.
  
• Zephyr Cycles to Xray Test Plans: creates Test Plans based on Zephyr Cycles.
• Zephyr Ad Hoc Cycles to Xray Test Plans: creates Test Plans based on Zephyr Ad Hoc Cycles.

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. 

...

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.

1. reset Reset the "TestRunStatus" custom field of the migrated Tests
   1. you You can use the link provided in the final screen mentioned earlier for to quickly obtaining obtain the created Tests; you will be redirected to the Issues search page page.
      
   2. save Save this search as a filter (you will need it afterwards).
      
   3. do Do a bulk change operation on the Test issuesIssues.
      
      
      
   4. reset Reset the TestRunStatus custom field.
      
2. reset Reset the "Requirement Status" custom field of the requirements linked to the migrated Tests:
   1. use Use the testRequirements JQL function using use the name of the previously saved filter as an argument.
      
   2. do Do a bulk change operation on the requirement issuesIssues.
      
   3. reset Reset the Requirement Status custom field.