Migrating from Zephyr Squad to QMetry using QMetry Migration Tool

In this guide, we will run you through the steps to migrate your data from Zephyr Squad to QMetry Test Management.

This documentation enlists all the information on migration process like what can be migrated, and what are the assets/data that may not be migrated, features of the migration utility along with System Requirements and Pre-requisites to be taken care before proceeding with migration.

What Zephyr Squad assets are migrated?

Table 216. What Zephyr Squad assets are migrated?

Zephyr Squad Assets

QMetry Assets

Tests

Test Cases

Cycle

Test Suites

Test Execution

Test Execution



Capabilities of the Migration Tool

  • Migrates Tests with teststeps, Test cycles and Test executions.

  • Rich text type data is migrated for all the long rich text supported fields.

  • Migrates custom fields and their values for all the assets. Support for Mapping of Zephyr Squad Enumerated fields and their values with QMetry fields.

  • Migrates folder structure of Tests.

  • Migrates comments for all the assets.

  • Migrates linkages between assets.

  • Migrates creation date for all the assets.

  • Migrates all the attachments and URL links.

  • Resumes migration failed or stopped due to an error.

System Requirements

  • Java25 needs to be installed. Reference: Archived OpenJDK GA Releases

  • MySQL services and MYSQL workbench 5.7 or above needs to be installed. Reference: MySQL :: Download MySQL Installer.

  • Operating Systems: Windows 10

  • CPU: 8 Cores, RAM: 16 GB

  • Get your QMetry Migration Tool (migrate2qtm.war) and its license (qmetry-license-version-1.0) from QMetry Support.

  • QMetry and Zephyr Squad should be running on your system with valid license.

  • Set UTC Time Zone in QMetry as all the dates from Zephyr Squad will be migrated in to QMetry as per UTC time zone.

  • Create Zephyr Squad users in QMetry.

Before you Begin

  • Turn off API limits and Audit Logging.

    • These steps need to be followed in the QMetry database. Enter 'root' database credentials when prompted.

      sudo su -
docker exec -it qmetry_rds_1 bash
mysql -uroot -p -A
USE qmetry;

    • Run the following SELECT query check the status and the UPDATE query to disable audit logs and email notifications.

    • 0=disabled 1=Enabled

      SELECT CAST(isEmailEnabled AS UNSIGNED) as isEmailEnabled , CAST(isLogEnabled AS UNSIGNED) as isLogEnabled from client; 
UPDATE `client` SET `isEmailEnabled` = b'0', `isLogEnabled` = b'0';

    • To enable them back (after migration is complete) run the following UPDATE query, and to check its updated value run the SELECT query.

      UPDATE `client` SET `isEmailEnabled` = b'1', `isLogEnabled` = b'1'; 
SELECT CAST(isEmailEnabled AS UNSIGNED) as isEmailEnabled , CAST(isLogEnabled AS UNSIGNED) as isLogEnabled from client;

    • Type \q to exit MySQL DB.

    • Type exit to exit the docker container.

  • [Optional] Install Certificate in JDK on the machine running the migration utility.

  • Run the migration utility from its dedicated machine.

    • Open your command prompt go to migrate2qtm.war directory.

    • Put license file "qmetry-license-version-1.0" beside migrate2qtm.war file.

    • Run the commands:

      cd PATH_TO_WAR_FILE
java -jar migrate2qtm.war --spring.datasource.username=dbusename --spring.datasource.password=dbpwd

    • The application should be accessible from the same machine using URL: http://localhost:8080/migrate2qtm.war.

    Once you're on the Zephyr Squad login page of the Utility, proceed with steps below.

Steps to Migrate Story and Bugs from Zephyr Squad to QMetry

Issue Types treated as "Story" and "Bugs" in Jira (Zephyr Squad) like Story, Bug, Epic, Task etc can be imported to QMetry by integrating the Jira Project with QMetry.

The default integration of Jira with QMetry enables import of requirements and issues. To integrate QMetry with Jira - first, install and configure QMetry's Jira Integration App i.e. "JIRA Integration - QMetry Enterprise".

With the above steps, the story and issues that would be imported and synced with QMetry, would be visible in the Requirement and Issue module respectively with the external key indicating the Jira Issue Key.

Story imported as Requirement in QMetry (with External Key)

QPro_Migration_Story_imported_as_Requirement_in_QTM.png

Bugs imported as Issues in QMetry (with External Key)

QPro_Migration_Bugs_imported_as_Issues_in_QMetry__with_External_Key_.png

Limitations

QMetry does not support integration of Sub Tasks or Sub Issue Types. These Requirements and Issues have to created manually in QMetry.

