Quality Center Installation & User Guide

Please note: Rally also offers an app for connecting with Quality Center which is different from this connector. This connector is based on an architecture which supports customizations not supported by the app (such as custom fields, extending the code, etc.).

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 defects, requirements, tests and test runs. The connector provides synchronization between Quality Center and Rally by allowing the user to:

• synchronize Quality Center Defects with Rally Defects,
• synchronize Quality Center Requirements with Rally User Stories,
• synchronize Quality Center Tests with Rally Test Cases,
• push Test Runs from Quality Center to Rally Test Case Results.

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 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; one for each project to store the unique id of the linked object. The connector copies fields to/from Rally or Quality Center based on a field mapping specified in the configuration file. Both standard and custom fields can be mapped between the two systems.

The connector provides four services which 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 of the above services to run, and in what order.

It is important to recognize that the data models of Rally and QualityCenter are not identical and, as such, they are only partially compatible. We recommend that you take some time to identify the key data items you want to track in both systems and what you want the policy to be as far as having a primary system of record. You'll see specific information later in this document discussing some of the trade-offs to be considered and some potential approaches.

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

3.0 Software and hardware requirements

This connector is available to Unlimited Edition customers and to customers with the HP Integration module. Click on 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've received a response and obtained the installation package, proceed with the following tasks.

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 Connector can be installed in a number of ways. There can be multiple install locations on the same machine which can run in parallel which determine 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

3.1 Pre-installation checklist

1. Project and Site Administration access to a "test environment" of QC
2. Rally administrator privileges are needed for setup but only user access is needed to run the connector
3. Proxy server details if the machine used to run the connector uses a proxy server (described below).
4. Before invoking the connector on a machine, you must access QC from an IE browser in order to download the required DLL files:
   • For QC 10, you must navigate your Internet Explorer to the URL of your QC 10 installation. The necessary DLL files will be downloaded automatically when the page loads and are then in place for use by the Connector.
   • 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, you would 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 select either "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. When you eventually run this executable file, it takes under a minute to run and displays an alert dialog informing you of the installation disposition (completed or failed).
     5. Upon a successful installation, the necessary DLL files are in place for use by the Connector.
   • Upgrades: Sometimes even an upgrade, say from patch level SP2 to SP3, will require a new DLL to be installed (the QC TDConnector add-in procedure).

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 (such as creating custom fields).
3. Edit the qc_config.xml to reflect your environment.
4. Run rally2_qc_connector.exe 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/www-cache:8000. You may need to restart your system in order for the change to take effect.

Installation for Windows

Double-click the RallyConnectorforQualityCenterInstall-<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\RallyConnectorforQualityCenter on Windows XP, and in C:\Program Files (x86)\RallyConnectorforQualityCenter for Windows 7):

1. rally2_qc_connector.exe - Executable to run the connector.
2. qc_config.xml - Sample configuration file.
3. WinTail.exe* - Utility to tail the log file output for debugging purposes.
4. startqc.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. Navigate 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 Defect or whatever work item you are mapping.
5. Click Actions → New Field.
6. Enter a Name of ExternalID, 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, but the name you choose must conform to these rules:

   • Begin with an uppercase letter
   • Less than 41 characters (40 is the maximum for display name)
   • No underscores, dashes, or spaces.

    

   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. For example, 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.

The update service from Rally to QC is workspace scoped, meaning the connector looks for any artifact 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 to Tools → Customize → Project Entities.
2. Expand Defect or Requirement 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 on the Save button. A dialog displays with the message "The changes were saved successfully".

Make note of the Field Name (NOT the Field Label) of this field (such as BG_USER_xx). You will enter this value (BG_USER_xx) in the <ExternalID> element of the configuration file under <QCConnection>.

If you are adding a field to the Requirement table, you also need to make the new user field available for the appropriate requirement types:

1. Select Requirement Types on the Project Customization screen (from Tools → Customize)

   Note that the user field you just added is automatically in the In Type list for the Undefined requirement type. For each additional requirement type that you want to map between Rally and Quality Center, select the requirement type (such as Functional) in the Types list on the left, select the user field you created above in the Not In Type list, and finally click the > button to move it over to the In Type list.

2. When you have added the field to all the appropriate requirement types, click Save.

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, the default configuration file has a name of qc_config.xml. We recommend making a backup copy of the qc_config.xml (and naming it something like qc_config.xml-orig or qc_config-pristine.xml) in case you need to reference a valid configuration file later. You can also name the qc_config.xml file you edit for your purposes to a name of your choosing. For the purposes of this document, we'll retain the name of qc_config.xml.

Edit qc_config.xml by entering the appropriate values between each begin and end tag.

Each major section is surrounded by a tag (called an XML element) to delineate that section. In the example above, here is a description of each section:

• RallyConnection
  Defines the connection information for Rally, including Rally URL, user, password, and so on.
• QCConnection
  Defines the connection information to Quality Center including domain name, project name, artifact type, user, etc.
• Connector
  Defines the field mapping between the two systems. Generally, strings should be mapped to strings, integers to integers, and so on.
• ConnectorRunner
  Specifies parameters related to the services the connector is to run.

Definition of tags in configuration file

Tags allowed/required in the section describing the Rally Connection:

<RallyConnection>

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

Tags allowed/required in the section describing the Quality Center Connection:

<QCConnection>

Tags allowed/required in the section describing the Connector:

<Connector>

Tags allowed/required in the section describing the Connector Runner:

