Skip to main content
System StatusContact Support Agility Community

VersionOne Integration for HP-ALM

This feature is available in all editions.



The VersionOne Integration for HP-ALM (formerly known as Quality Center) allows an organization to leverage its investment in HP-ALM as part of an integrated platform for agile development.

This integration provides agile teams with the ability to:

  • Create defects in VersionOne from defects in HP-ALM

  • Mark HP-ALM defects as "fixed" when the corresponding VersionOne defect is closed

  • Create tests in HP-ALM from tests defined on VersionOne defects or stories

  • Update the status of a VersionOne test from the corresponding HP-ALM test

The flow of defect data makes it possible to triage defects and include them in the planning process to balance new work and maintenance. You can leverage existing automated workflows and defect reporting in HP-ALM, while adding the practice of agile project management. The integration will send specified defects from HP-ALM to VersionOne and update defect status from VersionOne back to HP-ALM.

The flow of test data makes it possible to monitor the quality of your projects more easily by making the latest test results visible in VersionOne. Teams can leverage existing test plans and test reporting, while creating new tests based on current user stories/backlog items. This integration will send tests from VersionOne to HP-ALM and update test pass/fail results from HP-ALM back to VersionOne.

The following sequence diagram illustrates how the VersionOne Integration for HP-ALM interacts with HP-ALM and VersionOne:



Application files for the current and previous versions of this integration can be found in the AppCatalog

Source Code

Source code for this integration can be found in GitHub


Integrating tests and defects

System Requirements



  • 14.1 and higher, all editions. 15.0 or higher if using access tokens for VersionOne authentication.
  • A member account with a Team Member project role or higher permissions.


  • Tested on HP-ALM versions 11.5, 12.0, and 12.2. Integration with older versions of HP-ALM may work, but are no longer supported by VersionOne.


These installation instructions assume that both VersionOne and HP-ALM have already been installed and configured, and are working properly.

1. Determine the installation location.

The integration can be installed on any computer with HTTP access to both VersionOne and HP-ALM. Exact placement should be determined by your internal software management requirements. The integration computer must meet the system requirements stated above.

2. Extract the integration files.

Download the integration ZIP file from the AppCatalog then extract the files to a directory of your choice.

3. Configure the integration.

Configuration for the integration is a three step process that involves configuring VersionOne, HP-ALM, and the integration. Configuring all of these will be discussed in later sections.

4. Run the integration.

Using file explorer or a command prompt, navigate to your installation folder, and run the following application executable:

If you have configured your system properly, you should see several [Info] messages followed by a [Startup] message.

5. Test the integration.

Details on testing the integration are available below in the testing section.

6. Install the integration as a Windows Service.

Run the following command from a console window:
VersionOne.ServiceHost.exe --install

This command installs the service so it will run under the account NT AUTHORITY\Local Service. The Local Service account must be given access privileges to the directory where the integration was installed so it can store its state and write to log files.

Follow the steps below to change the security on the installation directory:

  1. Right click the installation folder from Windows Explorer.
  2. Select "properties".
  3. Select the "Security" tab.
  4. Click the "Add" button.
  5. Enter "Local Service" and click "OK".
  6. Click the "Allow" checkbox for the "Full Control" row.
  7. Click "OK" to save the changes.

To uninstall the service, use the "--uninstall" command line option.


Configure HP-ALM

This section describes how to configure HP-ALM for use with the integration.

Previous versions of the integration required installation of the HP-ALM Connectivity Components. With the release of version of the integration, this is no longer required as the integration uses the HP-ALM REST API. For instructions on how to uninstall the connectivity components, see Uninstall Utility for Quality Center / Application Lifecycle Management Client.

1. Create a custom user field on the "Test" entity for storing the VersionOne ID of the matching test asset.

In the HP-ALM user interface, select Customize from the configuration menu, then Project Entities, then Tests, then User Fields. From there click New Field to create a new custom user field.


In HP-ALM 12.0 and higher, you cannot configure user fields in the web client, you must use the desktop client.

2. Select or create a user in HP-ALM to represent the VersionOne system.

This user must have sufficient rights to accept and modify defects. Additionally, this user must have access to all HP-ALM projects that contain defects that will be pushed to VersionOne.

Configure VersionOne

1. Add "HP-ALM" to the global source list type.

In the VersionOne user interface, select List Type from the Administration drop down then select Global. In the Source list type section, click the Add button to add the new value.

Skip this step if you are configuring a VersionOne Team Edition instance.


2. Select or create a user in VersionOne to represent the HP-ALM system.