Migration Steps

  1. Zephyr Squad Login

    We recommend logging in Zephyr Squad using Admin Credentials so that the Projects available for migration are not restricted by a user's permissions.

    Select Zephyr Squad Instance: Cloud or Server/Data Center.

    For Zephyr Squad Server/ Data Center:

    • Base URL: Zephyr Squad URL in the format: <URL>

    • Username: Zephyr Squad Username and Password

    QPro_Migration_Zephyr_Squad_Login.png

    For Zephyr Squad Cloud

    • Base URL: Zephyr Squad URL in the format: <URL> 

    • Email Id: Zephyr Squad User Email address

    • Jira API Token: Atlassian Jira API Token

    • Zephyr Squad Access Key: Generated from the API Keys page

    • Zephyr Squad Secret Key: Generated from the API Keys page

    • Zephyr Squad Account Id: The ID of the user

    QPro_Migration_For_Zephyr_Squad_Cloud.png

  2. QMetry Login

    We recommend logging in QMetry using Admin Credentials so that the Projects available for migration are not restricted by a user's permissions.

    • Base URL: Your QMetry login : example: https://testmanagement.qmetry.com

    • Open API Key: QMetry Open API Key

    • Organization Code: Enter QMetry Organization Code, or leave it empty.

      QPro_Migration_QMetry_Login.png

  3. Create a Zephyr Squad Template Project in QMetry

    A template project is created in QMetry with the name "template_<zephyr project name>". The purpose of template project is to create a project structure that will be used to migrate the actual Zephyr Squad project with data into QMetry.

    In this template project -

    • Create Users: Create Zephyr Squad users in QMetry. Refer to Users in QMetry.

    Custom Fields: All the selected custom fields (Step # 5) from the Zephyr Squad will be created by the Migration utility and will be auto mapped to QMetry fields in the field mapping stage.

    This template project will be used in Step# 8 Migration. Users are taken from the template project to create the selected Zephyr Squad project.

  4. Project Selection

    • Select Zephyr Squad Projects you would like to migrate into QMetry. Also select the QMetry Project Template to be used to create the project structure. The selected Zephyr Squad projects are migrated one at a time.

      QPro_Migration_Project_Selection.png

  5. Entity Mapping

    Under this section, map the Zephyr Squad assets that you want to migrate with relevant QMetry Assets.

    QPro_Migration_Entity_Mapping.png

    Important Notes

    • Multiple Zephyr Squad entities can be mapped with respective QMetry entities.

    • For test cases, Created Date will be migrated to QMetry's system field and for other entities created date will be migrated as custom field, if user wants.

    • For test cases Created By will be migrated to QMetry's system field and for other entities created by will be migrated as custom field, if user wants.

    • Migrates all the attachments and URL links.

  6. Custom Fields

    You can select system fields and user-defined fields that are part of your Zephyr Squad project and that need to be migrated to QMetry.

    Note

    This is an important step to ensure there is no data loss when the project is migrated to QMetry. Make sure all the required fields are mapped correctly. Once migrated, the data cannot be reverted back.

    Selected fields will be converted as custom fields in QMetry and will be auto mapped with the appropriate fields on the field mapping page.

    QPro_Migration_Custom_Fields.png

    Custom Field for Zephyr Squad Test Steps

    QPro_Migration_Custom_Field_for_Zephyr_Squad_Test_Steps.png

    Custom Field for Zephyr Squad Cycle

    QPro_Migration_Custom_Field_for_Zephyr_Squad_Cycle.png

  7. Field Mapping

    Field mapping helps you to migrate the data from the fields of your Zephyr Squad assets to respective QMetry fields. Complete the field mapping for as many fields as possible to get their data migrated to QMetry. Fields can be mapped for Tests, Test Steps and Cycle.

    Field Mapping for Zephyr Squad Tests → QMetry Test Cases

    QPro_Migration_Field_Mapping_for_Zephyr_Squad_Tests___QMetry_Test_Cases.png

    Field Mapping for Zephyr Squad Test Steps → QMetry Test Steps

    QPro_Migration_Field_Mapping_for_Zephyr_Squad_Test_Steps.png

    Field Mapping for Zephyr Squad Cycle → QMetry Test Suite

    QPro_Migration_Field_Mapping_for_Zephyr_Squad_Test_Steps.png

  8. Field Value Mapping

    You can map the values of your different fields of Zephyr Squad, whose values may not match with QMetry field values.

    Field Value Mapping for Test Cases ( QMetry Test Cases)

    QPro_Migration_Field_Mapping_for_Zephyr_Squad_Tests.png

    Field Value Mapping for Test Steps ( QMetry Test Steps)

    QPro_Migration_Field_Mapping_for_Zephyr_Squad_Tests1.png

    Field Value Mapping of Cycles ( QMetry Test Suites)

    QPro_Migration_Field_Value_Mapping_of_Cycles_Test_Suites.png

  9. Migration

    Click Migrate to start the migration process.

    QPro_Migration_Migrate_Button.png

    You can track the migration process.

    QPro_Migration_TrackMigration.png

Important Notes

The migration utility is designed to support resuming the data migration from the same point in case an error is encountered due to data issues or other reasons. In such cases re-migrating the project is not necessary. At times when you run into errors, you can try to resume the migration after capturing the logs as follows.

  1. Capture Migration Logs

    The logs should be present in the logs folder of the migration utility directory containing the .war file. Zip the logs folder and send it to QMetry Support for investigation.

  2. Resume the Migration

    The migration can be resumed by refreshing the existing page and clicking "Resume" OR from the URL : http://<utility_url>/migrate2qtm/migration

  3. Reverting API metering, Audit history logging and Email Notifications.

    • Once the projects have been migrated, or in cases when users would use QMetry and no projects would be migrated for significant amount of time, in those cases these changes should be reverted.

    • Refer to the Before you begin section for the changes required.

Limitations

  • Zephyr Squad users are not migrated to QMetry.

  • Dashboards, Graphs, History logs are not migrated.

  • Attachments: Attachment files exceeding 100MB are not migrated.

  • For Test cases, Created Date will be migrated to  QMetry's system field and for other entities created date will be migrated as custom field, if user wants.

  • For testcases Created By will be migrated to  QMetry's system field and for other entities created by are migrated as custom field, if user wants.

Need Assistance?

If you run into any questions or concerns during your migration, you can reach out to QMetry Support by raising a ticket directly on our Support Portal. We would be happy to assist you!

In this section:
© 2026
Publication date: