Migrating from Zephyr Enterprise to QMetry using QMetry Migration Tool


In this guide, we will run you through the steps to migrate your data from Zephyr Enterprise 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 Enterprise assets are migrated and Mapping with QMetry assets


Zephyr Enterprise AssetsQMetry Assets
RequirementRequirements
TestcaseTest Cases
Execution CycleTest Suites
DefectIssues
Test ExecutionTest Execution
ReleaseRelease
ProjectProject
EnvironmentPlatform
BuildBuild

Capabilities of the Migration Tool

  • Migrates Requirements, Test Case and all their versions, rich text in Test Steps.
  • Migrates rich text in Testcase description, Test Steps, ‘text/long’ text type custom fields.
  • Migrates Test Data in Test Steps, Test Case, Test Runs/Executions, Defects.
  • Migrates custom fields & their values for all the assets.
  • Migrates folder structure. 
  • Migrates comments for all the assets. 
  • Migrates linkages between 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.
  • ALT Id will be migrated as externalID.
  • Test Planning (containing phases and folders) and Test Execution will be migrated as test suites to the Test Suite module inside the folders.
  • Custom field ‘checkbox’ type will be converted to string (e.g. if checkbox is checked, then the value in the field will be displayed "True").
  • If a duplicate folder is found in same level of hierarchy, then that folder will be migrated with id appended to it.
  • Resumes migration failed / stopped due to an error.
  • Support for Enumerated Mapping of Zephyr Enterprise fields and their values with QMetry fields.
  • Migrates custom fields 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 preferred one sample project.
  5. Project list mentioning migration priority sequence.
  6. Estimated entity size of overall projects.
  7. Time slots available - Target Migration Dates.


AssetsAverage entity counts of all projects

Maximum entity counts

from projects to be

migrated.


Test Repository Count

Test Execution Count

Requirement Count

Defect Count

Test Cycle Count

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. Zephyr Enterprise version 6.7.2 (Utility is tested on)
  7. Get your QMetry Migration Tool (zephyrent2qtm.war) and its license (qmetry-license-version-1.0) from QMetry Support.
  8. QMetry and Zephyr Enterprise should be running on your system with valid license.
  9. Set UTC Time Zone in QMetry as all the dates from Zephyr Enterprise will be migrated in to QMetry as per UTC time zone.
  10. Create Zephyr Enterprise users in QMetry.
  11. Export tags from Zephyr Enterprise and add them manually as Labels in QMetry. Refer to Labels 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.

3. Run the migration utility from its dedicated machine.

  • Open your command prompt go to zephyrent2qtm.war directory.
  • Put license file "qmetry-license-version-1.0" beside zephyrent2qtm.war file.
  • Run the commands: 
    • cd PATH_TO_WAR_FILE
    • java -jar zephyrent2qtm.war --spring.datasource.username=dbusename --spring.datasource.password=dbpwd
  • The application should be accessible from the same machine using URL : http://localhost:8080/zephyrent2qtm. Once you're on the Zephyr Enterprise login page of the Utility, proceed with steps below.

Migration Steps

Step 1:  Zephyr Enterprise Login

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

  • Base URL: Zephyr Enterprise URL in the format: <URL>
  • Username: Zephyr Enterprise Username and Password


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 Enterprise 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 Enterprise project with data into QMetry.

In this template project -

  • Create Users: Create Zephyr Enterprise users in QMetry. Refer to Users in QMetry.
  • Labels: Export tags from Zephyr Enterprise and add them manually as Labels in QMetry. Refer to Labels in QMetry.


Custom Fields: All the selected custom fields (Step # 5) from the Zephyr Enterprise 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, Labels and Custom fields are taken from the template project to create the selected Zephyr Enterprise project.


Step 3.2: Project Selection

  • Select Zephyr Enterprise 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 Enterprise projects are migrated one at a time.


Step 4.1: Entity Mapping

Under this section, map your Zephyr Enterprise assets being migrated into relevant QMetry Assets.


Step 4.2 Important Notes:

  • 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.
  • ALT Id will be migrated as externalID.
  • Test Planning (containing phases and folders) and Test Execution will be migrated as test suites to the Test Suite module inside the folders.
  • Custom field ‘checkbox’ type will be converted to a string (e.g. if checkbox is checked, then the value in the field will be displayed "True").
  • If a duplicate folder is found in the same level of hierarchy, then that folder will be migrated with id appended to it.
  • Test Case folders are created according to the Zephyr Enterprise Releases. Zephyr Enterprise test cases are then migrated in these folders.


Step 5: Custom Fields

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

  • Custom field ‘checkbox’ type will be converted to a string (e.g. if checkbox is checked, then the value in the field will be displayed "True").

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 Enterprise Requirements



Custom Field for Zephyr Enterprise Test Case



Custom Field for Zephyr Enterprise Execution Cycle

Custom Field for Zephyr Enterprise Defect

Step 6: Field Mapping

Field mapping helps you to migrate the data from the fields of your Zephyr Enterprise 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 Requirements, Test Case, Execution Cycle, and Defects.

Field Mapping for Zephyr Enterprise Requirements → QMetry Requirements



Field Mapping for Zephyr Enterprise Testcase → QMetry Test Cases




Field Mapping for Zephyr Enterprise Execution Cycle → QMetry Test Suite



Field Mapping for Zephyr Enterprise Defects → QMetry Issues



Step 7: Field Value Mapping

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

For example,

  • In Zephyr Enterprise, you have Priority Field having values: P1, P2, P3, P4
  • In QMetry Priority Field may have values: Blocker, Critical, Major, Minor

You can map such field values to have appropriate values while they are migrated in QMetry.


Field Value Mapping for Requirements 



Field Value Mapping for Test Case (QMetry Test Cases)


Field Value Mapping of Execution Cycles (QMetry Test Suites)


Field Value Mapping for Defect

The defects will be created in QMetry internal issue module.



Step 8. Migration

Till the Step # 7, all the processes were carried out on the template project created in Step# 3.1: Create a Zephyr Enterprise Template Project in QMetry.

In this step (Step # 8), this template project is used to create an actual project in which the Zephyr Enterprise Enterprise data will be migrated.
Click on the Migrate Button to start the migration process.


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>/zephyrent2qtm/migration
  3. Reverting API metering, Audit history logging and Email Notifications.

Limitations

  • Zephyr Enterprise users are not migrated to QMetry.
  • Dashboards, Graphs, History logs are not migrated.
  • Attachments: Attachment files exceeding 10MB are not migrated.
  • Test Case/Test Execution where Assigned to="Anyone", it will get assigned to admin.

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!