This user must have sufficient rights to create defects, and accept and modify tests in VersionOne. Additionally, this user must have access to all VersionOne projects that contain tests and defect statuses that will be pushed to HP-ALM. The default filters expect this user's "Short Name" (i.e. Owners Nickname) to be "admin".

3. Determine where to store the HP-ALM identifier in VersionOne.

The integration needs a text field in VersionOne to store the HP-ALM identifier, which is a reference to the domain, project, and defect ID in HP-ALM. By default this is the "Reference" field. If you are already using this field for a different purpose, you will need to create a custom text field and update the configuration setting.

Configure the Integration

To configure the integration, run the ServiceHost configuration tool by executing the following:

You must restart the integration service after making a change with the configuration tool.

The following section describes how to configure the integration using the configuration tool. This tool updates the VersionOne.ServiceHost.exe.config file located in the application directory.

1. On the "General" tab specify your VersionOne connection details.


The following table describes the fields on this tab:

Field Description

The type of authentication the integration will use to communicate with VersionOne.

Server URL The URL to your VersionOne server.
Access Token An acccess token created for the account the integration will run as, not required when using Basic authentication.
Username Username of the VersionOne member account that the integration will run as, not required when using access token authentication.
Password Password of the VersionOne member account that the integration will run as, not required when using access tokens authentication.

If there is a proxy between this machine and the VersionOne instance, you'll also need to configure the following settings:

Field Description
Use Proxy For Connection Determines if the integration tries to connect through a proxy.
Proxy URL The URL to your proxy server.
Proxy Username The username that will get you past the proxy.
Proxy Password The password for the proxy username.
Proxy Domain The name of proxy domain.

2. Once the VersionOne parameters are specified, select the "Validate" button to continue.

If your connection is valid, you'll see the message "VersionOne settings are valid" in green text.

3. On the "Workitems" tab specify the VersionOne field that will hold the HP-ALM ID.

This is typically the VersionOne "Reference" field.


The following table describes the fields on this tab:

Field Description
Reference Field Name Defect field used to hold HP-ALM ID. By default this is the Reference field.
Disabled Check this box to disable polling VersionOne for defect updates. If disabled, defects will not be transferred to VersionOne from HP-ALM nor will defects closed in VersionOne send updates to HP-ALM.

4. On the "Test Services" tab specify how VersionOne tests will be pushed and updated to/from HP-ALM.


The following table describes the fields on this tab:

Field Description
Disabled Check this box to disable polling VersionOne for test updates.
Reference Field Name Field on a VersionOne test used to hold HP-ALM ID. By default this is the Reference field.
Passed Test Status The test status value in VersionOne that indicates a test succeeded.
Failed Test Status The test status value in VersionOne that indicates a test failed.
Change Comment The change comment put into history for any modifications the service makes in VersionOne.
Description Suffix A suffix for the description of any defects that the service creates; Embedded Rich Text (HTML) is valid in this suffix.
Create Defect Indicates whether the service should create defects when a failed test is closed in VersionOne. Valid values are:
  • All: The integration will create a VersionOne defect for any closed test in the project when the test fails.
  • CurrentIteration: The integration will only create VersionOne defects for closed tests within the current iteration when the test fails.
  • None: The integration never create VersionOne defects when a test fails.
