Quality Center (Test) Installation User Guide

Integrations with test tracking applications allow team members to leverage their current test and defect infrastructure while using Rally for agile project management. Integrations to Quality Center are available or you could write your own using the extensible Web Services API in your favorite development language.

1.0 Introduction

The Rally Connector for Quality Center allows customers to use Rally for Agile lifecycle management while still using Quality Center for management of tests and runs. The connector enables you to map:

• Tests from Quality Center to the TestCases in Rally (or from TestCases in Rally to Quality Center)
• Runs from Quality Center to the TestCase Results in Rally

2.0 Overview of features

The Rally Connector for Quality Center runs as a Ruby script on a Windows machine inside your network. The connector uses the Quality Center Open Test Architecture (OTA) API which uses COM objects and is only supported on Windows.

The connector is configured through an XML file. A log file is created to track all changes made in Rally and Quality Center by the connector. The connector requires a custom field exists in each system to store the unique ID of the linked objects in the other system. For multiple Quality Center projects, you will need to setup multiple custom fields in Rally for each project to store the unique ID for the linked object. The connector copies fields from Rally and/or Quality Center based on a field mapping that you have specified in their configuration file. Standard and custom fields can be mapped between the two systems.

The connector provides four services to synchronize objects between Rally and Quality Center:

• Copy entities created in Quality Center to Rally work items
• Copy work items created in Rally to Quality Center entities
• Update Rally work items based on changes made to Quality Center entities
• Update Quality Center entities based on changes made to Rally work items

The configuration file specifies which services to run, and in what order.

For Quality Center tests, all four services are supported. For Quality Center runs, only COPY_OTHER_TO_RALLY is supported.

The graphic below depicts the recommended workflow when using Quality Center for test management.

3.0 Software and hardware requirements

This connector is available for Unlimited Edition customers and Integration Hub partners.
Click the Contact Support link at the bottom of any page in Rally to open a support case to obtain the Rally Connector for Quality Center. Once you have received a response and obtained the installation package, proceed with the following tasks.

The following are the software requirements to install and run the Rally Connector for Quality Center:

• Rally subscription
• A Windows XP, Windows 7 or Windows 2003/2008 Server with access to Quality Center and Rally
• HP Quality Center 10.0 with patch 7 or HP ALM 11.0 or HP Quality Center 11.0 (hereafter referred to as QC)
• Internet Explorer 7.0 or 8.0 (IE8 or IE9 running in the IE8 compatibility mode recommended for QC 10 / QC 11)

Hardware: The EIF Connector can be installed in a number of ways. There can be multiple install locations on the same machine that can run in parallel which affect the hardware required. We recommend the following guidelines:

• The base hardware recommended would be a Pentium IV or greater processor with 512MB of RAM for one installed location
• We recommend running no more than 5 to 10 configuration files per install location
• As you add more install locations running in parallel, we have found that each installed location consumes up to 200MB of RAM when running and less than 50MB when idle
• Hard drive space is minimal and needs to scale only with log files so 200-250MB of space per install location is recommended for log file space

3.1 Pre-installation checklist

• Project and Site Administration access to a test environment of Quality Center
• Rally administrator privileges are needed for setup but only user access is needed to run the connector
• Before use of the connector, you need to access Quality Center from your IE browser to download the required DLL files.
  • For QC 10, you'll only need to point your Internet Explorer to the URL for your QC 10 installation. The necessary DLL files are downloaded automatically when the page loads and are then in place for use by the Rally Connector for Quality Center.
  • For QC 11, you'll need to run Internet Explorer 8 and navigate to the initial page for QC. For example, if you've installed QC 11 on a host named qcserve and configured it to service connections on port 8080, navigate to http://qcserve:8080/qcbin. Adjust the name of the host and port to match your specific configuration.
    1. Once the initial page displays, click the Add-Ins Page link.
    2. Click the HP Quality Center Connectivity link.
    3. Click the Download Add-In link.
    4. A download dialog panel displays asking you to Run | Save | Cancel. While you can select Run, we suggest you first Save the TDConnect.exe file and run it after the download completes. This file is about 10 MB in size, takes under a minute to run, and displays an alert dialog informing you of the installation disposition (completed or failed). Upon a successful installation, the necessary DLL files are in place for use by the Rally Connector for Quality Center.

