Back to QMetry All Products Help Page
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 Assets | QMetry Assets |
---|---|
Requirement | Requirements |
Testcase | Test Cases |
Execution Cycle | Test Suites |
Defect | Issues |
Test Execution | Test Execution |
Release | Release |
Project | Project |
Environment | Platform |
Build | Build |
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.
- Details about the level of customization in Zephyr instance. (i.e. number of Custom/User-Defined Fields)
- Number of projects that need to be migrated.
- List of system and custom fields need to migrate (By Project).
- Number of projects to migrate for evaluation of utility. We preferred one sample project.
- Project list mentioning migration priority sequence.
- Estimated entity size of overall projects.
- Time slots available - Target Migration Dates.
Assets | Average 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 -
- Project size - Larger projects take more time to migrate.
- Test Execution data - Test Executions are more complex than other entities. So, it may take more processing time than other entities.
- Attachments – Attachments size also effect processing at the time of migration if their size is larger.
- Migration utility’s performance is also dependent upon network I/O and configurations of utility server.
System Requirements
- JDK 1.8.0_151 or above needs to be installed.
- MySQL 5.7 or above needs to be installed.
- Operating Systems: Windows 10, Linux - Cent OS 7
- CPU: 8 Cores, RAM: 16 GB
- 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).
- Zephyr Enterprise version 6.7.2 (Utility is tested on)
- Get your QMetry Migration Tool (zephyrent2qtm.war) and its license (qmetry-license-version-1.0) from QMetry Support.
- QMetry and Zephyr Enterprise should be running on your system with valid license.
- Set UTC Time Zone in QMetry as all the dates from Zephyr Enterprise will be migrated in to QMetry as per UTC time zone.
- Create Zephyr Enterprise users in QMetry.
- Export tags from Zephyr Enterprise and add them manually as Labels in QMetry. Refer to Labels 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.
- These steps need to be followed in the QMetry database. Enter 'root' database credentials when prompted.
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 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.
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.
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.
- 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.
- 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
- 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 beginning of the Migrating from Zephyr Enterprise to QMetry using QMetry Migration Tool#Before you begin for the changes required.
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!
Back to QMetry All Products Help Page