Base Query Filter The VersionOne query used to locate tests in VersionOne that need to be created in HP-ALM. The default query will find tests that have a blank Reference and the Test Owner Short Name (i.e. Owner's Nickname) is "admin" and Status value is blank.
Poll Interval The time interval (in minutes) between between two consequent requests for changes.
Project Mapping

Specify the list of projects in VersionOne that should be queried for test cases to send to HP-ALM. Multiple VersionOne projects can be specified. If the project has children, you can include those children when querying with the "Incl. Child Projects" checkbox.

The "HP-ALM Project ID" is not the actual name of the project in HP-ALM. Instead, the ID specified here is simply a reference to the corresponding "Project ID" in the project mappings within the "HP-ALM" tab on the config tool. The actual HP-ALM project specification is created on the "HP-ALM" -> "Project and Priority Mappings" tab.

5. On the "HP-ALM" tab, specify your HP-ALM connection details and the data transfer behavior.


Field Description
Disabled Check this box if you want to disable polling HP-ALM for updates to tests and new defects.
URL Fully qualified URL to your HP-ALM instance.
Username Valid HP-ALM user.
Password Password for specified user.

6. Click the "Validate" button to ensure the connection parameters are correct.

If your connection is valid, you'll see the message "Connection settings are valid" in green text.

7. Configure the defect search criteria.

Add search criteria to determine which defects in HP-ALM will be brought over into VersionOne:

Field Description
Field Name HP-ALM field to include in query for defects you want created in VersionOne.
Field Value Value expected in field to trigger defect creation in VersionOne.

The typical rows specified are "owner" with the HP-ALM user name representing the VersionOne user, and "status" with the status value to trigger defect creation in VersionOne, such as "New".

8. Specify the VersionOne source value (the value you created under step 1 of Configure VersionOne).

VersionOne Team Edition contains a Source value of "External System"

9. Specify the HP-ALM defect status value to set back in HP-ALM after the defect is created in VersionOne.

10. Specify the HP-ALM defect status value to set back in HP-ALM after the defect is closed in VersionOne.

11. Set the polling interval (in minutes) for the service.

12. In the Project and Priority Mappings tab, configure which HP-ALM projects are polled.

Project Mapping allows you to specify which HP-ALM projects are polled and where to create defects in VersionOne.


Field Description
ID The integration identifier for this project (the same value you entered as an identifier on the "Test Service" tab).
Domain The HP-ALM domain.
HP-ALM Project The HP-ALM project name.
Test Folder The name of HP-ALM folder to use for creating tests (if it doesn't exist, it will be created automatically).
VersionOne ID Field The HP-ALM custom field that will hold the VersionOne Test ID (the one you created under "Project Entities" in HP-ALM). See the note below to learn how to look up the correct value to use.
VersionOne Project VersionOne project to use for creating defects.

You can map multiple HP-ALM projects to the same VersionOne project.

Getting the right value to use for the VersionOne ID Field configuration involves executing a HP-ALM REST API query in your browser. To look up the value, open a browser and then enter the following URL, replacing the server, port, domain, and project with values from your environment:




Once the query returns, search the XML returned for the value of the custom field that you created to contain the VersionOne ID. Here's an example of the XML for the custom TS_USER_01 field:


<Field Name="user-01" Label="VersionOne ID" PhysicalName="TS_USER_01">






Note that it is the Name attribute that contains the value to use in the integration configuration, which in the example above, is "user-01".

13. Map your Priority Values.

Priority mapping allows you to configure how the VersionOne defect priority value is set based on the HP-ALM priority value. The algorithm for mapping is simple, if the HP-ALM priority value is in the mapping, the VersionOne defect value is set to the mapped value. If the HP-ALM priority value is not found, the VersionOne defect value is not set.


To add a priority mapping you need to do the following:

  1. Click on the "Project and Priority Mappings" tab.
  2. In the Priority Mappings grid, select a VersionOne Priority value from the dropdown.
  3. Supply the corresponding HP-ALM Project value name.

To remove a mapping:

  1. Select the desired row.
  2. Click the Delete current row button.

14. Save your changes and exit the config tool program.


Each section below describes how to test one aspect of the integration. To shut down the integration after testing, press "Q" in the console window.

Creating a HP-ALM test from a VersionOne test

  1. In VersionOne
    1. Select a project you defined on the "Test Service" tab in the configuration tool.
    2. Select a test and set the field to match the criteria defined on the "Test Service" tab. If you used the default configuration, you need to set the owner to the "admin" user and ensure that the test has no value in the status or reference fields.
  2. In HP-ALM
    1. Connect to the project you expected the test to appear. 
    2. Verify that the test appears in the Test Plan section under the folder configured on the "HP-ALM" tab in the Project section.

Updating the status of a VersionOne test from HP-ALM

  1. In HP-ALM
    1. Assign the test created from VersionOne to a TestSet.
    2. Change the status of this test.
  2. In VersionOne
    1. Verify the test status has changed.

Creating a VersionOne defect from HP-ALM

  1. In HP-ALM
    1. Assign a defect to the "Version One" user.
    2. Set the defect State to "New".
    3. Verify the defect state has changed to Open.
  2. In VersionOne
    1. Verify the defect is in the backlog for the VersionOne project specified on the "HP-ALM" tab in the configuration tool

Updating a HP-ALM defect from VersionOne

  1. In VersionOne
    1. Close a defect that was created from HP-ALM. 
  2. In HP-ALM
    1. Verify the defect status is set to "Fixed".

Getting Help

While we strive to make our integrations as easy to use as possible, however you may still occasionally need some help, and there are a few different ways you can get it:

  • StackOverflow: For asking question of the VersionOne Developer Community.
  • VersionOne Technical Services: A paid support offering, this team provides API training, development pairing, and complete custom development services.