• Proxy server details if the machine used to run the connector uses a proxy server

4.0 Installation

4.1 Basic installation steps

1. Install the connector (run the installer or extract the zip).
2. Make configuration changes in Rally and the other system.
3. Edit the <connector_name>_config.xml to reflect your environment.
4. Run rally2_<connector_name>_connector to start the synchronization process.

4.2 Install the connector

(Optional) If you use a proxy server to access Rally, you will need to set the http_proxy environment variable.

1. On Windows, right-click My Computer and select Properties.
2. Select the Advanced tab and then click Environment Variables.
3. Click New under System Variables and enter http_proxy as the full HTTP URL, such as http://www-cache:8000. You may need to restart your system in order for the change to take effect.

Installation for Windows

Double-click the RallyConnectorfor<connector_name>Install-<version>.exe to bring up the install wizard. Follow the prompts to complete the installation.

The Windows installer will install the following files (by default in C:\Program Files\RallyConnectorfor<connector_name>):

• rally2_<connector_name>_connector.exe - Executable to run the connector.
• <connector_name>_config.xml - Sample configuration file.
• WinTail.exe* - Utility to tail the log file output for debugging purposes.
• start<connector_name>.bat - Batch file that automatically runs the connector and shows the log file; useful for testing.

*WinTail is a free text file tail utility for Windows, generously made available by Bare Metal Software Pty Ltd. for redistribution without restriction. We have found it to be far superior to Notepad and other text editors for watching log files in real time as they are updated by the connector.

4.1.2 Make configuration changes in Rally and Quality Center

Create an external ID field in Rally

1. Log into Rally as a Workspace or Subscription administrator.
2. Go to Setup → Workspaces & Projects.
3. Click on the appropriate Workspace that you wish to map to Quality Center. This will take you to the Detail page for the given Workspace.
4. Click on Work Products & Fields and ensure the Work Product Type selected is Test Case or whatever work item you are mapping.
5. Click Actions → New Field.
6. Enter a Name and Display Name of ExternalID (name and display name must match), and type of String.

   Note: You can choose a different name (such as QualityCenterID) for the custom field in Rally,

   CAUTION: If you are planning to map to more than one Quality Center project (using multiple configuration files) to the same Rally workspace, create multiple ExternalID fields in Rally to match each project in Quality Center. such as ProjectAExternalID, ProjectBExternalID.

Make note of the name of this field. Once you start using the connector, this will contain the external ID of the Quality Center entity you are mapping between the two systems.

Tip: Rally does not support custom fields on test case results, so only complete this step for the test case work product type.

The update service from Rally to QC is workspace scoped, meaning the connector looks for any artifact type in Rally where the external ID field is not null. If you are mapping the same workspace to multiple Quality Center projects, then having unique external ID fields is critical so the connector knows which work item to update in Quality Center. Work item ids are not unique across Quality Center projects.

Create an External ID user field in Quality Center

Contact your Quality Center project administrator to perform these updates:

1. Go toTools → Customize → Project Entities.
2. Expand Test or Run in the Project Entities List.
3. Select the User Fields folder.
4. Select the New Field button at the bottom of the form.
5. Provide a Field Label for the field, select Field Type as String with a 40 character limit and leave the default check boxes for all other options.
6. Click Save. A dialog displays with the message The changes were saved successfully displays.
7. Repeat steps #1-6 for the TEST and RUN tables.

Make note of the Field Name (not the Field Label) of this field (such as TS_USER_xx or RN_USER_xx). You will enter this value (TS_USER_xx or RN_USER_xx) in the <ExternalIDField> element of the configuration file under <QCConnection> or <QCRunConnection>.

