Migrating from QTM4J(4.x) to QMetry using QMetry Migration Tool
In this guide, we will run you through the steps to migrate your data from QTM4J to QMetry Test Management.
This documentation provides information about the migration process, including supported and unsupported assets/data, features of the migration utility, system requirements, prerequisites, and important steps to follow before starting the migration.
QTM4J-QMetry Entity mapping
QTM4J | QMetry |
|---|---|
Test Case | Test Case |
Test Cycle | Test Suite |
Test Run Execution | Test Execution |
Capabilities of the Migration Tool
Migrates custom field and system fields and auto map in field mapping.
Migrates testcases and all their fields along with rich text supported in long-text type field.
Migrates test data in teststeps, test suite and test executions.
Integrates jira issue types with QMetry’s requirement and issue module through Jira Integration feature of QMetry.
Migrates custom fields and their values for all the assets.
Migrates folder structure along with folder description.
Migrates Fixed Version as Release.
Migrates comments for all the assets.
Migrates linkages between assets.
Migrates all the attachments & URL links.
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
QTM4J Version 4.x (Utility is tested on)
Get your QMetry Migration Tool (migrate2qtm.war) and its license (qmetry-license-version-1.0) from Professional Services team.
QMetry and QTM4J should be running on your system with valid license.
Set UTC Time Zone in QMetry as all the dates from QTM4J will be migrated in to QMetry as per UTC time zone.
Pre-requisites
Turn off API limits and Audit Logging.
Note
Whenever Audit Logs are disabled any manual task performed on QMetry will not be logged.
For QMetry server:
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.
For QMetry cloud:
Contact Professional Services team to turn off the API limits.
[Optional] Install Certificate in JDK on the machine running the migration utility.
Follow the steps specified here : How to install certificate in JDK ?
Remove or rename duplicate list values for system or custom fields in QTM4J as QMetry does not support creation of duplicate values.
Create a Template Project in QMetry. The purpose of template project is to create a project structure that will be used to migrate the actual QTM4J project with data into QMetry. In this template project, create and link the JIRA users. Refer to Users in QMetry.
Migration Steps
Run the migration utility from its dedicated machine.
Open the command prompt and go to the migrate2qtm.war directory.
Put license file "qmetry-license-version-1.0" besides migrate2qtm.war file.
Run the following command by giving the path of the migrate2qtm.war file
PATH_TO_WAR_FILE>java -jar migrate2qtm.war --spring.datasource.username=<DB USERNAME> --spring.datasource.password=<DB PASSWORD> cd <PATH_TO_WAR_FILE> java -jar migrate2qtm.war --spring.datasource.username=<dbusername> --spring.datasource.password=<dbpwd>
Note
The application should be accessible from the same machine using the URL : http://localhost:8080/migrate2qtm
Once you're on the destination selection page of the Utility, select QTM and proceed with steps below:
Destination Login - QMetry
We recommend logging in using admin credentials so that the projects available for migration are not restricted by a user's permissions.
Base URL: Your QMetry login URL. For example: https://testmanagement.qmetry.com
API Key: QMetry open API.
API Key from: QMetry<Integrations>Open API
Source Login- QMT4J
In the source selection page, select QTM4J and go to the QTM4J authentication screen. We recommend logging in using admin credentials so that the projects available for migration are not restricted by a user's permissions.
For QTM4J Server or Data Center:
Base URL: Jira instance URL in the format: http://<IP Address/URL>
Email : QTM4J user's login email
Password: QTM4J user's login password
QMetry API Key: Add the API key(QTM4J > Configuration > Open API)
For QTM4J Cloud:
Base URL: Jira instance URL in the format: http://<IP Address/URL>
Email : QTM4J user's login email
Password: QTM4J user's login password
QMetry API Key: Add the API key(QTM4J > Configuration > Open API)
Select Cloud from drop-down.
Pre-requisites
Make sure you comply with the pre-requisite mentioned on the screen.
Project Selection
QTM4J project and QMetry template project:
Select the QMetry project template to be used to create the project structure. The template project should be empty with 'Rich text enabled' and users with desired roles linked to it.
Select QTM4J project you would like to migrate into QMetry. Only one project can be selected and migrated at a time.
Project key and Project lead can be given by selecting the '' If required, Add Project Lead....." checkbox.
Jira Project Selection
Select the jira projects that you want to integrate with the project which is currently being migrated.
Entity Mapping
Jira Entity Mapping:
Under this section, for each selected Jira project, map your Jira assets or any other custom Issue-type to Requirement and Issue(defect) entities of QMetry. These assets will be migrated through Jira Integration feature of QMetry.
QMetry Entity Mapping:
Under this section, map your QTM4J assets which need to be migrated into relevant QMetry Assets.
Execution capping: User has a choice to give execution date criteria i.e. starting date from which the executions should migrate. To choose the capping date the user needs to click on “Select Date for Execution Capping“ option and select a date. Any executions having executed on date less than the selected capping date, will get skipped.
Custom Fields
You can select system fields and user-defined fields that are part of your QTM4J 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 selected correctly. Once migrated, the data cannot be reverted.
Selected fields are migrated as custom fields in QMetry and auto mapped with the appropriate fields in the field mapping page.
Custom Field for QTM4J’s Testcases
You can select system fields and user-defined fields that are part of your QTM4J 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 selected correctly. Once migrated, the data cannot be reverted.
Selected fields will be converted as custom fields in QMetry and auto mapped with the appropriate fields in the field mapping page.
Custom Field for QTM4J's Testcases
Custom Field for QTM4J’s Test Suites
Field Mapping
Field mapping helps you to map the fields of your QTM4J assets to respective QMetry fields. Complete the field mapping for all the fields to get their data migrated to QMetry.
Note
Any mandatory field of QTM should be mapped to mandatory field of QTM4J. The field type of the mapped fields of QTM4J and QMetry should be same.
Field Mapping for QTM4J Test Case → QMetry Test Case
Field Mapping for QTM4J Test Cycle → QMetry Test Suite
Field Value Mapping
You can map the values of your different enumerated fields of QTM4J 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 that of QTM4J. To create the new values:
Click on the checkbox beside the field value.
Click on "Add value" button below
Now map the QTM4J field values to the newly created QMetry fields values.
Note
The Add Value option is not available for test execution status and test step execution status. For that you need to manually create the execution status in the template project of QMetry before beginning the migration process.
Field Value Mapping for Test cases
Field Value Mapping for Test Suite
Migration
Click Migrate to start the migration process.
Monitor the migration progress until it is completed.
Once the migration is completed, you can log in to QMetry and verify all the migrated data in your migrated project.
Post-requisite
The migration utility is designed to support resumption of 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 Professional Services team for investigation.
Resume the Migration
The migration can be resumed by refreshing the existing page or clicking "Resume" on the migration page.
Reverting API metering, Audit history logging and Email Notifications.
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;
Refer to the Pre-requisite for more details.
Important Notes and Limitations
Dashboards, reports, overview, activities, graphs, history logs will not be migrated.
QTM4J users are not migrated to QMetry. The users need to be created and linked to the template project manually before starting the migration.
Test Plan from QTM4J will not get migrated as QMetry does not have such module.
The execution history will be migrated in the form of test logs of the test executions.
Attachments greater than 100 MB(for QMetry cloud) or 300 MB(for QMetry server) in size are not migrated. Such attachment details will be added to the 'skipped_attachments.log' file.
For assigning users to the migrated assets:
If the user is found in QMetry, the entity assigned to him in QTM4J, gets assigned to that user in QMetry.
If the user is not found in QMetry, but the selected Project Lead user is present in QMetry, the assets of QTM4J are assigned to that user.
If the user and Project Lead are not found in QMetry, the assets are assigned to QMetry System Admin.
QMetry Testcase: Estimated time maximum value is 99999 mins; the value will be skipped for Estimated time and 99999 mins.
Custom fields in test execution will not get migrated as QMetry does not provide customization at execution level.
For parameters grid, if less parameters (as compared to parameter table) are added in test steps, then such parameter will be removed from the grid when we migrate to QMetry.
For cross-project shareable testcases, the linked cross-project shareable testcase steps will be directly appended to the testcase after migrating to QMetry .
Archived data of fix versions, testcases, test cycles will not be migrated.
As per QMetry ’s functionality user can “update” the existing execution of testcase and steps and does not add new execution iteration. Same will be case through migration utility. So, for multiple execution iterations in QTM4J (execution history), the execution is updated multiple times, when migrated to QMetry.
QTM4J’s Test plans will not be migrated to QMetry as there is no corresponding module in QMetry.
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!