Migrating from Zephyr Squad (formerly Zephyr for Jira) 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, Pre-requisites, and steps to be taken care before proceeding with migration.

What Zephyr Squad assets are migrated and Mapping with QMetry assets

Capabilities of the Migration Tool

• Migrates Tests and all their versions, rich text in Test Steps. 
• Migrates custom fields & their values for all the assets. 
• Migrates folder structure.  
• Migrates comments for all the assets.  
• Migrates linkages between assets. 
• Migrates creation date for all the assets. 
• 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 will be migrated as custom field, if user wants. 
• Migrates all the attachments & URL links. 
• Resumes migration failed / stopped due to an error. 
• Support for Enumerated Mapping of Zephyr Squad fields and their values with QMetry fields. 
• Migrates custom field and system fields and auto map in field mapping. 

Planning your Migration

The scope of migration affects the migration time. The clear visualization of the scope helps you do the precise planning for the migration. Below details should be shared before proceeding with the migration. 

1. Details about the level of customization in Zephyr instance. (i.e. number of Custom/User-Defined Fields) 
2. Number of projects that need to be migrated. 
3. List of system and custom fields need to migrate (By Project). 
4. Number of projects to migrate for evaluation of utility. We prefer one sample project. 
5. Project list mentioning migration priority sequence. 
6. Estimated entity size of overall projects. 
7. Time slots available - Target Migration Dates. 

Estimated Time Required for Migration

Server downtime duration for migration is dependent on below mentioned factors. The best approach is to do a mock migration of all the projects, get the UAT done. This approach provides exact stimates, to reduce last minute risks. Following are some factors -

1. Project size - Larger projects take more time to migrate.
2. Test Execution data - Test Executions are more complex than other entities. So, it may take more processing time than other entities.
3. Attachments – Attachments size also effect processing at the time of migration if their size is larger.
4. Migration utility’s performance is also dependent upon network I/O and configurations of utility server.

System Requirements

1. JDK 1.8.0_151 or above needs to be installed.
2. MySQL 5.7 or above needs to be installed.
3. Operating Systems: Windows 10, Linux - Cent OS 7
4. CPU: 8 Cores, RAM: 16 GB
5. Apache Tomcat server needs to be installed. Reference: https://archive.apache.org/dist/tomcat/tomcat-8/v8.5.60/bin/ (select as per the system you are using).
6. Get your QMetry Migration Tool (migrate2qtm.war) and its license (qmetry-license-version-1.0) from QMetry Support.
7. QMetry and Zephyr Squad should be running on your system with valid license.
8. Set UTC Time Zone in QMetry as all the dates from Zephyr Squad will be migrated in to QMetry as per UTC time zone.
9. Create Zephyr Squad users in QMetry.

Before you begin

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

2. Install Certificate in JDK on the machine running the migration utility.

• Follow the steps specified here: How to install certificate in JDK ?

3. 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 QTM 

Issue Types treated as "Story" & "Bugs" in Jira (Zephyr Squad) like Story, Bug, Epic, Task etc can be imported to QTM by integrating the Jira Project with QTM. The default integration of Jira with QTM enables import of requirements and issues. To integrate QTM 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) 

Bugs imported as Issues in QMetry (with External Key) 

Limitations 

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

Migration Steps

Step 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 

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 

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

Step 3.1: 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.

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

Step 3.2: 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.

Step 4.1: Entity Mapping

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

Step 4.2 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 & URL links.

Step 5: 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.

Custom Field for Zephyr Squad Tests

Custom Field for Zephyr Squad Test Steps

Custom Field for Zephyr Squad Cycle

Step 6: 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

Field Mapping for Zephyr Squad Test Steps → QMetry Test Steps

Field Mapping for Zephyr Squad Cycle → QMetry Test Suite

Step 7: 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)

Field Value Mapping for Test Steps (QMetry Test Steps)

Field Value Mapping of Cycles (QMetry Test Suites)

Step 8. Migration

The migration progress can be monitored until it is completed.

Once the migration completes, you can log in to QMetry and verify all the migrated data in your given projects.

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.

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!