4.1.3 Edit the Configuration File

The configuration file was part of the delivered zip file and should be in the same directory where you extracted the Ruby gem. For Quality Center tests and runs, the default configuration file has a name of qc_config_test.xml and qc_config_run.xml. Uninstalling the connector will permanently delete the default files shipped with the connector so renaming or backing up these files is extremely important.

Step 1: Edit the "test configuration" file (such as the qc_config_test.xml) by entering the appropriate values between each begin and end tag.

Step 2: Edit the "run configuration" file (such as the qc_config_run.xml) by entering the appropriate values between each begin and end tag.

Each major section is surrounded by a tag to delineate that section. In the example above, here is a description of each section:

• RallyConnection - Defines the connection information to Rally including Rally URL, username, password, and so on.
• RallyTestResultConnection - Defines the connection information to Rally including Rally URL, username, password, etc. Supports Rally test results only.
• QCConnection - Defines the connection information to Quality Center including domain name, project name, artifact type, user, and so on.
• QCRunConnection - Defines the connection information to Quality Center including domain name, project name, artifact type, user, and so on. Supports QC runs only.
• Connector - Defines the field mapping between each system. This expects each field is compatible with the field in the other system (Integer -> Integer, ...)
• ConnectorRunner - Specifies a run interval for how often the connector will query each system to trigger creates/updates and what services should run.

Definition of tags in configuration file

Below is a more detailed explanation of each tag in the configuration file:

Rally connection

Parent Tag	Tag Name	Description	Sample Values	Required
RallyConnection	<Url>	Server used to connect to Rally.	sandbox.rallydev.com rally1.rallydev.com	Y
RallyConnection	<WorkspaceName>	Workspace in Rally you want to copy/update work items.	My Workspace MyWorkspace	Y
RallyConnection	<User>	Login name for user to make the Web Services requests to create/update work items in Rally.	user@company.com	Y
RallyConnection	<Password>	Password for user to make the Web Services requests to create/update work items in Rally. Note: The first time the connector runs, it will encode the password so it is not saved in plain text.	mypassword	Y
RallyConnection	<ArtifactType>	Type of artifact you want to create/update in Rally.	Defect HierarchicalRequirement TestCase	Y
RallyConnection	<ExternalIDField>	Rally custom string field (name and display name must be identical) that stores the unique ID for the other system. Refer to the Create an External ID Field in Rally section above.	ID	Y
RallyConnection	<Projects>	Contains a list of Project tags. Each tag refers to one Rally project that will be used when finding new Rally work items to copy to the other system. For updating work items from Rally to the other system, all projects in <WorkspaceName> are considered. At least one Rally project must be specified in this tag.	<Project>Rally1</Project> <Project>Rally2</Project>	Y

Tip: Escape special characters contained in a Rally Workspace or Project name that are markup sensitive. For example:

Rally Test Result connection
Same as RallyConnection except parent tag is <RallyTestResultConnection>.

Quality Center connection

Parent Tag	Tag Name	Description	Sample Values	Required
QCConnection	<Url>	Quality Center server name (or IP address) and port. Syntax is server:port	myqcserver:8080	Y
QCConnection	<User>	User to make the API requests to create/update entities in Quality Center.	myuser	Y
QCConnection	<Password>	Password for user to make the API request to create/update entities in Quality Center. Note: The first time the connector runs, it will encode the password so it is not saved in plain text.	mypassword	Y
QCConnection	<Domain>	Name of domain that you want to connect to in Quality Center.	My Domain	Y
QCConnection	<DatabaseSet>	Name of project that you want to connect to in Quality Center.	My Project	Y
QCConnection	<ArtifactType>	Entity name for the entities you want to create/update in Quality Center.	TEST	Y
QCConnection	<TestFolder>	Name of the Test Plan folder under Subjects in which to place newly copied tests in Quality Center. This folder must exist prior to running the connector.	Iteration1, UI-Responsiveness	N
QCConnection	<IDField>	Quality Center field used to store the unique ID of a test or other entity.	TS_TEST_ID	Y
QCConnection	<ExternalIDField>	Quality Center user field of type String that stores the unique ID for the Rally work item. Refer to the Create an External ID User Field in Quality Center section above.	TS_USER_01	Y

