Zephyr Migration Tool - Advanced Guide

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:

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:

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 the objects count in your database:

Total count of test steps.

SELECT count (*) FROM jira."AO_7DEABF_TESTSTEP";
Total count of test step level attachment.
SELECT count (*) FROM jira."AO_7DEABF_ATTACHMENT" where "TYPE" = 'TESTSTEP';
Total count of step results.
SELECT count (*) FROM jira."AO_7DEABF_STEP_RESULT";
Total count of step result attachment.
SELECT count (*) FROM jira."AO_7DEABF_ATTACHMENT" where "TYPE" = 'TESTSTEPRESULT';
Total count of executions.
SELECT COUNT(*) FROM public."AO_7DEABF_SCHEDULE";
Total count of step results defects.
SELECT COUNT(*) FROM public."AO_7DEABF_STEP_DEFECT";

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 triggers Zephyr to delete all Zephyr objects for those issues. Then, you should clear cache in Zephyr Configurations menu, and bulk edit the issues 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.

Zephyr Squad Server-to-Cloud Migration Guides