Introduction

Zephyr HP ALM Migration Adapter is a unique API-driven solution that lets you migrate your data from HP ALM directly into Zephyr Enterprise. The solution works with either an On-Prem or a Cloud installation of Zephyr Enterprise.

Please see below for the compatible version of the HP ALM tool.
You can get the HP ALM Migration Adapter from the download page (the utility name is HPQC-ZS-<release>).

ALM and Zephyr Compatibility

ALM Adapter Version	ZE Version	HP ALM/QC Version
1.5.x	6.7 and later	15.0 12.6 12.5 11.5

Planning

Planning is an important phase of migration. This phase involves:

Determining HP ALM artifacts that need to be migrated
Reviewing environments and configurations
Optimizing stage environments

The sections below explain these in more details:

Determine HP ALM artifacts that need to be migrated
It is important to acknowledge that not all the data you have in legacy system remains good to be transferred. In this phase, you should review how your testing methodologies and practices have changed over time and determine the right HP ALM artifacts that makes sense to transfer to Zephyr.
Review environments and configurations
Not all HP ALM environments are configured the same. Please review the hardware configuration, memory allocation, API throttling configurations, network topology etc for each HP ALM environment.
Determine the migration style
There are two possibilities for the migration: big bang migration or trickle migration.
In big bang migration, the process is conducted over a weekend when both HP ALM and Zephyr are shut down for users. With this approach, we suggest at least one dry run of the migration in a stage environment before the live event.
In trickle migration, you may take an incremental approach by having both HP ALM and Zephyr available in parallel during weeks/months, and moving projects from HP ALM to Zephyr based on business needs.
With either approach, we undertake at least one week of review, preparation and optimization of stage environment; this includes optimization of system that has Zephyr HP ALM Migration adapter installed. Full access to stage environment is required.

Adapter Overview

The Zephyr HP ALM Migration adapter uses REST APIs to extract data from HP ALM and import data into Zephyr Enterprise. The section below provides a high-level overview of the communication between the Zephyr Enterprise instance, the HP ALM instance, and the Zephyr HP ALM Migration adapter:

Supported Migration Entities

The current version of the Zephyr HP ALM Migration Adapter supports migration of the following types of entities:

Projects
Users
Requirements
Tests
Test Attachments
Test Steps
Step Attachments
Test Folder Organization
Test Custom Fields
Release
Cycle
Test Run (Test Execution in Zephyr)

Limitations

Not all ALM data can be migrated to Zephyr Enterprise and the migrated data should comply with certain Zephyr requirements. The table below provides detailed information on migration limitations:

Component	Migration limitations
Domain	Since Zephyr does not have the domain concept, no domains are created in Zephyr. To differentiate the domains, the name of each migrated project is preceded by the domain name in Zephyr: `<domain name> <project name>`.
Users	A user name must have at least two characters. Users whose name has only one character will not be migrated. If only the first name of a user is specified in ALM (for example, `John`), the user will be migrated with the `John.John` user name. A user name without a proper email ID (for example, `user.1089`) will get a dummy email ID after the migration: `user.1089@qcmigrateduser.com`. All the users migrated to Zephyr will have the Lead role. You can change the role later. If a user was deleted in HP ALM, after the migration, all the data created by the user will be assigned to test.manager in Zephyr.
Releases	ALM folders containing releases will be discarded. Only the releases will be migrated. For example, if you have the `Sample-1` release in the `MyReleases` folder in HP ALM, you will have only the `Sample-1` release in Zephyr. If the release name or description is too long, it will be truncated to meet Zephyr requirements. Releases that have attachments will be ignored. If the release description is in the rich text format, it will be converted to plain text. If a release has only one character in its name, it will not be migrated. If the name of a release folder contains special or international characters, it will be ignored.
Requirements	ALM requirements of the Folder type will become both requirements and requirement folders in Zephyr. For example, if the requirement type of the `NewReq1` requirement is Folder, you will see both the `NewReq1` folder and the `NewReq1` requirement in Zephyr. Requirements that are not associated with any release or cycle in ALM will be shown in project requirements in Zephyr.
Test cases	Test cases that are not associated with any release or cycle in ALM will migrated to the project test repository and will not be assigned to any release. Test cases that have a priority in HP ALM will not be migrated. Test cases that do not belong to a test set, but are mapped to a requirement, will be added to the same release as the requirement.
Cycles	Cycles whose name has only one character will be ignored. If a test set is not associated with any cycle in ALM, the test set will be migrated to the Default ALM Release created in Zephyr.
Cycle phases	A cycle phase that is not associated with any release will be migrated to the Default ALM Cycle created in Zephyr. If the name of a cycle phase contains only one character, the phase will not be migrated. If the dates of cycle phases are not within the cycle’s range of dates, they will be changed to the cycle dates.
Executions	If an execution has child items in ALM, it will not have them in Zephyr. All the executions will be individual. In the execution history, the assignment date of executions will be the same as the cycle phase start date. If no Open Date is specified in ALM, the migration date and time will be specified in the Changed On column of Zephyr’s execution history.
Custom fields	Fields of the Lookup List type with child items will not be migrated. Custom fields of the user list type will not be migrated. Float custom fields will not be migrated. Custom fields of requirements and test cases are migrated. Custom fields of other entities are not migrated. The values of picklist custom fields can be inserted dynamically in ALM, which is not supported in Zephyr. The following error will be posted to the log when migrating such a field: `Invalid option for list xxx custom field.` If the data type of an ALM custom field differs from that in Zephyr, a new custom field with the same name postfixed with `ALM` will be created in Zephyr.
Attachments	Test step attachments of ALM test cases and executions are not migrated (HP ALM versions: 11.5 and 12.1). Files attached to releases are not migrated.
Defects	HP ALM defects are not migrated.
Accounts	To perform migration, you must be logged in to Zephyr as test.manager.
Indexing	After each migration session, you need to perform full reindexing in Zephyr. If you want to migrate a project that already exists in Zephyr (for example, your project was not migrated completely and you want to migrate it again), you need to either delete or rename the project in Zephyr before starting the migration. If the HP ALM and Zephyr servers are in different time zones, the Created On and Executed On dates you have in HP ALM will differ from those in Zephyr.