Quality Center Run connection
Same as QCConnection except parent tag is <QCRunConnection> and some additional tags:

Parent Tag	Tag Name	Description	Sample Values	Required
QCRunConnection	<TestExternalIDField>	Quality Center user field of type String on TEST table that stores the unique ID for the Rally work item.	TS_USER_xx	Y
QCRunConnection	<RunDaysToSearch>	Specified in days, this is the time period within which the connector looks into the past, for new QC Runs to be copied to Rally TestCaseResults (and associated with a Rally TestCase). The default is one (1) day.	2	N

Connector tags

Parent Tag	Tag Name	Description	Sample Values	Required
ConnectorRunner	<Preview>	Allows you to enable a preview mode for testing where NO objects are copied/updated in either system.	false true
ConnectorRunner	<Services>	Determine what type of services to run. Be careful if you update in both directions because whichever system runs the update first will overwrite the updates of the other system.	COPY_OTHER_TO_RALLY, COPY_RALLY_TO_OTHER, UPDATE_OTHER_TO_RALLY, UPDATE_RALLY_TO_OTHER	Y
ConnectorRunner	<LogLevel>	Determines what type of messages are written to the log file. The highest level is Debug where all messages are displayed. The default log level is Info.	Fatal, Error, Warn, Info, Debug
Connector	<FieldMapping>	Determine what fields map between the two systems.	See Field Mapping section below.	Y
Connector	<OtherFieldHandlers> <OtherEnumFieldHandler>	Allows a user to map non-alike drop-down values between the two systems.	See Mapping Drop-down Values section below.

Tip: Incrementally set up the connector! Start with a basic configuration file, test that you can connect to Quality Center and Rally in a "test" environment. Once you validate this is setup correctly, then start customizing the field mapping and field handler sections.

Field mapping

The field mapping section is located between the <Connector> tags in the configuration file and defines what fields map between the two systems.

For example, this definition sets up a mapping between the Rally field Name with the field Headline in the other system. On a create or update, the connector will only update the Name field in Rally and the Headline field in the other system.

When you set up your mapping between the two systems, ensure the fields are compatible between the two systems (an integer field should map to an integer field in the other system, a rich text should map to a rich text in the other system).

Otherwise, you might experience situations where information is not created/updated between the two systems and you will see an error in the log file. For example, the connector will post an error for a particular work item if you try to post a string to a custom field of type integer in Rally.

You can add subsequent mappings by appending to this list. For example, this sets up a mapping to Rally Name → Headline, Rally Description → Description, Rally Priority → Priority:

If you are mapping a drop-down value in Rally to the other system, this assumes that the drop-down values match. Otherwise, the connector will throw an error letting you know the value was not found in the list.

If your drop-down values are different between the two systems, see the next section called Mapping Drop-down Values.

Field handlers

Mapping Rally Test Result to Test Case (Required for runs)

When copying a Quality Center run to a Rally test case result, a Rally test case result must be created with an association to a test case. When a new run is found in Quality Center, the connector finds the ID for the associated test in Quality Center if the field mapping is setup correctly. For example:

The connector then uses the RN_TEST_ID value to look-up the linked test case in Rally based on this ID. Consequently, the connector needs to know which custom field on the Rally test case holds the QC test unique ID. Once the custom field name is known, add a RallyReferenceFieldHandler for TestCase. This example uses "ExternalID" for the Rally custom field name.

Mapping Run Dates (Required for runs)

