--- title: "Importing / Migrating Data from Zephyr for Jira" canonical: "https://docs.getxray.app/space/XRAY/301668108/Importing%20%2F%20Migrating%20Data%20from%20Zephyr%20for%20Jira" format: markdown --- > Macro (ui-expand) > > > Macro (toc) # Introduction Since v3.3, Xray has provided a built-in importer for [Zephyr Essential for Jira](https://marketplace.atlassian.com/apps/1014681/zephyr-essential-test-management-for-jira?hosting=cloud&tab=overview). > ⚠️ - Xray built-in importer is only available for Zephyr Essential (previously known as Zephy Squad). Zephyr Scale (previously known as TM4J) is not supported by this migration utility. References to Zephyr in this documentation only apply to Zephyr Essential. > ⚠️ - Go here to see how to [migrate from Zephyr Scale to Xray DC/Server](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301472768). As of Xray v3.3, the importer only performs inline data migration (i.e., Zephyr's Test Issues are moved to Xray's Test Issues). # Before Using the Zephyr Import Tool Please check beforehand whether the versions below are compatible with the Import tool and Zephyr, whether they meet the necessary requirements, and whether they have any existing features or limitations. ## Versions Compatibility | **Xray Version** | **Supported Zephyr Essential 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 | | From v7.9.0 | v4.0.0 - v9.6.2 | | From 7.13.0 | v4.0.0 - 10.1.3 | ## Requirements Before Proceeding with the Migration > ℹ️ We strongly recommend you create a backup of your Jira instance before migrating the data. - Zephyr and Xray must be installed. - The Project, where migration is being done, must have Xray issue types (at least the [Tests](https://getxraydocs.atlassian.net/wiki/display/XRAY790/Test), [Test Executions](https://getxraydocs.atlassian.net/wiki/display/XRAY790/Test+Execution), and [Test Plans](https://getxraydocs.atlassian.net/wiki/display/XRAY790/Test+Plan)): you may use the *Add Xray Issue Types* action shortcut, which is available on the [Project settings](https://getxraydocs.atlassian.net/wiki/display/XRAY790/Project+Configuration) screen. - Requirement Issue Types used in Zephyr must be configured in Xray: all the different Issue Types that Zephyr Tests cover should be configured in Xray's [Issue Type Mapping settings](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301473147). - Defect Issue Types used in Zephyr must be configured in Xray: all the different Issue Types that are being used as defects in Zephyr must be configured in Xray'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 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 fields in Xray's Test, Test Execution, and Test Plan must be the Issue Summary and Issue Reporter. - Make sure that the Jira workflow states that are being used by the Zephyr Test Issue Type are [editable](https://confluence.atlassian.com/jirakb/how-do-i-edit-closed-issues-779160787.html). > ℹ️ The current process performs an inline migration, i.e. Tests and data, are migrated to Xray, and the original entities are lost. Thus, we recommend backing up your Jira instance before performing the migration. > ℹ️ > ℹ️ Also, as the amount of data to migrate may be considerably large, we advise you to perform this migration during non-working hours. Please also make sure that users are not changing data on the project while the migration is being done. ## Features and Limitations Below there's a list of the supported features and current limitations. Most information will be migrated seamlessly, but please check the following table. | **Supported Features** | **Unsupported** | | --- | --- | | Inline migration (not cloning) of:
- Test and [Test Steps](https://getxraydocs.atlassian.net/wiki/pages/viewpage.action?pageId=49152976). - Test and Test Step attachments. - Links between Tests and Defects/Requirements. - Cycle (including Cycle folders*). - Executions: - Defects (Global and Step level). - Attachments (Global and Step level). - Result (Global and step level). - Comments (global and step level). - Assignee. - Custom fields in the Test Steps and on the Execution. | - All Zephyr executions from the Ad-hoc cycle; only the last Execution is migrated. - Activity information. - Test Statuses and Test Step Statuses configurations. - Cycle folders as such*. | | (*) Cycle folders will be migrated to Test Executions since the semantics on Xray are a bit different in terms of entities/organization. | # Operations Within this section, you're able to find the exact mapping of entities from Zephyr to Xray. ## Mapping Information | **Zephyr Entity** | **Xray Entity** | **Notes** | | --- | --- | --- | | Test:
- Steps. - Attachments. | Test:
- Steps. - Attachments. | If empty, the *Step* column will be filled with ** | | Cycle | Test Plan (optional):
- **Summary:** - - **fixVersion**: version assigned to Cycle
Test Execution (linked to the previous Test Plan):
- **Summary:** - Execution - **fixVersion**: version assigned to Cycle | - 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 if the Cycle contains multiple Executions for the same Test, only the last Execution will be migrated. | | Cycle's folder | Test Execution, linked to the Test Plan created earlier from the Cycle
- **Summary: ** - - Execution - **fixVersion**: version assigned to Cycle | N/A | | Ad-hoc Cycle | Test Plan (optional)
- **Summary:** - Ah Hoc - **fixVersion**: version assigned to Cycle
Test Execution, linked to the previous Test Plan
- **Summary:** - Ad Hoc Execution - **fixVersion**: version assigned to Cycle | N/A | | Execution:
- Global comment. - Global defects. - Global status. - Step results. - Step comments. - Step defects. - Step status. | [Test Run](https://getxraydocs.atlassian.net/wiki/display/XRAY790/Test+Runs):
- Global comment. - Global defects. - Global status. - Step results. - Step comments. - Step defects. - Step status. | N/A | > ℹ️ All Issues will be created in the project where the migration is being performed. ## Migrating 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_* - 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](https://getxraydocs.atlassian.net/wiki/display/XRAY790/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. ## Performing the Migration 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 the 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: > Macro (ui-steps) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > ℹ️ Please have a look at the following section for some additional steps before concluding the migration process. ## After the Migration Concludes 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. > Macro (ui-steps) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content) > > > Macro (legacy-content)
Support/Troubleshooting If you have questions or technical issues, please [contact the Support team via the Customer Portal (Jira service management)](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28) or [send us a message using the in-app chat](https://getxraydocs.atlassian.net/wiki/display/XRAY/In-App+Chat+Support).