<ConnectorRunner>

Tip: We strongly suggest that you incrementally set up the connector. First, start with a basic configuration file. Ensure that you can connect to Quality Center and to Rally in a "test" environment using this configuration file. Once you have validated this setup, then begin customizing the field mapping and field handler sections of the configuration file.

Field mapping

The field mapping section is located between the <Connector> tags in the configuration file and defines what fields are to be mapped 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/or 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 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.

CopySelector and UpdateSelector

The CopySelectors and UpdateSelectors for QC will support the same syntax which can be used within the QC system. Examples:

Mapping QC markup fields

Some fields in QC contain rich-text (basically markup metadata) to achieve bolding, underlining, bulleting, etc. This rich-text is usually different between QC and Rally. The field handler <QCRtfFieldHandle> allows:

• mapping BG_DESCRIPTION
• mapping BG_DEV_COMMENTS
• mapping TS_DESCRIPTION

An example of mapping BG_DESCRIPTION:

Mapping QC attachments

If you want attachments in Quality Center accessible when viewing the corresponding artifact (story, defect, test) in Rally, it can be done by creating a link in Rally which points to the attachment location. This is possible with HP Quality Center but differs in the implementation between HP QC 10 and HP ALM 11.

Note: This mapping is only supported in the QC to Rally direction.

Note: The QC connector supports this capability for the Bug, Requirement and Test items only.

HP QC 10 Attachments

In HP QC 10, all attachments for each Quality Center domain/project are stored in a fixed location on the disk of the Quality Center server. Therefore, if this folder is shared, its contents could be viewed from some client. You may need to contact your Quality Center administrator to setup a shared network drive with access to the attachments folder for the specific domain/project.

You must create a custom field in Rally of type Text, which will be used to store the references (links) to the QC attachments (the field name in the example below is QCAttachments). Then use syntax similar to the following in your configuration file:

In this example, the Rally field handler <QCAttachmentFieldHandler> will store links in the following format (if you viewed the raw text for the Rally rich text field):

The field handler will append additional attachments as follows:

HP ALM 11 Attachments

HP ALM/QC 11 stores attachments in a collection of folders on the QC server in a way that is much less predictable than for QC 10. However, HP ALM 11 offers a REST API that permits a straightforward and deterministic way of referencing the attachments as links.

Use the field handler <QCUrlAttachmentFieldHandler> to handle mapping between QC and Rally as follows:

Similar to the QC 10 example, the QCUrlAttachmentFieldHandler will store links in the following format:

Mapping dates

Quality Center has a set of date fields for artifacts where the format needs to be a string composed of a date, but equivalent fields in Rally may be in a string composed of date and time. The field handler <QCDatetimeToDateFieldHandler> will allow such date fields to be translated between the two systems.

We recommend using this field handler for the following standard Quality Center fields:

• mapping BG_CLOSING_DATE
• mapping BG_DETECTION_DATE
• mapping RQ_REQ_DATE
• mapping TS_CREATION_DATE

An example configuration file snippet for date mapping:

In Rally, the CreationDate is a read-only field. It is on an artifact, put there by the underlying database and therefore the user can not modify this field. In the example above, we have placed a <Direction> tag. While the tag is not actually required in this instance, we use it to reinforce the fact that this field can never be modified by the user in Rally. If a configuration file maps into this Rally field, it will be silently ignored (no data is copied or updated in this Rally field).

Mapping TS_NAME

Quality Center has a set of forbidden characters when creating a name for a Test. To handle this, there is a field handler for TS_NAME which will remove the forbidden characters when pushing updates or creates from Rally to QC.

Note: If the UPDATE_OTHER_TO_RALLY service is also specified, the new updated name from QC will change the Rally name to the QC name which contains none of the forbidden characters.

For TS_NAME, the following eleven characters are removed:

Mapping RQ_REQ_NAME

Quality Center has a set of forbidden characters when creating a name for a Requirement. To handle this, there is a field handler for RQ_REQ_NAME which will remove the forbidden characters when pushing updates or creates from Rally to QC.

Note: If the UPDATE_OTHER_TO_RALLY service is also specified, the new updated name from QC will change the Rally name to the QC name which contains none of the forbidden characters.

For RQ_REQ_NAME, the following three characters are removed:

To configure the field handler, your field mappings section must have either TS_LINKED_REQ or BG_LINKED_REQ mapped:

For Test to Story:

Note: For the above, specify the custom field you created in Quality Center to contain the ID of the Rally User Story (RQ_USER_nn in the above example). This should be the same as the field in the configuration file which was previously used to copy the Requirements to User Stories.

For Defect to Story:

Note: For the above, specify the custom field you created in Quality Center to contain the ID of the Rally User Story (RQ_USER_nn in the above example). This should be the same as the field in the configuration file which was previously used to copy the Requirements to User Stories.

An important note: The connector will log a warning if multiple requirements are linked to a Test or Defect when this field handler runs.

Mapping reference fields from Quality Center

The field handler <QCReferenceFieldHandler> enables the following:

• mapping BG_DETECTED_IN_RCYC
• mapping BG_DETECTED_IN_REL
• mapping BG_TARGET_REL

Important note: This mapping is only supported in the direction of Quality Center to Rally. The data will not be mapped from Rally to Quality Center.

In the following example, the <QCReferenceFieldHandler> field handler is used to extract the Name from a QC object. The <RallyReferenceFieldHandler> is used to insert this Name into a Rally object.