A date on a Rally test case result is a required field. The date on a Quality Center run is represented in two fields, called RN_EXECUTION_DATE and RN_EXECUTION_TIME, and the connector needs to know how to convert those values to a Rally date (ISO 8601 UTC). To support mapping Quality Center run dates to Rally test case result dates, add a field mapping and QCRunDateFieldHandler in the OtherFieldHandlers section. For example:

Mapping Rally Test Case to Rally Story (Optional for tests)

To track the Quality Center test status on stories in Rally, the Quality Center tester can enter the formatted ID of the Rally story on the test in Quality Center. Add a field mapping and RallyReferenceFieldhandler to support this feature.

First, the config file for tests will need to map the Rally story (WorkProduct behind the scenes) to the QC user field that stores the formatted ID to .

Second, add a RallyReferenceFieldHandler to the RallyFieldHandlers section that informs the connector to look-up the story by formatted id.

Mapping drop-down values
Mapping users
Mapping reference fields

4.1.4 Run the connector

Once the qc_config*.xml files are setup, you can start running the connector. On Windows, you can simply open a DOS shell and type:

to start the service.

Double-click on WinTail.exe to run WinTail. In WinTail, open the file rallylog.log to watch the log messages generated by the connector. This is an easy way to confirm that the connector is working properly, or to discover any errors.

Tip: We ship a startqc-test.bat file to make it easier to test. Double-click on the batch file to automatically run the connector and open the log file in WinTail.

To stop the service, use Control-C in the command shell.

Multiple configuration files

For users who want to map to more than one workspace in Rally, need to map multiple artifact types or need to map to multiple containers (such as domain/projects in Quality Center or ClearQuest databases) in the other system, setting up multiple configuration files may make sense. Rally recommends naming the configuration files using descriptive names for easier troubleshooting.

To run multiple instances of the connector for different configuration files, pass in the list of config files as arguments to the rally2*_connector.rb script or rally2*_connector.exe.

The connector will process the configuration files based on the command line argument order, and processes one file at at time.

Once it processes every configuration file, the connector will sleep based on the sleep value. The default is 15 minutes. To change the sleep value between runs, set this value (in minutes) as the last command line argument.

*We recommend a sleep value of 10 minutes or more and advise against anything less.

5.1 Troubleshooting the connector

Once the connector is running, all errors are written to a log file in the directory where the rally2_* file resides. Informational messages, warning and errors are written to the log file depending on the value of the <LogLevel> tag in the <ConnectorRunner> section of the config file.

To see the most recent log messages on Windows, rename the extension of the WinTail file from .dat to .exe and then double-click on the WinTail.exe and browse to the rallylog.log file.

Before the connector starts synchronizing objects between the two systems, it performs a validation that confirms that 1) Connecting to Rally is successful, 2) Connecting to the other system is successful, 3) Fields in the field mapping exist in Rally and the other system, and 4) Ensures that each field handler has a corresponding field mapping section in the configuration file.

To confirm the validation is successful without moving objects between the two systems, ensure you set the <Preview> tag in the configuration file to true. This acts as a good trick if you want to experiment with some different configuration options to debug an issue.

If you still cannot determine the root cause of an issue, then please email the entire log file and config file to Rally Support.

6.1 Tips

• Mapping Rally Projects: If you are copying tests from Quality Center to Rally using the RallyReferenceFieldHandler with Projects, you may see a "Could not find Rally Project with name ..." error in the log file if the connector user does not have "Editor" permissions to that project in Rally.
• Pessimistic Locking in Quality Center In QC: When an entity is selected in Quality Center, QC assumes that you are editing the record and locks the entity. The update RALLY_TO_OTHER service will not update an entity in QC which was modified in Rally, if you have locked the record in QC.

7.1 Known issues

1. Mapping Release/Iterations with Multiple Projects: If you are using a <RallyReferenceHandler> to map Releases/Iterations with the same name and multiple projects, you may receive an error if the Release/Iteration you are updating on the Test references a different Project than the given Test is assigned. The connector only returns the FIRST Release/Iteration with the matching name in Rally so it could have a reference to a Release/Iteration in a different project.