Migrating from Zephyr Enterprise to QMetry using QMetry Migration Tool

Open

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

Capabilities of the Migration Tool

• Migrates custom fields & their values for all the assets.

• Migrates folder structure. 

• Migrates comments for all the assets. 

• Migrates linkages between assets.

• Migrates all the attachments & URL links.

• Resumes migration failed / stopped due to an error.

• Support for Enumerated Mapping of Zephyr Enterprise fields and their values with QMetry fields.

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.9 (Utility is tested on)

7. Get your QMetry Migration Tool (migrate2qtm.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.

Pre-requisite

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=dbusername --spring.datasource.password=dbpwd

• The application should be accessible from the same machine using URL : http://localhost:8080/migrate2qtm. Once you're on the Zephyr Enterprise login page of the Utility, proceed with steps below.

4. Remove/rename duplicate list values for system/custom fields in Zephyr as QMetry does not support creation of duplicate values.

5. Create a Zephyr Enterprise Template Project in QMetry

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 Zephyr Enterprise users. Refer to Users in QMetry.

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

Open

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: Pre-requisite

Make sure you comply with the pre-requisite mentioned on the screen.

Step 4: Project Selection

• Select the Zephyr Enterprise Project you would like to migrate into QMetry. Also select the QMetry Project Template to be used to create the project structure. 

Step 5: Entity Mapping

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

Step 6: Custom Fields

You can select system fields and user-defined fields that are part of your Zephyr Enterprise project that needs 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.

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

Step 8: Field Value Mapping

You can map the values of your different fields of Zephyr Enterprise to that of QMetry.

Migration Tool provides an option of "Add value" if user wants to create a new field value in QMetry same as Zephyr offers. To create the new values > Click on the checkbox beside the field value > Click on "Add value" button below > Now map the Zephyr field values to the newly created QMetry fields values.

NOTE: The Add Value option is not available for test execution values and test step execution values.

Field Value Mapping for Requirements 

Field Value Mapping for Test Case (QMetry Test Cases)

Step 9. Migration

Click on the Migrate Button to start the migration process.

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

Post-requisite

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 Pre-requisite for the changes required.

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.

• ALT Id will be migrated as externalID.

• Test Planning (containing phases and folders) is migrated as test suites to QMetry

• Zephyr's ‘checkbox’ type Custom field will be migrated as a string (e.g. if checkbox is checked, then the value in the field will be displayed "True" in QMetry).

• If a duplicate folder is found in the same level of hierarchy, then that folder will be migrated with ID appended to the folder name.

• Folders are created according to the Zephyr Enterprise Releases. Zephyr Enterprise assets are then migrated in these folders.

• If Testcases are shared(i.e. Testcase has same ID) amongst multiple Releases in Zephyr, then new Testcases(i.e. each Testcase with a unique ID) will be created for respective Releases in QMetry.

• Migration Tool will not migrate execution of a deleted Testcase.

• If a duplicate Release is found, then that Release will be migrated with ID appended to the release name.

• Migration Tool does not migrate Hidden Releases and its Assets.

Limitations

• Zephyr Enterprise users are not migrated to QMetry.

• Dashboards, Graphs, History logs are not migrated.

• Attachments: Attachment files exceeding 100 MB 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!