Migrating Defects from HP ALM to Jira

The current process for migrating historical defects from HP ALM into Jira involves the following steps:

The defects are exported from HP ALM using APIs available from HP
The defects are then imported into Jira by using Jira REST API calls or via a .CSV file

Setup & Usage Instructions

For setup and usage instructions, please refer to Using the Zephyr HP ALM Migration Adapter.

Additional Questions

For any questions, please contact Zephyr Support: https://support.getzephyr.com

Before sending a request to our Support team, you can create an archive containing system information and various logs that will help us debug the issue. To learn how to create the archive, see Support ZIP File.

Version History

Version	Release Date	Release Notes
1.5.5	March 2, 2021	Improvements: HP ALM might have custom fields that already exist in Zephyr. To avoid duplicating custom fields, version 1.5.5 introduces the following changes: If a custom field coming from HP ALM already exists in Zephyr: No new custom field is created, the existing field will be used. If an ALM field has a different data type, a new custom field with the same name postfixed with ALM is created in Zephyr. In case of custom picklist fields, the items of the ALM field are appended to the existing picklist field. In HP ALM, test cases can be assigned multiple time to the same cycle phase. To replicate this behavior in Zephyr, a number of test case copies are created in Zephyr and are assigned to such a phase. Old logs are no longer deleted. Previously, the adapter kept only the last 8 logs. You can still delete old logs manually. Bug fixes: Sometimes, the status of certain test cases was not migrated.
1.5.4	January 7, 2021	You can now perform parallel migration, which speeds up the migration process when migrating several projects. Performance improvements (multi-threading and bulk operations) Support for proxy. Support for HP ALM 15.0. Additional check points to control migration. Bug fixes.
1.5.3	October 13, 2020	Support for migrating test sets not assigned to any cycle in HP ALM. Support for migrating unexecuted test cases. Support for migrating Actual Results data from HP ALM. Support for migrating attachments at the Test Step and Evidence levels. When a test set is not assigned to a cycle, keep the hierarchy at the Test Case Repo level. Support for migrating test cases even if the HP ALM user has been deleted. Additional help when authentication fails. Updated time measurements from milliseconds. Bug fixes.
1.5.2	September 3, 2020	Compatibility with Zephyr Enterprise 6.8.
1.5.1	July 16, 2020	Bug fixes.
1.5	June 18, 2020	Compatibility with Zephyr Enterprise 6.7.x.
1.4.1	July 16, 2020	Bug fixes.
1.4	June 18, 2020	Bug fixes.
1.3	October 30, 2019	Test cases have been moved to the project level. Test cases can now be added to releases as cycles and phases. Now you can map a requirement to a test case if it is mapped in HP ALM: Test cases which do not belong to a test set will be moved to the default release of Zephyr Enterprise along with mapped requirements to maintain mapping coverage.
1.2	September 16, 2019	Improved migration of test cases to a specific Releases instead of at the Project level. Bug fixes.
1.1	July 25, 2019	Added support for self-signed certificates.
1.0	May 23, 2018	Added support for additional entities.
0.1	September 08, 2017	Initial version.

Zephyr HP ALM Migration Adapter Overview