Zephyr Migration Tool - Advanced Guide

Applies to Zephyr Squad Server 9.0.1 and 4.8, last modified on March 13, 2023

On this page, you can find comprehensive information about the Zephyr Open-Source Migration tool.

If your question is not answered here or if you want more information, feel free to contact us.

There is no reliable method to calculate the time required for migration. Customers should be prepared that migration tasks may even take hours. We urge our customers to test their migrations before setting dates for Prouction Migration. Only Test Migration will provide an accurate time estimation.

Test Cases will be imported with Jira XML site import, as they are Jira issues of type Test. ZMT will migrate Zephyr objects such as Test Steps, Executions, and more.

Test Steps and Executions have a bigger impact on performance. Also, any type of attachment impacts the rate of the migration - especially Test Execution Attachments.

Based on the number of test steps and test executions, you can:

  • expect a migration task to take more than 2 hours if it has more than 10,000 test steps and test executions combined.
  • expect a migration task to take more than 10 hours if it has more than 30,000 test steps and test executions combined.
  • expect a migration task to take more than 24 hours if it has more than 50,000 test steps and test executions combined.

The best way to know if a migration task is running is to check the migration logs. You can see the logs in your browser when you trigger the migration from http://localhost:8080/beginMigration. If the logs are updating, it means that the migration is running.

You can press ctrl+x to kill the Zephyr Migration tool process.

It is possible to run multiple project migrations simultaneously, however, you must take into consideration the Jira API call limits.

The hardware recommendation depending on the data footprint are:

  • Small instances - projects with less than 10,000 test steps and test executions combined:

    • 64-bit operating system

    • 4-core CPU

    • 8 GB RAM

  • Large instances - projects with more than 10k test steps and test executions combined:

    • 64-bit operating system

    • 4-core CPU

    • 16 GB RAM

If you are using the Zephyr Migration tool as your migration method, you can skip some migration steps by setting some default properties to false - if the project in question does not have any data for those properties, or if you do not want to migrate them. If you do not set the property to false, ZMT will check for those objects for every Issue in the selected Project.

You can use these queries to verify objects count in your database:

Total count of test steps.


Total count of test step level attachment.


Total count of step results.


Total count of step result attachment.


Total count of executions.


Total count of step results defects.


Once a project is partially migrated, you need to clear the existing Zephyr data on the Cloud before running the project migration again.

If you want to remove Zephyr objects for a single project, you should bulk edit all the issues in the project to a different Issue Type, like Test_Temp. That will trigger Zephyr to delete all Zephyr objects for those issues. Then, you should bulk edit them back to Test before you run ZMT for the project again.

If you want to remove Zephyr objects for the entire Jira instance, the easiest way is to rename the Test issue type in your cloud instance to Test_temp and then rename it back to Test. This effectively deletes test steps, executions, steps results, and attachment data for all projects in the cloud instance for all projects.

It is not necessary to delete version, cycle, and folder data to rerun a failed migration.

Besides deleting the data, you also need to delete the mapping files. Please refer to the Understanding the mapping files section to understand how they work.

Zephyr Migration Tool(ZMT) creates mapping files during the data migration process to track the objects already migrated to the Cloud. You can use the mapping files from previous migration to skip the data that is already migrated as ZMT skips the objects listed in the mapping files. If you need to re-run a migration and want to reimport the data, you must delete the existing mapping files.

Mapping files are a set of .xls files, created at the migration file path. They record the Zephyr entities that are already migrated. Mapping files are created for the Zephyr entities such as Version, Cycle, Folder, Execution, TestSteps, StepResults, Execution-Attachment, TestStep-Attachment, and StepResult-Attachment.

Once the migration is complete, we see the created files under the provided migration file path.

The Zephyr Migration tool will skip the migration of any Zephyr data found in existing mapping files. Therefore, if you want to redo the Zephyr Squad migration, you will need to delete the already created mapping files.

You can retain the mapping files from previous migrations for objects that you do not need to migrate. Either because the objects were already imported successfully or because you want to improve the migration tool performance.

If the mapping files cannot be found (because they got deleted or the migration file path changed), the Zephyr Migration tool imports the Zephyr data again, which can cause duplicates.

If you want to keep the current Zephyr data and continue the import with a new migration attempt, you must keep all the existing mapping files. The tool skips the already imported data and imports the data that is missing.

See Also

Zephyr Squad Server-to-Cloud Migration Guides

Highlight search results