Installation & User Guide for Rally's connector to Quality Center

The Rally connector for Quality Center allows customers to use Rally for Agile lifecycle management while still using Quality Center (QC) for management of defects, requirements, tests, and test runs. The connector provides the ability to reflect work items between Quality Center and Rally. Reflection of work items generally involves matching the values of a small number of key fields between the two systems. It does this by allowing you to:

  • Reflect Quality Center defects in Rally as defects
  • Reflect Quality Center requirements in Rally as user stories
  • Reflect Quality Center tests in Rally as test cases
  • Push test runs from Quality Center to Rally test case results

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 in each system to store the unique ID of the linked objects in the other system. The connector copies fields to and 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 five services which effect the reflection 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
  • Update Rally fields and Quality Center fields

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

An alternative update service, UPDATE_RALLYFIELDS_AND_OTHER, searches Rally first for updates and pushes only the recently changed mapped-fields to the QC system. It then searches the QC system for updates and, when found, pushes all mapped fields into Rally.

This reduces the chances of overwrites of data. The only scenario where an overwrite might occur is if User-A made changes in Rally and User-B made changes in the QC system for the same fields. In this case, the Rally information is copied over to the QC system (possibly overwriting the data in the QC system), then all data is copied over to the Rally system.

It is important to recognize that the data models of Rally and Quality Center 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. There is specific information later in this document discussing some of the trade-offs to be considered and some potential approaches.

Note: Rally will no longer maintain the connector with bug fixes against Quality Center version 9 or version 10. Support will continue to assist with general usage issues. The connector is fully supported when used with HP QC 11, 11.5 and HP ALM 12.

This connector is available to Unlimited Edition customers and to customers with the HP Integration module.

Support / Feedback

Log in to the Rally Community for support of this and all of our connectors. The Rally Community is your one stop shop for self service and support. Accessing the Rally Community is quick and easy!

To sign up:

  1. Navigate to https://rallycommunity.rallydev.com/signin.
  2. First time to the site? Click Not a member?
  3. Complete the self-service registration form to be automatically logged into the Rally Community

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.

This web page contains the following sections:

System setup

Rally Integrations FAQ and Best Practices contains some very useful information.

Software and hardware requirements

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

  • Rally subscription
  • Windows XP, Windows 7, or Windows 2003/2008/2012 Server
  • HP Quality Center 10.0 with patch 7 or HP Quality Center 11.0 or HP Quality Center 11.5 or HP ALM 12
  • Internet Explorer 9.0 or beyond (10.0, 11.0)

Hardware

You can install the connector several 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:

  • Base hardware of a Pentium IV or greater processor with 512MB of RAM for one installed location
  • No more than 5 to 10 configuration files per install location
  • If you add more install locations running in parallel, 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

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.
  4. Before invoking the connector on a machine, you must access QC from an IE browser in order to download the required DLL files (Important: It must be IE 32-bit, not 64-bit; and must be invoked with Run as administrator).
    • For HP ALM 12, use Internet Explorer 9 (or greater) to access the initial page for QC. For example, if you installed HP ALM 12 on a server named almserve and configured it to service connections on port 8080, you would navigate to http://almserve:8080/qcbin.
      1. Once the initial page displays with a panel of links, click the Tools link.
      2. On the resultant Application Life Cycle → Tools page, click the HP ALM Connectivity link.
      3. Once the HP ALM Connectivity Tool page displays, click the Download HP ALM Connectivity link at the bottom of that page.
      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 (10 MB) and run it after the download completes. When you run the downloaded.exe, it takes under a minute to run and displays an alert dialog with the installation disposition (completed or failed).
        • You must download the new OTA.DLL for HP ALM 12 before using the new connector.
      5. Upon successful installation, the necessary DLL files are in place for use by the connector.
    • For QC 11, use Internet Explorer 9 to access the initial page for QC. For example, if you 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.
      1. Once the initial page displays, click Add-Ins Page.
      2. Click HP Quality Center Connectivity.
      3. Click Download Add-In.
      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 (10 MB) and run it after the download completes. When you run the downloaded.exe, it takes under a minute to run and displays an alert dialog with the installation disposition (completed or failed).
      5. Upon successful installation, the necessary DLL files are in place for use by the connector.
    • For QC 10, use Internet Explorer to access the URL of your QC 10 installation. The necessary DLL files are downloaded automatically when the page loads and are then in place for use by the connector.
    • Upgrades: Sometimes even an upgrade, such as patch level SP2 to SP3, will require a new DLL to be installed (the QC TDConnector add-in procedure).

Get the Quality Center connector

The connector runs on a Windows computer behind your firewall using Quality Center's TD API and accesses Rally through the Rally Web Services API. Most fields between the two systems can be synchronized. The connector supports QC 10, QC 11, QC 11.5 and HP ALM 12.

Consider the following:

  • The following people are involved in getting fields set up in both Rally and QC:
    • A Quality Center administrator user who can create the QC custom fields you want to synchronize with Rally.
    • A Rally administrator user who can create the custom fields on the Rally artifact you want to synchronize with QC.
    • Someone with access to the Windows machine described above to install and configure the connector.
  • Consider the process you want to setup between Rally and QC:
    • Where do objects start and end their lifecycle?
    • Which fields need updated?
  • Identify a test domain or project in Quality Center to use for testing the connector.
  • Identify a test Rally workspace or project to use for testing the connector.
  • The Windows machine being used must have visited the Quality Center web page from IE to ensure the TDAPI client DLLs used by the connector have been installed.

To obtain the Rally connector for Quality Center, click the Contact Support link at the bottom of any page in Rally to open a support case and request the connector. Once you have received a response and obtained the installation package, proceed with the following tasks.

If you have upgraded from QC 11.x to HP ALM 12 and have run the Rally Connector for Quality Center against the QC 11.x server and you now want to run the connector against the HP ALM 12 server, you'll need to remove the result of running the TDConnect.exe installation for QC 11.x first before running the TDConnect.exe for HP ALM 12.

Install the connector

(Optional) If your site uses a proxy server to access Rally, you will need to set the http_proxy environment variable. This can be done one of two ways on Windows 7:

  • Define a permanent system variable:
    1. From Start, right-click on Computer, then select Properties.
    2. Click Advanced system settings.
    3. From System Properties, click Environment Variables.
    4. From Environment Variables → System variables, click New.
    5. On New System Variables, enter http_proxy in the Variable name: field, then enter your proxy's full HTTP Url in the Variable value: field (for example, http://www-cache:8000).
    6. Click OK three times to save and exit this process.
    7. You may need to restart your system in order for the change to take effect.
  • One-time use in a command window:

    In an MS-DOS command window, set the environment variable before invoking the connector with the following command:

    set HTTP_PROXY=http://username:password@myproxy.company.com:8000

Installation for Windows

Double-click the RallyConnectorforQualityCenterInstall-x.x.x-yyy.exe to open the install wizard. Follow the prompts to complete the installation.

install

The Windows installer installs the following files (by default in C:\Program Files\RallyConnectorforQualityCenter on Windows XP, and in C:\Program Files (x86)\RallyConnectorforQualityCenter for Windows 7):

  • rally2_qc_connector.exe: Executable to run the connector
  • qc_config.xml: Sample configuration file
  • WinTail.exe*: Utility to tail the log file output for debugging purposes
  • startqc.bat: Batch file that automatically runs the connector and shows the log file that is 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.

Quality Center setup

Create an External ID user field in Quality Center

HP ALM 12 actions

  1. Using the ALM Desktop Client, navigate to the appropriate Domain and Project.
  2. Near the upper right of the page, click on the gear icon and select the Customize menu item.
  3. On the left side of the page, click on the Project Entities item.
  4. Expand Defect or Requirement in the list of Project Entities.
  5. Select the User Fields folder.
  6. Click on the 'New Field' icon (with the green plus symbol above the list of Project Entities).
  7. Provide a Field Label for the field, select Field Type as String with a 40 character limit and leave the default checkboxes for all other options.
  8. Click Save. A dialog should display that states The changes were saved successfully.

For HP ALM 12:

  • On the Application Lifecycle Management - Project Customization page, click the 'Requirement Types' on the left side.
  • In the column where the the Requirement Types are listed, for each entry, click the type name and then mark the checkbox under the In Type column for the field you added to the Requirement table.
  • Click Save. A dialog should display that states The changes were saved successfully.

QC 10, QC 11, QC 11.5 actions

    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 New Field 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 checkboxes for all other options.
    6. Click Save. A dialog displays The changes were saved successfully.

    Make note of the Field Name (not the Field Label) of this field (such as BG_USER_XX).

    Enter this value (BG_USER_XX) in the <ExternalID> element of the configuration file which is within the <QCConnection> element.

    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.

For QC 10.0, QC 11.0 and QC 11.5:

  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:

    1. Select the requirement type (such as Functional) in the Types list on the left.
    2. Select the user field you created above in the Not In Type list.
    3. 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.

Create a CrosslinkUrlField in QC

It can be useful to have reference information in the QC work item that will relate to the corresponding Rally artifact. The <CrosslinkUrlField> element in the <QCConnection> section of the configuration file allows you to specify the name of the custom field that will contain this reference (String).

  • We suggest a field name of RallyLink or RallyURL
  • Must be a String field
  • This field name will be used in the <CrosslinkUrlField> element within the <QCConnection> section of the configuration file
  • Note: This URL field is only supported on the QC side, and not on the Rally side.

Rally setup

Rally accesses fields from their Display Name, not their Name. Spaces and underscores are removed, for example, Example Field becomes ExampleField.

Create an External ID field in Rally

  1. Log into Rally as a workspace or subscription administrator.
  2. Go to SetupWorkspaces & Projects.
  3. Select the workspace that you wish to map to Quality Center.
  4. On the workspace's detail page, select the Fields link in the sidebar and ensure the Work Item 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: This field can not be of type Text).

    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 will be using the Rally / HPQC Work Item connector with multiple Rally projects and multiple HPQC projects in the same domain, we recommend that you use <UpdateSelector>Project.Name = "Example Project"</UpdateSelector> in the <RallyConnection> section of the config to avoid excessive warning messages where multiple QC items may have the same ID across multiple QC projects.

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 TestCaseResults, so only complete this step for the HierarchicalRequirement, Defect and Test Case work item types.

The update service is workspace scoped, meaning the connector searches 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 updates the correct work item in Quality Center. Work item IDs are not unique across Quality Center projects.

Connector configuration

The connector could be used in one of two ways:

  • WorkItem mode - the connector is used to copy/update UserStories/Defects, between Rally & QC.
  • Test mode - the connector is used to copy/update QC Test & Run artifacts to Rally TestCase & TestCaseResult artifacts.

WorkItem mode

A configuration file is used to instruct the connector on what actions to perform. A sample 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 give your configuration file any name of your choosing. For the purposes of this document, we retain the name of qc_config.xml.

Edit your configuration file (or the default qc_config.xml) and enter the appropriate values between each XML begin and end tag.

<Config>
        <RallyConnection>
                <Url>rally1.rallydev.com</Url>
                <WorkspaceName>Workspace Name</WorkspaceName>
                <Projects>
                        <Project>Project Name 1</Project>
                </Projects>
                <User>user@company.com</User>
                <Password>password</Password>
<!-- You can use an APIKey in place of User and Password tags -->
        <!-- <APIKey>YourAPIKeyValueGoesHere...</APIKey> -->
                <ArtifactType>Defect</ArtifactType>
                <ExternalIDField>ExternalID</ExternalIDField>
        <!--    <UpdateSelectors>
                        <UpdateSelector>State = Open</UpdateSelector>
                        <UpdateSelector>Priority = High</UpdateSelector>
                </UpdateSelectors>
                <FieldDefaults>
                        <Field><Name>RootCause</Name><Default>Undefined</Default></Field>
                </FieldDefaults>
        -->
        </RallyConnection>

        <QCConnection>
                <Url>server:port</Url>
                <Domain>Domain Name</Domain>
                <Project>Project Name</Project>
                <User>qcusername</User>
                <Password>password</Password>
                <ArtifactType>BUG</ArtifactType>
        <!--    <CopySelectors>
                        <CopySelector>BG_STATUS   = Open</CopySelector>
                        <CopySelector>BG_PRIORITY = High Attention</CopySelector>
                        <CopySelector>RQ_REQ_NAME = (WebExample1 Or WebExample2) </CopySelector>
                </CopySelectors>
        -->
                <IDField>BG_BUG_ID</IDField>
                <ExternalIDField>BG_USER_XX</ExternalIDField>
                <ExternalEndUserIDField>BG_USER_YY</ExternalEndUserIDField>
        </QCConnection>

        <Connector>
                <FieldMapping>
                        <Field><Rally>Name</Rally><Other>BG_SUMMARY</Other></Field>
                </FieldMapping>
        </Connector>

        <ConnectorRunner>
                <Preview>False</Preview>
                <LogLevel>Debug</LogLevel>
                <Services>UPDATE_RALLY_TO_QC,  COPY_QC_TO_RALLY</Services>
        </ConnectorRunner>
</Config>

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, username and password or APIKey.

  • QCConnection

    Defines the connection information to Quality Center including domain name, project name, artifact type, user, and so on.

  • 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.

Test mode

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

The Rally Connector for Quality Center allows you 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 Tests)
  • Runs from Quality Center to the TestCaseResults in Rally

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 following graphic depicts the recommended workflow when using Quality Center for test management.

workflow

The configuration file is 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.

  1. Edit the test configuration file (such as the qc_config_test.xml) by entering the appropriate values between each begin and end tag.
  2. <Config>
            <RallyConnection>
                    <Url>rally1.rallydev.com</Url>
                    <WorkspaceName>Workspace Name</WorkspaceName>
                    <Projects>
                            <Project>Project Name 1</Project>
                    </Projects>
                    <User>user@company.com</User>
                    <Password>password</Password>
    <!-- You can use an APIKey in place of User and Password tags -->
            <!-- <APIKey>YourAPIKeyValueGoesHere...</APIKey> -->
                    <ArtifactType>testcase</ArtifactType>
                    <ExternalIDField>ExternalID</ExternalIDField>
            <!--    <CopySelectors>
                            <CopySelector>State = Open</CopySelector>
                            <CopySelector>Priority = High</CopySelector>
                    </CopySelectors>
            -->
            </RallyConnection>

            <QCConnection>
                    <Url>server:port</Url>
                    <Domain>Domain Name</Domain>
                    <Project>Project Name</Project>
                    <User>qcusername</User>
                    <Password>password</Password>
                    <ArtifactType>TEST</ArtifactType>
                    <TestFolder>MyTestFolder</TestFolder>
                    <IDField>TS_TEST_ID</IDField>
                    <ExternalIDField>TS_USER_xx</ExternalIDField>
            </QCConnection>

            <Connector>
                    <FieldMapping>
                            <Field><Rally>Name</Rally><Other>TS_NAME</Other></Field>
                    </FieldMapping>
            </Connector>

            <ConnectorRunner>
                    <Preview>False</Preview>
                    <LogLevel>Debug</LogLevel>
                    <Services>UPDATE_QC_TO_RALLY,  COPY_QC_TO_RALLY</Services>
            </ConnectorRunner>
    </Config>
  3. Edit the run configuration file (such as the qc_config_run.xml) by entering the appropriate values between each begin and end tag.
  4. <Config>
            <RallyTestResultConnection>
                    <Url>rally1.rallydev.com</Url>
                    <WorkspaceName>Workspace Name</WorkspaceName>
                    <Projects>
                            <Project>Project Name 1</Project>
                    </Projects>
                    <User>user@company.com</User>
                    <Password>password</Password>
    <!-- You can use an APIKey in place of User and Password tags -->
            <!-- <APIKey>YourAPIKeyValueGoesHere...</APIKey> -->
                    <ArtifactType>test case result</ArtifactType>
            </RallyTestResultConnection>

            <QCRunConnection>
                    <Url>server:port</Url>
                    <Domain>Domain Name</Domain>
                    <Project>Project Name</Project>
                    <User>qcusername</User>
                    <Password>password</Password>
                    <ArtifactType>RUN</ArtifactType>
                    <TestFolder>MyTestRunFolder</TestFolder>
                    <IDField>RN_RUN_ID</IDField>
                    <ExternalIDField>RN_USER_xx</ExternalIDField>
                    <!-- QC user field on TEST table that stores the unique id for the Rally work item -->
                    <TestExternalIDField>TS_USER_xx</TestExternalIDField>
                    <!-- By default, the connector will only "look back" 1 day for new QC Runs to be
                         copied to Rally TestCaseResults (and associated with a Rally TestCase).
                         Use the following XML tag to change the number of days to search.
                    -->
                    <RunDaysToSearch>2</RunDaysToSearch>
            </QCRunConnection>

            <Connector>
                    <FieldMapping>
                            <!-- The required 4 fields on a Rally TestCaseResult object: -->
                            <Field><Rally>Date</Rally>      <Other>RN_EXECUTION_DATE</Other> </Field>
                            <Field><Rally>Build</Rally>     <Other>RN_RUN_NAME</Other>       </Field>
                            <Field><Rally>TestCase</Rally>  <Other>RN_TEST_ID</Other>        </Field>
                            <Field><Rally>Verdict</Rally>   <Other>RN_STATUS</Other>         </Field>
                    </FieldMapping>

                    <RallyFieldHandlers>
                            <!-- Required field handler: Determines how to lookup the associated test in Rally -->
                            <RallyReferenceFieldHandler>
                                    <FieldName>TestCase</FieldName>
                                    <!-- Custom field on Rally TestCase to store the unique id for linked QC test -->
                                    <ReferencedFieldLookupID>ExternalID</ReferencedFieldLookupID>
                            </RallyReferenceFieldHandler>
                    </RallyFieldHandlers>

                    <OtherFieldHandlers>
                            <!-- Required field handler which will convert a QC run date into a Rally date: -->
                            <QCRunDateFieldHandler>
                                    <FieldName>RN_EXECUTION_DATE</FieldName>
                            </QCRunDateFieldHandler>

                            <OtherEnumFieldHandler>
                                    <FieldName>RN_STATUS</FieldName>
                                    <Mappings>
                                            <!-- Add additional mappings between Rally verdict and RN_STATUS -->
                                            <Field><Rally>Fail</Rally>      <Other>Failed</Other></Field>
                                            <Field><Rally>Pass</Rally>      <Other>Passed</Other></Field>
                                    </Mappings>
                            </OtherEnumFieldHandler>
                    </OtherFieldHandlers>
            </Connector>

            <ConnectorRunner>
                    <Preview>False</Preview>
                    <LogLevel>Debug</LogLevel>
                    <!--- Only the COPY_QC_TO_RALLY service is supported for RUNs -->
                    <Services>COPY_QC_TO_RALLY</Services>
            </ConnectorRunner>
    </Config>

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, username and password or APIKey.
  • <RallyTestResultConnection>
    Defines the connection information to Rally including Rally URL, username and password or APIKey. Supports Rally test results only.
  • <QCConnection>
    Defines the connection information to Quality Center including domain name, project name, artifact type, user, and so on. Used when mapping bugs and requirements.
  • <QCRunConnection>
    Defines the connection information to Quality Center. Used when mapping tests and more.
  • <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.

Field mapping

The field mapping section is located within the <Connector> element in the configuration file. It defines which fields are to be mapped between the two systems.

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

<Config>
  ....
  <Connector>
    <FieldMapping>
      <Field>
        <Rally>Name</Rally>  <Other>Headline</Other>
     </Field>
    </FieldMapping>
    ....

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 or 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 of Rally Name to QC Headline, and Rally Description to QC Description, and Rally Priority to QC Priority:

<Config>
    ....
    <Connector>
        <FieldMapping>
            <Field><Rally>Name</Rally>         <Other>Headline</Other></Field>
            <Field><Rally>Description</Rally> <Other>Description</Other></Field>
            <Field><Rally>Priority</Rally>       <Other>Priority</Other></Field>
        </FieldMapping>
        ....

If you are mapping a drop-down value in Rally to the other system, this assumes the drop-down values match. Otherwise, the connector generates an error that the value was not found in the list. If your drop-down values are different between the two systems, see Map Drop-Down values.

Individual fields may also have a directionality specified, whereby that specific field will be mapped in one direction only. For more information on this feature, see Field Directionality.

CopySelector and UpdateSelector

The FAQ has a section of general information about using the <CopySelector> and <UpdateSelector>.

However, the QC connector does not allow for multiple tests on the same field. It does support the same syntax which can be used within the QC GUI, which allows for more complex testing. Here are a few examples of <CopySelectors> in the <QCConnection> section of the configuration file:

<CopySelectors>
    <CopySelector>BG_USER_02 = Y</CopySelector>
    <CopySelector>BG_STATUS = (Not Closed And Not Fixed)</CopySelector>
</CopySelectors>
<CopySelectors>
    <CopySelector>BG_USER_02 = Y</CopySelector>
    <CopySelector>BG_PROJECT = (Not "")</CopySelector>
</CopySelectors>
<CopySelectors>
    <CopySelector>BG_USER_02 = Y</CopySelector>
    <CopySelector>BG_STATUS = (Open Or Reopen)</CopySelector>
</CopySelectors>
<!-- To select QC Requirements 4 and 5 only: -->
<CopySelectors>
    <CopySelector>RQ_REQ_ID = (>3 And <6)</CopySelector>
</CopySelectors>
<CopySelectors>
    <CopySelector>BG_USER_03 = (Not (ABC or DDM))</CopySelector>
</CopySelectors>
<CopySelectors>
    <CopySelector>BG_USER_03 = (Not ("ABC DEF" or "GHI JKL"))</CopySelector>
</CopySelectors>

Selectors and requirements

If you want to use a requirements folder in the CopySelectors, you must surround your condition with ^ characters and you must enclose the whole expression in parentheses. You must also fully qualify the path to your requirements folder. See the example below.

If you are unfamiliar with how filters are defined and expressed in QC, consider the following. In QC, open up the Filter. Once you have expressed your conditions and the results are as you desired, then click the Copy Filter icon (the second from the left on the top of the Filter requirements dialog). Paste this into a text buffer in your favorite editor. It should look similar to the text below.

[Filter][Keep_Hierarchical]{
TableName:REQ,
ColumnName:RQ_FATHER_NAME,
LogicalFilter:\0000001e\^Requirements\SubChannel\Basement^,
VisualFilter:\0000001e\^Requirements\SubChannel\Basement^,
NO_CASE:
}

The parts that you need to be concerned with are the ColumnName, which in the example is RQ_FATHER_NAME and the LogicalFilter value. For the LogicalFilter you should copy the portion bounded by the up-caret symbols (^). Be sure to include the caret characters when you copy that portion.

In the <CopySelector>, use the RQ_FATHER_NAME as the field name and the portion of the LogicialFilter you copied as the value. Once you have that in the <CopySelector>, enclose the caret delimited logical value in parenthesis. An example below illustrates the end product.

<Config>
    ....
    <QCConnection>
        ....
        <CopySelectors>
            <CopySelector>RQ_FATHER_NAME = (^Requirements\SubChannel\Basement^)</CopySelector>
        </CopySelectors>
        ....

Map QC markup fields

Some fields in QC contain rich-text (basically markup metadata) to achieve bolding, underlining, bulleting, and so on. This rich-text is usually different between QC and Rally. When copying these type of fields from Rally to QC, the <QCRtfFieldHandler> can be used to instruct the connector to translate most of this metadata. This <QCRtfFieldHandle> can be used on mapping fields such as:

  • BG_DESCRIPTION
  • BG_DEV_COMMENTS
  • RQ_REQ_COMMENT
  • TS_DESCRIPTION

An example of mapping BG_DESCRIPTION:

<Config>
    ....
    <Connector>
        <FieldMapping>
            <Field><Rally>Description</Rally><Other>BG_DESCRIPTION</Other></Field>
            ....
        </FieldMapping>
        <OtherFieldHandlers>
            <QCRtfFieldHandler>
                <FieldName>BG_DESCRIPTION</FieldName>
            </QCRtfFieldHandler>
            ....
        </OtherFieldHandlers>
If mapping more than one field for the QCRtfFieldHandler split out the fields as follows:
<Config>
    ....
    <Connector>
        <FieldMapping>
            <Field><Rally>Description</Rally><Other>BG_DESCRIPTION</Other></Field>
            <Field><Rally>Notes</Rally><Other>BG_DEV_COMMENTS</Other></Field>
            ....
        </FieldMapping>
        <OtherFieldHandlers>
            <QCRtfFieldHandler>
                 <FieldName>BG_DEV_COMMENTS</FieldName>
            </QCRtfFieldHandler>

            <QCRtfFieldHandler>
                 <FieldName>BG_DESCRIPTION</FieldName>
           </QCRtfFieldHandler>
            ....
        </OtherFieldHandlers>

Map QC attachments

The QC connector has several options for mapping attachments:

  • Copy the actual QC attachments to Rally

    Copy attachments between Rally and QC with the <RallyAttachmentLinker/> option in the configuration file as follows:

    <Config>
        ....
        <Connector>
            ....
            <RelatedObjectLinkers>
                <RallyAttachmentLinker />
            </RelatedObjectLinkers>
            ....

    Note: Rally attachments are limited to 5 MB. If a QC attachment is larger than 5 MB, it will not be copied from QC to Rally. In such cases, you may use one of the methods below for mapping attachments, which creates a link (URL) in Rally that points to the attachment location in the QC system (no attachment is created in the Rally system, just a URL). The <RallyAttachmentLinker/> supports bi-directional mapping between QC and Rally. The URL mapping is supported in the QC to Rally direction only.

    Known issue: DE23963 - If adding attachments to a child project and the connector user only has editor permissions to Rally, the user must have at least editor permissions to all parent projects of the child project to add an attachment.


  • Map a link to QC10 attachments

    For Quality Center attachments to be accessible when viewing the corresponding artifact (story, defect, test) in Rally, you can create a URL in Rally which points back to the original attachment in the QC system. This mapping is only supported in the QC10 to Rally direction.

    Note: The QC connector supports this capability for the bug, requirement, and test items only.

    In HP QC10, all attachments for each Quality Center domain or project are stored in a fixed location on the disk of the Quality Center server. If the location of this folder is known and shared, its contents can be viewed from an external client. You may need to contact your Quality Center administrator to set up a shared network drive with access to the attachments folder for the specific domain or project.

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

          <Config>
          ....
          <Connector>
          <FieldMapping>
          <Field>
            <Rally>QC10Attachments</Rally>
            <Other>BG_ATTACHMENT</Other>
            <Direction>TO_RALLY</Direction>
          </Field>
          ....
          <OtherFieldHandlers>
          <QCAttachmentFieldHandler>
            <FieldName>BG_ATTACHMENT</FieldName>
            <Path>\\sharedpath</Path>
          </QCAttachmentFieldHandler>
          ....
         

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

     <a href='file:\\sharedpath\file1'>file1</a>

    The field handler will append additional attachments as follows:

     <a href='file:\\sharedpath\file1'>file1</a> <a href='file:\\sharedpath\file2'>file2</a>

    The path to a QC10 project (where the attachments are stored) on the QC server should look similar to: E:\HP\repository\qc\Default\JPPROJECT\attach.


  • Map a link to QC11 attachments or HP ALM12 attachments

    For Quality Center attachments to be accessible when viewing the corresponding artifact (story, defect, test) in Rally, you can create a URL in Rally which points back to the original attachment in the QC system. This mapping is only supported in the QC 11 or HP ALM 12 to Rally direction.

    Note: The QC connector supports this capability for the bug, requirement, and test items only.

    HP QC 11 / ALM 12 stores attachments in a collection of folders on the QC server. It also offers a REST API which permits a straightforward and deterministic way of referencing those attachments as URL links.

    To use this feature, create a custom field in Rally of type Text, which will be used to store the references (URL links) to the attachments (the custom field name in the example below is QC 11 / ALM 12 Attachments). Then use the <QCUrlAttachmentFieldHandler> to handle mapping between QC11 and Rally as follows:

          <Config>
          ....
          <Connector>
          <FieldMapping>
          <Field>
            <Rally>QC11Attachments</Rally>
            <Other>BG_ATTACHMENT</Other>
            <Direction>TO_RALLY</Direction>
          </Field>
          ....
          <OtherFieldHandlers>
          <QCUrlAttachmentFieldHandler>
            <FieldName>BG_ATTACHMENT</FieldName>
          </QCUrlAttachmentFieldHandler>
          ....
         

    The QCUrlAttachmentFieldHandler stores links in the following format:

     <a href='http://qcserver/qcbin/rest/domains/yourdomain/projects/
                    /yourproject/defects/44/attachments/YourAttachedFile.docx'
    >YourAttachedFile.docx</a>

    Caution: As HP ALM only supports client access from Internet Explorer 9, 10, or 11, the link to view the attachments also only works when using IE (9, 10, 11) to access Rally.

Map dates

Quality Center has a set of date fields for artifacts where the format is a string composed of a date, but equivalent fields in Rally may be in a string composed of date and time. There are two field handlers which facilitate this movement of date fields, namely <QCDatetimeToDateFieldHandler> and <RallyDateTimeFieldHandler>.

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

  • BG_CLOSING_DATE
  • BG_DETECTION_DATE
  • RQ_REQ_DATE
  • TS_CREATION_DATE

An example configuration file snippet for date mapping:

<Config>
....
<Connector>
<FieldMapping>
<Field>
  <Rally>CreationDate</Rally>
  <Other>BG_DETECTION_DATE</Other>
  <Direction>TO_OTHER</Direction>
</Field>
....
<OtherFieldHandlers>
<QCDatetimeToDateFieldHandler>
  <FieldName>BG_DETECTION_DATE</FieldName>
</QCDatetimeToDateFieldHandler>
....

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).

When doing bi-directional movements of date fields, use both field handlers as in the following example:

<Config>
....
<Connector>
  <FieldMapping>
    <Field>
      <Rally>Name</Rally>
      <Other>BG_SUMMARY</Other>
    </Field>
    <Field>
      <Rally>TargetDate</Rally>
      <Other>BG_CLOSING_DATE</Other>
    </Field>
  </FieldMapping>
  <OtherFieldHandlers>
    <QCDatetimeToDateFieldHandler>
      <FieldName>BG_CLOSING_DATE</FieldName>
    </QCDatetimeToDateFieldHandler>
  </OtherFieldHandlers>
  <RallyFieldHandlers>
    <RallyDateTimeFieldHandler>
      <FieldName>TargetDate</FieldName>
      <!-- TargetDate(2012-08-25T06:00:00.000Z) -->
      <DateTimeFormat>%Y-%m-%dT%H:%M:%S.%LZ</DateTimeFormat>
    </RallyDateTimeFieldHandler>
  </RallyFieldHandlers>
</Connector>
....

Map TS_NAME

Quality Center has a set of forbidden characters when creating a name for a test. Use 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.

<Config>
....
<Connector>
....
<OtherFieldHandlers>
<QCNameFieldHandler>
  <FieldName>TS_NAME</FieldName>
</QCNameFieldHandler>
....

For TS_NAME, the following eleven characters are removed:

    
Character
Symbol
Backslash
\
Slash
/
Colon
:
Quote
"
Question mark
?
Single quote
'
Less than sign
<
Greater than sign
>
Vertical bar
|
Asterisk
*
Percent
%

Map RQ_REQ_NAME

Quality Center has a set of forbidden characters when creating a name for a requirement. Use 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.

<Config>
  ....
    <Connector>
      ....
      <OtherFieldHandlers>
        <QCNameFieldHandler>
        <FieldName>RQ_REQ_NAME</FieldName>
      </QCNameFieldHandler>
      ....

For RQ_REQ_NAME, the following three characters are removed:

    
Character
Symbol
Backslash
\
Caret/Circumflex
^
Asterisk
*

Map TS_LINKED_REQ and BG_LINKED_REQ

In Quality Center, requirements can be linked to bugs and test cases. In Rally, a similar relationship is possible, but these relationships are not preserved by default. Quality Center tracks linkages in a separate table between requirements and defects. Rally tracks the relationship using the User Story field on defects and the work item field on test cases. So, Quality Center can link a test or defect to more than one requirement while Rally only links a test case or defect to one user story.

You can set up a mapping which will preserve the relationship of a test or defect when moving data from Quality Center to Rally only. Relationships from Rally to Quality Center are not supported.

The <QCReqLinkFieldHandler> is available to help preserve the linkage of a bug or test to a requirement when that requirement has also been synced by the connector. This field handler searches the link table for a bug or test for linked requirements. The first requirement that has a Rally ID will be used to link a defect or test case in Rally.

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

For test to story:

<Config>
  ....
  <Connector>
  <FieldMapping>
  <Field>
    <Rally>WorkProduct</Rally>
    <Other>TS_LINKED_REQ</Other>
    <Direction>TO_RALLY</Direction>
  </Field>
  ....
  <OtherFieldHandlers>
  <QCReqLinkFieldHandler>
    <FieldName>TS_LINKED_REQ</FieldName>
    <ReqRallyIDField>RQ_USER_NN</ReqRallyIDField>
  </QCReqLinkFieldHandler>
  ....
  <RallyFieldHandlers>
  <RallyReferenceFieldHandler>
    <FieldName>WorkProduct</FieldName>
    <ReferencedFieldLookupID>ObjectID</ReferencedFieldLookupID>
  </RallyReferenceFieldHandler>
  ....

Note: For the <ReqRallyIDField> 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 <ExternalIDField> field in the configuration file which was previously used to copy the requirements to user stories.

For defect to story:

<Config>
  ....
  <Connector>
  <FieldMapping>
  <Field>
    <Rally>Requirement</Rally>
    <Other>BG_LINKED_REQ</Other>
    <Direction>TO_RALLY</Direction>
  </Field>
  ....
  <OtherFieldHandlers>
  <QCReqLinkFieldHandler>
    <FieldName>BG_LINKED_REQ</FieldName>
    <ReqRallyIDField>RQ_USER_NN</ReqRallyIDField>
  </QCReqLinkFieldHandler>
  ....
  <RallyFieldHandlers>
  <RallyReferenceFieldHandler>
    <FieldName>Requirement</FieldName>
    <ReferencedFieldLookupID>ObjectID</ReferencedFieldLookupID>
  </RallyReferenceFieldHandler>
  ....

Note: For the <ReqRallyIDField> 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 <ExternalIDField> 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.

Map reference fields from Quality Center

The field handler <QCReferenceFieldHandler> enables the mapping from Quality Center to Rally only. Rally to Quality Center is not supported by this field handler. This field handler supports the following QC fields being mapped to Rally:

  • BG_DETECTED_IN_RCYC
  • BG_DETECTED_IN_REL
  • BG_TARGET_RCYC
  • BG_TARGET_REL
  • RQ_TARGET_RCYC
  • RQ_TARGET_REL
  • RN_ASSIGN_RCYC
  • TC_ASSIGN_RCYC

In the following example, the <QCReferenceFieldHandler> field handler is used to extract the Name from a QC object.

<Config>
  ....
  <Connector>
    <FieldMapping>
      <Field>
        <Rally>Release</Rally>
        <Other>BG_DETECTED_IN_REL</Other>
        <Direction>TO_RALLY</Direction>
      </Field>
      ....
    <OtherFieldHandlers>
        <QCReferenceFieldHandler>
          <FieldName>BG_DETECTED_IN_REL</FieldName>
        </QCReferenceFieldHandler>
      ....

Map Rally Test Result to Test Case (required for runs)

When copying a Quality Center Run to a Rally TestCaseResult, a Rally TestCaseResult must be created with an association to a TestCase. 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 set up correctly. For example:

<Field>
  <Rally>TestCase</Rally>
  <Other>RN_TEST_ID</Other>
</Field>

The connector then uses the RN_TEST_ID value to look-up the linked TestCase in Rally based on this ID. Consequently, the connector needs to know which custom field on the Rally TestCase 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.

<Config> ....
  <Connector>
    <RallyFieldHandlers>
      <RallyReferenceFieldHandler>
        <FieldName>TestCase</FieldName>
        <ReferencedFieldLookupID>ExternalID</ReferencedFieldLookupID>
      </RallyReferenceFieldHandler>
      .... </RallyFieldHandlers>
  </Connector>
  .... </Config>

Map Run Dates (required for runs)

The Date field on a Rally test case result object is a required field (and it is ISO 8601 UTC compliant). However, on a QC Run object the date is represented in two fields: RN_EXECUTION_DATE and RN_EXECUTION_TIME. To support the mapping of a QC run date to a Rally test case result date, use the field handler <QCRunDateFieldHandler> within the <OtherFieldHandlers> section. For example:

<Config>
  <RallyTestResultConnection> ....
    <ArtifactType>TestCaseResult</ArtifactType>
  </RallyTestResultConnection>
  <QCRunConnection> ....
    <ArtifactType>RUN</ArtifactType
                >
    <IDField>RN_RUN_ID</IDField>
    <!-- By default, the connector will only "look back" 1 day for new QC Runs to be
                     copied to Rally TestCaseResults (and associated with a Rally TestCase).
                     Use the following XML tag to change the number of days to search.
                -->
    <RunDaysToSearch>4</RunDaysToSearch>
  </QCRunConnection>
  <Connector>
    <FieldMapping>
      <Field>
        <Rally>Date</Rally>
        <Other>RN_EXECUTION_DATE</Other>
      </Field>
      <Field>
        <Rally>TestCase</Rally>
        <Other>RN_TEST_ID</Other>
      </Field>
      .... </FieldMapping>
    <RallyFieldHandlers> <RallyReferenceFieldHandler>
                               
      <FieldName>TestCase</FieldName>
      <ReferencedFieldLookupID>TCExternalID</ReferencedFieldLookupID>
      </RallyReferenceFieldHandler>
    </RallyFieldHandlers>
    <OtherFieldHandlers>
      <QCRunDateFieldHandler>
        <FieldName>RN_EXECUTION_DATE</FieldName>
      </QCRunDateFieldHandler>
      .... </OtherFieldHandlers>
    .... </Connector>
  <ConnectorRunner> .... </ConnectorRunner>
</Config>

Map 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) to the QC user field that stores the formatted ID to.

<Field>
  <Rally>WorkProduct</Rally>
  <Other>TS_USER_xx</Other>
</Field>

Second, add a <RallyReferenceFieldHandler> to the <RallyFieldHandlers> section that informs the connector to find the story by FormattedID.

<Config> ....
  <RallyFieldHandlers>
  <RallyReferenceFieldHandler>
    <FieldName>WorkProduct</FieldName>
    <ReferencedFieldLookupID>FormattedID</ReferencedFieldLookupID>
  </RallyReferenceFieldHandler>
  .... </Config>

Field handlers

Map drop-down values
Map dates
Map user names
Map reference fields from Rally

Multiple configuration files

There are times when setting up multiple configuration files is necessary, like when you want to map:

  • More than one workspace in Rally
  • Multiple artifact types
  • To or from multiple containers in the other system (such as domains or projects in Quality Center, which would require a unique Rally custom field for the ExternalID of each container being used)

Note: Naming the configuration files using descriptive names makes for easier troubleshooting

To run multiple instances of the connector for different configuration files, invoke it multiple times, using one configuration file each time as follows:

rally2_qc_connector.exe  config_workspaceA.xml  -1
rally2_qc_connector.exe  config_workspaceB.xml  -1

The above commands could be placed in a BAT file for easier invocation.

XML tags

 

XML tags in the <RallyConnection> section:

Tag Name Description Sample Values
     
<RallyConnection>
Required
Opening parent tag for this section.  
<Url>
Required
Server used to connect to Rally (excluding any http prefix and /slm suffix, as the connector will add these to whatever is specified). sandbox.rallydev.com
rally1.rallydev.com
myRally.mydomain.com
192.168.23.24
<WorkspaceName>
Required
Workspace in Rally where you want to copy or update work items. Special characters in this field must be escaped as in: & must be entered as &amp;, > must be entered as &gt;, < must be entered as &lt;, and so on. My Workspace
Dog &amp; Pony WS
<Projects>
Required
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. Special characters in this field must be escaped as in: & must be entered as &amp;, > must be entered as &gt;, < must be entered as &lt;, and so on. <Project>Rally1</Project>
<Project>Rally2</Project>
<Project>P3&amp;4</Project>
<User>
Required
Login name of user to make the Web Services requests to create/update work items in Rally. user@company.com
<Password>
Required
Password associated with the above <User>. Note: The connector will encode this password string and update it in the configuration file as to avoid clear-text passwords being stored. mypassword
<APIKey> RallY APIKey (from Rally Application Manager) for the account to be used to access Rally from the connector. If this is specified, you do not need to supply a username and password. You do not need to whitelist the user associated with the value of the APIKey used as a value. ABC123plmokn43315...
<ArtifactType>
Required
Type of artifact you want to create or update in Rally. (Defect, defect),
(Story, UserStory, HierarchicalRequirement), TestCase, TestCaseResult
<ExternalIDField>
Required
Rally custom string field (name and display name must be identical) that stores the unique ID for the other system. See Create an External ID Field in Rally. QCID
<SuppressDeprecationWarning /> Changes the 'WARN' message about Rally WSAPI version deprecation in the logfile to an 'INFO' message.  
<CopySelectors>
  <CopySelector>
      expression
   </CopySelector>
   [....]
</CopySelectors>
Criteria to use when finding new Rally issues to copy to Quality Center. Multiple criteria are ANDed together. An individual selector specification has the form:
<field><relation><value>,
where:
<field> is the name of a Rally artifact field
<relation> is one of =, !=, gt, lt, gte, lte
<value> is a valid value for the <field>.
See FAQ section for more details.
<CopySelector>
Status = Open
</CopySelector>
<CopySelector>
Priority = Low
</CopySelector>
<UpdateSelectors>
   <UpdateSelector>
      expression
   </UpdateSelector>
   [....]
</UpdateSelectors>
Criteria to use when finding existing Rally issues to be updated in Quality Center. Multiple criteria are ANDed together. An individual selector specification has the form:
<field> <relation> <value>
where:
<field> is the name of a Rally artifact field
<relation> is one of =, !=, gt, lt, gte, lte
<value> is a valid value for the <field>.
See FAQ section for more details.
<UpdateSelector>
Release != alpha
</UpdateSelector>
<FieldDefaults>
   <Field>
      <Name>F1</Name>
      <Default>V1</Default>
   </Field>
   [....]
</FieldDefaults>
Used when the destination system has a required field, but the field is not going to be mapped in the configuration file. This will cause field F1 to be set to value of V1. See more information in FAQ under Map required fields.
</RallyConnection>
Required
Closing parent tag for this section.  

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

& ampersand becomes &amp;
> greater than becomes &gt;
< less than becomes &lt;

Example: Research & Development → Research &amp; Development

 

XML tags in the <QCConnection> section:

Tag Name Description Sample Values
     
<QCConnection>
Required
Opening parent tag for this section.  
<Url>
Required
Quality Center server name (or IP address) and port. Syntax: Normally just the server:port is needed. For https (such as accessing a SaaS QC server), use https://server:443/qcbin QCserverLocal:8080,
https://QCserverSaaS:443/qcbin
<User>
Required
User name used make the API requests to create or update entities in Quality Center. myuser
<Password>
Required
Password of user making the API request to create or update entities in Quality Center. Note: The first time the connector runs, it will encode (which is not the same as encryption) this password and re-write the configuration file to avoid plain text passwords being stored. mypassword
<Domain>
Required
Name of domain that you want to connect to in Quality Center. My Domain
<Project>
Required
Name of project to be used in Quality Center. My Project
<ArtifactType>
Required
Entity name of the entities you want to create or update in Quality Center. BUG,
REQ,
TEST
<RequirementType> Requirement type to set for requirements created in Quality Center. Only applicable when the <ArtifactType> value is REQ. Business, Folder, Functional, Group, Testing, Undefined or your <custom_defined_req_type>
<RequirementFolder> Name of the folder under the QC requirements root folder where requirements are copied (or updated) to. This will have no effect on copying requirements out of QC to Rally. Only applicable when the <ArtifactType> value is REQ. The default is to place copied requirements directly in the requirements root folder. This folder must exist prior to running the connector (also see RequirementFolderID). Release1
Southwest
Regulatory
<RequirementFolderID> The ID of the folder under the QC requirements root folder where requirements are copied (or updated) to. This will have no effect on copying requirements out of QC to Rally. Only applicable when the <ArtifactType> value is REQ. The default is to place copied requirements directly in the Requirements root folder. This folder must exist prior to running the connector. This is useful when there are duplicate folder names in your QC Project (also see RequirementFolder).
123
456
<IDField>
Required
Quality Center field used to store the unique id of a bug, usually BG_BUG_ID BG_BUG_ID
<ExternalIDField>
Required
A custom user field in Quality Center of type String used to store the unique id (ObjectID) for the Rally work item. See Create an External ID User Field in Quality Center. BG_USER_01
<ExternalEndUserIDField> A custom user field in Quality Center of type String used to store the FormattedID of the Rally work item (DExx). See Create an External ID User Field in Quality Center. BG_USER_02
<CrosslinkUrlField> QC custom field (String field types) containing html text information to the corresponding artifact in Rally. RallyURL
<CopySelectors>
   <CopySelector>
      expression
   </CopySelector>
   [....]
</CopySelectors>
Criteria to use when finding new Quality Center issues to copy to Rally. Multiple criteria are ANDed together. An individual selector specification has the form:
<field><relation><value>,
where:
<field> is the name of a Quality Center item field
<relation> is one of =, !=, gt, lt, gte, lte
<value> is a valid value for the <field>.
<CopySelector>
BG_STATUS = Open
</CopySelector>
<CopySelector>
BG_PRIORITY = High
</CopySelector>
For more information about the CopySelectors allowed in QC, see CopySelector and UpdateSelector.
<UpdateSelectors>
   <UpdateSelector>
      expression
   </UpdateSelector>
   [....]
</UpdateSelectors>
Criteria to use when finding existing Quality Center issues to be updated in Rally. Multiple criteria are ANDed together. An individual selector specification has the form:
<field> <relation> <value>
where:
<field> is the name of a Quality Center item field
<relation> is one of =, !=, gt, lt, gte, lte
<value> is a valid value for the <field>.
<UpdateSelector>
BG_TARGET_REL != alpha
</UpdateSelector>
For more information about the UpdateSelectors allowed in QC, see CopySelector and UpdateSelector.
<FieldDefaults>
   <Field>
      <Name>F1</Name>
      <Default>V1</Default>
   </Field>
   [....]
</FieldDefaults>
Used when the destination system has a required field, but the field is not going to be mapped in the configuration file. This will cause field F1 to be set to value of V1. See more information in FAQ under Map required fields.
</QCConnection>
Required
Closing parent tag for this section.  

 

XML tags in the <Connector> section:


Tag Name Description Sample Values
     
<Connector>
Required
Opening parent tag for this section.  
<FieldMapping>
Required
Specifies which fields are to be mapped between the two systems. See Field Mapping.
<OtherFieldHandlers> (opening tag)  
   <OtherUserFieldHandler>
      <FieldName>name-of-field</FieldName>
      <Domain>CompanyName.com</Domain>
   </OtherUserFieldHandler>
For mapping usernames between systems. The <FieldName> is the name of the field in QC. See Map user names section of the FAQ. Bug_Owner
   <OtherEnumFieldHandler>
      ....
   </OtherEnumFieldHandler>
Allows for the mapping of non-alike, drop-down values between the two systems. See Map Drop-Down Values.
   <OtherConditionalEnumFieldHandler>
      ....
   </OtherConditionalEnumFieldHandler>
Very similar to the <OtherEnumFieldHandler> except with this one only the exceptions need to be declared. Corresponding entries in the pull-down lists of both system which are identical, need not be declared.
   <OtherConcatFieldHandler>
      <FieldName>
         Dest-field
      </FieldName>
      <ConcatFields>
         <Field>Src-field1</Field>
         <Field>Src-field2</Field>
         <Field>.....</Field>
      </ConcatFields>
   </OtherConcatFieldHandler>
Using the contents of Dest-field as the initial string, appends each additional Src-fieldN to Dest-field, using HTML break tags (<br />) to separate each additional field value.

BG_DEV_COMMENTS


BG_DESCRIPTION
BG_USER_02
.....
   <QCAttachmentFieldHandler>
      <FieldName>name-of-field</FieldName>
      <Path>\\sharedpath</Path>
   </QCAttachmentFieldHandler>
Stores a link in the Rally artifact to the QC10 attachment. See Map QC attachments. BG_ATTACHMENT
   <QCUrlAttachmentFieldHandler>
      <FieldName>name-of-field</FieldName>
   </QCUrlAttachmentFieldHandler>
Stores a link in the Rally artifact to the QC11 attachment. See Map QC attachments. BG_ATTACHMENT
RQ_ATTACHMENT
   <QCRtfFieldHandler>
      <FieldName>name-of-field</FieldName>
   </QCRtfFieldHandler>
Converts some of the rich text metadata in the Rally field to a more suitable QC version. See Map QC markup fields. BG_DESCRIPTION
BG_DEV_COMMENTS
RQ_REQ_COMMENT
TS_DESCRIPTION
   <QCUserEmailFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
   </QCUserEmailFieldHandler>
Paired with <RallyUserEmailFieldHandler>.
Given a QC username, it returns the email address for that QC user, which is to be handed to the <RallyUserEmailFieldHandler> (and viceversa).
Valid values for name-of-field:
Any field of type Owner (such as BG_RESPONSIBLE, RQ_REQ_AUTHOR, TS_RESPONSIBLE, RN_TESTER_NAME).
   <QCRunDateFieldHandler>
      <FieldName>name-of-field</FieldName>
   </QCRunDateFieldHandler>
  RN_EXECUTION_DATE
</OtherFieldHandlers> (closing tag)  
<RallyFieldHandlers> (opening tag)  
   <RallyReferenceAttributLookupFieldHandler>
      <FieldName>
         name-of-object
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-object
      </ReferencedFieldLookupID>
   </RallyReferenceAttributeLookupFieldHandler>
Used to map a field from an object.

Project,Release,Iteration


ObjectID,FormattedID
   <RallyUserFieldHandler>
      <FieldName>
         name-of-object
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-field
      </ReferencedFieldLookupID>
   </RallyUserFieldHandler>
Used to map usernames. See Map user names.

User,Owner,Tester


Name,FormattedID
   <RallyUserEmailFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
   </RallyUserEmailFieldHandler>
Paired with <QCUserEmailFieldHandler>.
Given a Rally user's email address, it returns the Rally user (and vice versa).
Valid values for name-of-field:
User, Owner, SubmittedBy, Tester
   <RallyDateTimeFieldHandler>
      <FieldName>F1</FieldName>
      <DateTimeFormat>S1</...>
   </RallyDateTimeFieldHandler>
Bi-directional.
Rally to Other: Convert the Rally ISO date in field F1 into a date string formatted as specified by the string S1 (as per Ruby's DateTime.strftime function) and store this new date string into the field F1 is mapped to.
Other to Rally: The date string contained in the field which F1 is mapped to, is converted into a Rally ISO date (in accordance with Ruby's DateTime.parse) and stored in Rally's F1 field. Note that string S1 is not used in this case.

TestDate
%m-%d-%Y%H:%M:%S
   <RallyEnumFieldHandler>
      ....
   </RallyEnumFieldHandler>
Allows for the mapping of non-alike, drop-down values between the two systems. See Map Drop-Down Values.
   <RallyConcatFieldHandler>
      <FieldName>
         Dest-field
      </FieldName>
      <ConcatFields>
         <Field>Src-field1</Field>
         <Field>Src-field2</Field>
         <Field>.....</Field>
      </ConcatFields>
   </RallyConcatFieldHandler>
Using the contents of Dest-field as the initial string, appends each additional Src-fieldN to Dest-field, using HTML break tags (<br />) to separate each additional field value.

Some custom field


Description
some other field
.....
   <RallyCSVUserMappingFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <FileName>
         name-of-file
      </FileName>
   </RallyCSVUserMappingFieldHandler>
Specifies the name of a field being mapped (name-of-field) and a CSV file where user mappings are stored (name-of-file). The CSV file is used to lookup and transform usernames based on the mappings specified within. This is case sensitive. See a more detailed explanation on the FAQ page or an example XML file.

SubmittedBy


MyUserMappings.csv
</RallyFieldHandlers> (closing tag)  
<RelatedObjectLinkers> (opening tag)  
   <RallyAttachmentLinker /> Used to copy attachments between QC and Rally (bi-directional). Can be used on any object which supports attachments (in Rally: tasks, defects, stories, and tests; in QC: requirements, defects, and tests). For more information, see Map QC attachments.
   <QCReqtoRallyTestWorkProductLinker>
      <RallyStoryFieldForQCReq>
         name-of-field
      </RallyStoryFieldForQCReq>
   </QCReqtoRallyTestWorkProductLinker>
The name-of-field is the Rally custom field in the Req/Story config file. QCReqID
</RelatedObjectLinkers> (closing tag)  
</Connector>
Required
Closing parent tag for this section.  

 

XML tags in the <ConnectorRunner> section:

Tag Name Description Sample Values
     
<ConnectorRunner>
Required
Opening parent tag for this section.  
<Preview> Allows you to enable a preview mode for testing where NO objects are copied or updated in either system. False (default)
True
<LogLevel> Specifies the type of messages to be written to the log file. The highest level is Debug where all messages are displayed. Fatal
Error
Warn
Info (default)
Debug
<Services>
Required

Use the copy services to initially reflect items between systems, then use the update services to keep those reflected items up to date.

The alternative update service searches Rally first for updates and pushes only the recently changed fields to the other system. It then searches the other system for updates and pushes all mapped fields into Rally. This reduces the occurrences of overwrites when changes have been made in both systems.

Copy services:

COPY_QC_TO_RALLY
COPY_RALLY_TO_QC

Update services:

UPDATE_QC_TO_RALLY
UPDATE_RALLY_TO_QC

Alternative update service:

UPDATE_RALLYFIELDS_AND_OTHER (may not be used in conjunction with the other update services)

See FAQ for more information.

<PostServiceActions>
   <MirrorStoryHierarchyInQC  />
</PostServiceActions>

Instructs the connector to move the Rally user story hierarchy to a QC requirements hierarchy (one direction only). Should not be used in the same configuration file as <MirrorQCStoryHierarchyInRally>.
<PostServiceActions>
   <MirrorQCStoryHierarchyInRally>
      <RootFolderID>number</RootFolderID>    </MirrorQCStoryHierarchyInRally>
</PostServiceActions>

Instructs the connector to move the QC requirement hierarchy to a Rally user story hierarchy (one direction only). Should not be used in the same configuration file as <MirrorStoryHierarchyInQC>. This feature will only work with: 1) the Requirement artifact in QC, 2) the UserStory artifact in Rally, 3) a parent which has no tasks.
By default, the QC requirements copied to Rally have the full QC folder pathname (starting at Requirement). To have the Rally folder named with a subset of the full pathname, you may give the starting point (folder name) by specifying the top level folder ID within the <RootFolderID> element.
<Emailer>
   <Level>value</Level>
   <SendEmailFrom>value</SendEmailFrom>
   <SendEmailTo>value</SendEmailTo>
   <SMTPServer>value</SMTPServer>
   <SMTPPort>value</SMTPPort>
   <SMTPUser>value</SMTPUser>
   <SMTPPassword>value</SMTPPassword>
   <SMTPSec>value</SMTPSec>
</Emailer>
Opening tag for this feature.
Which logfile messages to email.







Closing tag for this feature.
See example.
Error or Warning
monitor@acme.com
monitor@acme.com
smtp.acme.com
587
Username@Domain.com
Password
TLS
 
</ConnectorRunner>
Required
Closing parent tag for this section.  

 

The <RallyTestResultConnection> XML tags:

These are the same as the <RallyConnection> section except the parent tag is <RallyTestResultConnection>.

 

The <QCConnection> XML tags:

Tag Name Description Sample Values
     
<QCConnection>
Required
Opening parent tag for this section.  
<Url>
Required
Quality Center server name (or IP address) and port. Syntax is server:port. myqcserver:8080
<User>
Required
The user to make the API requests to create and update entities in Quality Center. myuser
<Password>
Required
Password for user to make the API request to create and 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
<Domain>
Required
Domain that you want to connect to in Quality Center. MyCompany.com
<DatabaseSet>
Required
Project that you want to connect to in Quality Center. My Project
<ArtifactType>
Required
Entity name for the entities you want to create and update in Quality Center. TEST
<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
<IDField>
Required
Quality Center field used to store the unique ID of a test or other entity. TS_TEST_ID
<ExternalIDField>
Required
Quality Center user field of type String that stores the unique ID for the Rally work item. See Create an External ID User Field in Quality Center . TS_USER_01
</QCConnection>
Required
Closing parent tag for this section.  

 

The <QCRunConnection> XML tags:

This tag is used when dealing with Tests in QC. It supports all of the tags in the <QCConnection> section, as well as the following tags:

Tag Name Description Sample Values
     
<QCRunConnection>
Required
Opening parent tag for this section.  
<Url>
Required
Quality Center server name (or IP address) and port. server.port
<Domain>
Required
Name of the domain you want to connect to in Quality Center. My Domain
<Project>
Required
Name of project to be used in Quality Centter. My Project
<qcusername>
Required
Quality Center username. username@qc.com
<password>
Required
Password associated with the username above. mypassword
<ArtifactType>
Required
Type of artifact you want to create or update in QC. BUG, REQ, TEST
<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
<IDField>
Required
Quality Center field used to store the unique ID of a test run. RN_RUN_ID
<ExternalIDField>
Required
Quality Center user field of type String that stores the unique ID of a test or other entity. TS_User_01
<RunDaysToSearch> Specified in days, the time period in which the connector searches into the past for new QC runs to be copied to Rally test case results (and associated with a Rally test case). The default is one (1) day. 1 (default)
2
</QCRunConnection>
Required
Closing parent tag for this section.  

 

The <Connector> XML tags:

Tag Name Description Sample Values
     
<Connector>
Required
Opening parent tag for this section.  
<FieldMapping>
Required
Specifies which fields are to be mapped between the two systems. See Field Mapping.
<OtherFieldHandlers> Opening tag.  
   <OtherEnumFieldHandler>
      ....
   </OtherEnumFieldHandler>
Allows for the mapping of non-alike drop-down values between the two systems. See Map Drop-Down Values.
   <QCTestplanFolderFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
   </QCTestplanFolderFieldHandler>


TS_SUBJECT
</OtherFieldHandlers> Closing tag.  
<RelatedObjectLinkers>
Used for more complex mappings of fields.  
   <RallyToQCTestStepLinker> Used to COPY (Note: UPDATE is not supported) Rally test cases and steps—to—QC Tests and TestSteps.  
      <ValidationStep>
         positional-name
      </ValidationStep>
Tells the connector where to place Rally's Validation Input or Validation Expected Result in the list of QC TestSteps.
Last
First
      <StepFields>
         <Field>
            <Rally>
               name-of-field
            </Rally>
            <Other>
               name-of-field
            </Other>
         <Field>
         ....
      </StepFields>
See example QC-config-test-steps-01.pxml


ExpectedResult


DS_EXPECTED
    </RallyToQCTestStepLinker> Closing tag. See example configurations file QC-config-test-steps-01.pxml
    <QCToRallyTestStepLinker />
Used to COPY (Note: UPDATE is not supported) QC Tests and TestSteps --to-- Rally test cases and Steps. See example configurations file QC-config-test-steps-02.pxml
</RelatedObjectLinkers>
Closing tag.  
<RallyFieldHandlers> Opening tag.  
   <RallyReferenceAttributeLookupFieldHandler>
      <FieldName>
         ObjectName
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-object
      </ReferencedFieldLookupID>
   </RallyReferenceAttributeLookupFieldHandler>
Used to map a field from an object.

Project,Release,Iteration

ObjectID, FormattedID
   <RallyUserFieldHandler>
      <FieldName>
         ObjectName
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-field
      </ReferencedFieldLookupID>
   </RallyUserFieldHandler>
Used to map usernames. See Map User Names.

User, Owner, Tester, ...


Name, FormattedID, ...
   <RallyUserEmailFieldHandler>
      <FieldName>ObjectName</FieldName>
   </RallyUserEmailFieldHandler>
Uses the email address of the object ObjectName. User, Owner, Tester, ...
   <RallyDateTimeFieldHandler>
      <FieldName>F1</FieldName>
      <DateTimeFormat>S1</...>
   </RallyDateTimeFieldHandler>
Bi-directional.
Rally to Other: Convert the Rally ISO date in field F1 into a date string formatted as specified by the string S1 (as per Ruby's DateTime.strftime function) and store this new date string into the field F1 is mapped to.
Other to Rally: The date string contained in the field which F1 is mapped to, is converted into a Rally ISO date (in accordance with (via Ruby's DateTime.parse) and stored in Rally's F1 field. Note that string S1 is not used in this case.

TestDate
%m-%d-%Y%H:%M:%S
   <RallyEnumFieldHandler>
      ....
   </RallyEnumFieldHandler>
Allows for the mapping of non-alike drop-down values between the two systems. See Mapping Drop-Down Values.
    <RallyTestFolderFieldHandler>
        <FieldName>
           name-of-folder
        </FieldName>
    </RallyTestFolderFieldHandler>
See example at QC-config-CopyTests2test cases.pxml.

TestFolder
</RallyFieldHandlers> Closing tag.  
</Connector>
Required
Closing parent tag for this section.  

 

The <ConnectorRunner> XML tags:

Tag Name Description Sample Values
     
<ConnectorRunner> Opening parent tag for this section.  
<Preview> Allows you to enable a preview mode for testing where NO objects are copied or updated in either system. False (default)
True
<LogLevel> Specifies the type of messages to be written to the log file. The highest level is Debug where all messages are displayed. Fatal
Error
Warn
Info (default)
Debug
<Services>
Required

Use the copy services to initially reflect items between systems, then use the update services to keep those reflected items up to date.

The alternative update service searches Rally first for updates and pushes only the recently changed fields to the other system. It then searches the other system for updates and pushes all mapped fields into Rally.

Copy services:

COPY_QC_TO_RALLY
COPY_RALLY_TO_QC

Update services:

UPDATE_QC_TO_RALLY
UPDATE_RALLY_TO_QC

Alternative update service:

UPDATE_RALLYFIELDS_AND_OTHER (may not be used in conjunction with the other update services)

See FAQ for more information.

</ConnectorRunner> Closing parent tag for this section.  

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 set up correctly, then start customizing the field mapping and field handler sections.

Run the connector

WorkItem mode

Once the qc_config.xml file has been edited to reflect your environment, you can start running the connector. On Windows, open a command shell and type:

rally2_qc_connector.exe  qc_config.xml  -1

to start the service. If you named your configuration file something other than qc_config.xml, substitute that name on the command line. The last argument, -1, tells the connector to run once, then exit.

Note: In the past we have sometimes suggested using a positive integer value as they last argument, such as 10, which would instruct the connector run; sleep 10 minutes; then repeat this process. We now advise against such use it appears to generate issues in some environments (and they are difficult to triage). We strongly suggest using -1 as the last argument, and then set up a Windows Scheduled Task if you want the connector to run at regular intervals.

The file rallylog.log is generated by the connector and contains login information. View it by drag-and-drop onto WinTail.exe (part of the installation). Viewing the log file is how to tell if the connector is working properly, or to discover any errors.

Tip: Rally ships a startqc.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. If the configuration file you intend to use is not named qc_config.xml you must edit the startqc.bat file to reference your configuration file name.

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

Test mode

Once the qc_config*.xml files are set up, you can start running the connector.

  1. To start the connector on Windows, open a command shell and enter:
  2. rally2_qc_connector.exe  qc_config_test.xml  -1
    rally2_qc_connector.exe  qc_config_run.xml  -1
  3. Double-click on WinTail.exe to run WinTail.
  4. 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.

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

Credential Encryption (added May 2015)

As of version 4.6.0 of the Connector, credentials occurring in the *Connection sections of the configuration file that are in clear-text are encrypted after the initial run using that config file. Credentials are identified as any configuration item tag appearing in a *Connection section whose name is '*User', or any '*Password' or 'APIKey'.

Credentials in the Emailer section (SMTPUser and SMTPPassword) will still be encoded. The credential encryption is localized for the installation of the connector and various aspects of the configuration file.

In practice, as long as the installation and execution folders are constant and the key Rally parameters in the configuration do not change, you are free to modify most of the contents of the configuration file without having to reset the credentials to their clear-text values. However, care must be taken in environments that do not have such stable characteristics to frequently check the log files for any entries that indicate environmental changes have taken place that prevent the connector from decrypting the encrypted values for use in the connector execution.

Modify the logging parameters

The connector logs messages as it is processing into a rallylog.log file in the current working directory. By default, the maximum size of a log file is 5 MB and the log rotation is limited to 10 files. You can adjust the maximum size of the log file and adjust the maximum count of log files in the log rotation by specifying command line arguments for this.

The -s <integer> option pair can be used to specify the maximum size of the log file in MB increments (up to 100 MB). This can also be expressed as --max-log-file-size <integer>.

The -m <integer> option pair can be used to specify the maximum count of files in the log file rotation scheme. This can also be expressed as --max-log-files-count <integer>.

Example: To set the log file max size to 50 MB and the maximum log file rotation count to 20 files for a single invocation of the connector:

rally2_xxx_connector -s 50 -m 20 xxx_config.xml -1

OR

rally2_xxx_connector --max-log-file-size 50 --max-log-files-count 20 xxx_config.xml -1

Multiple configuration files

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) in the other system, setting up multiple configuration files may make sense.

To run multiple configuration files, invoke the connector once for each file. For example:

rally2_qc_connector.exe  config_workspaceA.xml  -1
rally2_qc_connector.exe  config_workspaceB.xml  -1

Troubleshoot the connector

The rallylog.log file

Once the connector is running, all errors are written to the rallylog.log in the working directory where rally2_qc_connector.exe was invoked. Informational messages, warnings, and errors are written to the log file depending on the value of the <LogLevel> tag in the <ConnectorRunner> section of the configuration file.

To see the most recent log messages on Windows, we recommend using the provided WinTail utility. To do this, rename the file from WinTail.dat to WinTail.exe and then drag the rallylog.log file and drop it on the WinTail.exe icon. The log file displays with automatic updates.

Connector validation

Before the connector starts synchronizing objects between the two systems, it performs these validations:

  • Connecting to Rally is successful
  • Connecting to the QC system is successful
  • The Rally fields in the field mapping section exist in Rally
  • The QC fields in the field mapping section exist in the other system
  • Each specified 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, set the <Preview> tag in the configuration file to true. This is useful if you wish to experiment with some different configuration options to debug an issue.

Datetime field handlers

When mapping date fields, a field handler is required to instruct the connector how the field is to be transformed. A proper setup could be as follows:

        .....
          <Field><Rally>TargetDate</Rally>   <Other>BG_CLOSING_DATE</Other></Field>
        .....
        <QCDatetimeToDateFieldHandler>
                <FieldName>BG_CLOSING_DATE</FieldName>
        </QCDatetimeToDateFieldHandler>
If the fieldhandler above is not provided, you might see a error such as this:
 DEBUG : Connector.block in map_fields_to_rally - Mapping
                BG_CLOSING_DATE(2013-03-05 00:00:00 +0000)
                        - to -
                TargetDate(2013-03-05 00:00:00 +0000)
  WARN : RallyConnection.initialize - <Errors><OperationResultError>
                        Could not parse: Cannot convert "null" into a date.
                        You must use the ISO8601 date+time format.

EnvironmentalKey ident_vector not valid error

The following error may be seen in QC connector version 4.6.0 and higher. If this error is seen, please re-enter the userid/password for both QC and Rally.

        .....
          ERROR : Class.initialize - EnvironmentalKey ident_vector not valid for decryption target value

A simple BAT file

This startqc-simple.bat file is provided as an example of how the connector could be invoked. Note that the recommendation is to run it once per configuration file.

@echo off
echo.------------------------------------------------   >> .\rallylog.log
echo.Windows Task invoked on %date%, %time% (local time)>> .\rallylog.log
echo.------------------------------------------------   >> .\rallylog.log

set My_Configuration_Dir="C:\Users\jpkole\MyQCfiles"
set My_Connector_Dir="C:\Program Files (x86)\RallyConnectorforQualityCenter"

:: If your site uses a proxy, uncomment next line and set it appropriately
:: set HTTP_PROXY=http://username:password@myproxy.company.com:8000

cd %My_Configuration_Dir%

%My_Connector_Dir%\rally2_qc_connector.exe   qc-config-01.xml   -1
%My_Connector_Dir%\rally2_qc_connector.exe   qc-config-02.xml   -1
%My_Connector_Dir%\rally2_qc_connector.exe   qc-config-03.xml   -1

A complex BAT file

This startqc-complex.bat file is provided to help capture more data for complex issues.

:: ===============================================================
:: SCRIPT:
::      startqc-complex.bat
::
:: PURPOSE:
::      Used to invoke the QC connector.
::
:: USAGE:
::      Edit the variables below to fit your environment and invoke
::      this BAT script in a MS-DOS command window or as a Windows
::      Scheduled Task.
::
::      As this BAT file runs, it will output status messages to the
::      command window as well as to the logfile "Connector.log".
::
:: VARIABLES:
::      My_Delay_In_Minutes - The amount of time, in minutes, to
::              delay before processing all the config files again.
::
::      My_Configuration_Dir - The working directory where the
::              connector will be run. This is typically where
::              your config files are stored and it will also be
::              where the logfiles are created.
::
::      My_Connector_Dir - The directory (folder) where the connector
::              was installed. By default this is:
::              "C:\Program Files (x86)\RallyConnectorforQualityCenter"
::              however, it may have been overridden when the
::              connector was installed.
::
::      My_Connector_Exe - The actual Windows executable that is the
::              QC connector.
::
::      My_Config_Files - A list of all the config files that are to be
::              processed by the connector.
::     
:: LOGFILES:
::      rallylog.log - this is the normal log file used by the
::              connector. As always, it will appear in the working
::              directory where the connector is invoked. In the
::              example below, it is specified as the environment
::              variable "My_Configuration_Dir".
::
::      Connector.log - this file will also appear in your working
::              directory and it will contain progress messages
::              written by this BAT file. In the event of a fatal
::              error, it may also contain stack trace information.
:: ===============================================================
@echo off
echo.------------------------------------------------   >> .\rallylog.log
echo.Windows Task invoked on %date%, %time% (local time)>> .\rallylog.log
echo.------------------------------------------------   >> .\rallylog.log

set My_Delay_In_Minutes=10
set My_Configuration_Dir="C:\Users\jpkole\MyQCconfigs"
set My_Connector_Dir="C:\Program Files (x86)\RallyConnectorforQualityCenter"
set My_Connector_Exe=%My_Connector_Dir%\rally2_qc_connector.exe
set My_Config_Files=qc-config-01.xml,qc-config-02.xml,qc-config-03.xml

Setlocal EnableDelayedExpansion

:: If your site uses a proxy, uncomment next line and set it appropriately
:: set HTTP_PROXY=http://user:password@server.company.com:8000

cd %My_Configuration_Dir%

echo Starting "startqc-complex.bat" at: %DATE%, %TIME%
echo Starting "startqc-complex.bat" at: %DATE%, %TIME%      >> Connector.log 2>&1
set /a My_Delay_In_Seconds=%My_Delay_In_Minutes%*60

:LABEL_top_of_loop
        for %%f in (%My_Config_Files%) do (
                echo Processing "%%f" at: %DATE%, !TIME!
                echo Processing "%%f" at: %DATE%, !TIME!    >> Connector.log 2>&1
                %My_Connector_Exe%  %%f  -1                 >> Connector.log 2>&1
        )

        echo Sleeping for %My_Delay_In_Minutes% minutes...  >> Connector.log 2>&1
        timeout /t %My_Delay_In_Seconds% /NoBreak
        GOTO :LABEL_top_of_loop

::the end::

Best practices

Map Rally Projects

If you copy defects from Quality Center to Rally and are mapping a QC field to the Rally Project field, you may see a message like Could not find Rally Project with name ... in the log file if the connector user does not have editor permissions to that project in Rally.

RallyReferenceFieldHandlers are for the most part deprecated. Prior to the 4.4.2 release, if multiple projects were specified in the config file Release or Iteration value was sometimes mapped incorrectly. By relocating some logic, that issue has been addressed as well as being able to handle the most common Rally Reference fields (Project, Release, Iteration) automatically without needing explicit notation in the configuration file. If the configuration file specifies a RallyReferenceFieldHandler for one of those aforementioned fields, the connector will emit a deprecation warning message into the log file and will not register the field handler as that logic is now handled automatically. The are some edge cases where the use of RallyReferenceFieldHandler may be necessary, for fields such as Parent, Child, WorkProject, Owner and other similar fields.

Pessimistic locking in Quality Center

When an entity is selected in QC (using your browser), QC assumes you are editing the record and therefore locks the entity. The UPDATE_RALLY_TO_QC service will not update a Rally artifact to an entity in QC, if you have locked the record (an error in the log file will indicate when this happens).

Map more than one Quality Center project to a single Rally workspace

If you are mapping more than one Quality Center project to a single Rally workspace, there are important considerations to scale this successfully.

  • The IDs of QC artifacts are not unique across the multiple QC projects, which may result in more than one Rally artifact having the same value for the External ID field that corresponds to QC IDs.
  • If you are updating from Rally to QC, note that updates are by default Rally workspace-scoped, and not Rally project-scoped. In the scenario when more than one QC project is mapped to the same Rally workspace, it is recommended that you have Rally projects within this workspace directly correspond to respective QC projects. Individual config files must be created per each Rally project/QC project pair.
  • Each config file has to narrow the scope of Rally to QC updates to the Rally project that is currently referenced under RallyConnection's project tag.

Copy or split Rally stories that are mapped to QC requirements

If you copy or split Rally stories that already have corresponding requirements in QC, make sure to delete the value of the ExternalID field. Otherwise, the copy of the original story will still contain the original story's ExternalID field. This is undesirable since it creates many-to-one mapping between Rally and QC artifacts, which will affect the integrity of your data.

Known issues

Map releases or iterations with multiple projects

When mapping Release or Iteration values and there are multiple Rally Projects where the Release/Iteration names are identical across Rally Projects, you may receive an error if the Release or Iteration you are updating on the defect references a different project than the given defect is assigned. The connector only returns the first Release or Iteration with the matching name in Rally so it could have a reference to a Release or Iteration in a different project.

Map a null release or iteration

When using a <OtherEnumFieldHandler> to map a release or iteration, it is not possible to set it to null or Unscheduled (DE12979).

Email feature for Error

Prior to revision 2.8.8, the <Emailer> feature would not send email if the <Level> was set to Error (DE15642).

QC server upgraded

We have seen the connector hang when attempting to connect to the QC server which was upgraded, but the QC client PC was not update with the proper QC DLL's. The logfile merely shows:

....
   ANY : ConnectorRunner.block in run - processing to commence using content from Simple-Test-01.xml
   ANY : Class.read_config_file - Simple-Test-01.xml last modified 2013-08-15 19:12:59 UTC, size: 1336 chars
   ANY : RallyConnection.initialize - Initializing Rally connection version 2.8.8
  INFO : RallyConnection.initialize - Rally Web Services version 1.16
   ANY : QCConnection.initialize - Initializing Quality Center connection version 2.8.8
  INFO : Connector.initialize - Ruby platform i386-mingw32
  INFO : Connector.initialize - Ruby version 1.9.2
  INFO : QCConnection.connect - Connecting to Quality Center at http://vmwin2008qc11.f4tech.com:8080/qcbin as user jpqc11
 DEBUG : QCConnection.block in identify_qc_version - Preparing to open Registry to examine: Software\Classes\CLSID\{C5CBD7B2-490C-45f5-8C40-B8C3D108E6D7}\InprocServer32
 DEBUG : QCConnection.block in identify_qc_version - Registry Software\Classes\CLSID\{C5CBD7B2-490C-45f5-8C40-B8C3D108E6D7}\InprocServer32 opened...
 DEBUG : QCConnection.block (2 levels) in identify_qc_version - Registry path to HPQC OTAClient.dll ==> C:\PROGRA~2\HP\QUALIT~1\OTACLI~1.DLL
 DEBUG : QCConnection.win_path_expanded - expanded Registry path to DLL target: C:/Program Files (x86)/HP/Quality Center Client Side/OTAClient.dll
At that point, the connector could not be interrupted with Control-C, and a Ruby process was consuming 100% of a CPU.

Duplicate requirement names in QC

In Rally, two requirements can have the same value in the name field. This is not allowed in the QC system. If a requirement with a duplicate RQ_REQ_NAME is copied to QC, an error will occur. If the configuration file is using the <RequirementFolder> or <RequirementFolderID> tag, the following error occurs (otherwise the error will be an OLE 80040556):

  INFO : Connector.copy_to_other - Copy US447 to Quality Center
 DEBUG : Connector.block in map_fields_to_other -   Mapping Name(test dup req name) - to - RQ_REQ_NAME(test dup req name)
 DEBUG : Connector.block in map_fields_to_other -   Mapping Description(US447 desc) - to - RQ_REQ_COMMENT(US447 desc)
 DEBUG : QCConnection.create_internal - set all artifact fields
 ERROR : QCConnection.rescue in create_internal - failed on attempt to move Requirement item to target folder
 ERROR : QCConnection.rescue in create_internal - failed on attempt to create QC Req item from src item
 ERROR : QCConnection.cleanup_shell_artifact - Attempting to delete the shell req item due to error.
  INFO : QCConnection.delete - Deleted QC req with id 22
 ERROR : QCConnection.cleanup_shell_artifact - The shell req was deleted successfully.
  WARN : QCConnection.initialize - Could not create req - failed on attempt to move Requirement item to target folder -

Connector errors when QC comments or Description over 32768 chars (DE22249)

[2015-01-15 17:39:20 Z]  WARN : RallyEIF::WRK::RallyConnection.initialize -
Error on request - https://rally1.rallydev.com/slm/webservice/1.42/testcase/create.js?/workspace=/workspace/658223893a -
{:errors=>["Validation error: TestCase.Description length is greater than the maximum length of 32768"]}

QC StepDesign copy to Rally TestStep text content over 2048 characters gets truncated

A TestStep in Rally has two text content fields (Input and ExpectedResult). There is a size limit of 2048 characters on the content that can be held in both of those fields. If the QC StepDesign that is being copied to a Rally TestStep has text content that is greater than 2048 chars, the corresponding mapped field in Rally will be limited to the first 2048 characters. A WARNING message will be written to the log to indicate that this truncation upon creation of the Rally TestStep has taken place.

Revision history

  • 4.6.1-master-86 --- 18-July 2015
    • Fixes:
      • Fixed issue where TestStep content over 2048 bytes resulted in an error where the creation of that TestStep failed and the creation of any subsuquent TestSteps for the target TestCase were not attempted. This issue was addressed by truncating any TestStep content over 2048 bytes and informing by writing a WARNING message in the log file.
  • 4.6.0-master-84 --- 28-May-2015
    • Enhancements:
      • Credentials in the RallyConnection, QCConnection, QCRunConnection sections are now encrypted.
    • Known Issues:
      • (none)
  • 4.5.5-master-81 --- 21-April-2015
    • Enhancements:
      • Support for using APIKey in place of Rally Username and password.
      • Better handling of FieldDefaults and values.
      • Better logging of failed attempt to copy/update items from another system to Rally.
  • 4.5.4-master-79 --- 02-April-2015
    • Enhancements:
      • Better logging for create/update operations when error conditions encountered.
      • Better handling of string fields mapped to Rally Name, Description, Notes that contain non-ASCII characters.
  • 4.5.3-master-78 --- 07-March-2015
    • Enhancements:
      • Added a RallyBooleanFieldHandler.
    • Fixes:
      • Fixed issue in YetiEmailer where header item had leading spaces not accepted by some email servers.
  • 4.5.2-master-74 --- 28-Jan-2015
    • Enhancements:
      • Added support for HP ALM 12.
      • Updated to use Rally WSAPI v2.0.
  • 4.4.12-maintenance-47 --- 05-Jan-2015
    • Fixes:
      • Introduced a <RallyReferenceAttributeLookupFieldHandler> configuration element to allow use of a <ReferencedFieldLookupID> other than 'Name' for the Project, Release and Iteration fields. The use of a <RallyReferenceFieldHandler> for the Project, Release and Iteration fields was deprecated and the introduction of this field handler can allow similar functionality when the lookup field is intended to be an attribute other than 'Name'.
  • 4.4.11-maintenance-40 --- 19-Nov-2014
    • Fixes:
      • Corrects a change made to Rally ALM that prevented the connector from copying attachments.
  • 4.4.10-master-72 --- 16-Oct-2014
    • Enhancements:
      • Modified rallyeif-wrk core dependency on rally_api to 1.1.2 (that depends on httpclient 2.4.0) to address SSLv3 security issue.
    • Known Issues:
      • The <ValidationStep> fieldhandler is broken - DE23409 filed
  • 4.4.4-master-67 --- 18-Sep-2014
    • Enhancements:
      • Improved semantic comparison of Rally boolean values to strings ('true' / 'false') should result in fewer unnecessary updates.
      • Improved semantic comparison of Rally decimal values to integers/strings (1.0 should equal 1 or "1") should result in fewer unnecessary updates.
      • Added ability of OtherUserFieldHandler to accommodate HPQC user names in all caps to compare case-insensitively to Rally UserName values.
      • Improved comparison of Rally User to user identifier from HPQC should result in fewer unnecessary updates.
    • Known Issues:
      • The <QCRtfFieldHandler> Fieldhander will only process 1 field per Fieldhandler - DE22728 filed. (see QCRtfFieldHandler section for information on multiple field usage.)
  • 4.4.3-master-66 --- 29-Aug-2014
    • Enhancements:
      • Modifications to make parsing RevisionHistory Revision records more robust, especially the Notes field.
  • 4.4.2 --- 30-Jul-2014
    • Enhancements:
      • Common Rally Reference fields (Project, Release, Iteration) no longer need to have a RallyReferenceFieldHandler configured in the Connector - RallyFieldHandlers section of the config file.
      • Mapping of Rally Reference fields such as Release and Iteration is fully project scoped to ensure that if the DisplayName of multiple Release items is identical, the artifact contains the link to the item associated with the Project setting in the artifact.
  • 4.3.2 --- 05-Feb-2014
    • Fixes:
      • Fixed a bug in QC Test Run Connector in preview mode
  • 4.3.0 --- 16-Jan-2014
    • Enhancements:
      • Upgrade from Ruby 1.9.2-p290 to Ruby 2.0.0-p247.
      • Performance improvement gained by using rally_api rather than rally_rest_api.
      • Added more build tests.
      • QC Connector causes backward time drift when mapping TargetDate to BG_CLOSING_DATE (DE18750).
      • Updated Rally QC Email User Field Handler (DE18583).
      • The <RallyUserFieldHandler> was broken (DE18850).
      • Connector would validate only the first config file on command line (DE17492).
      • Added <SuppressDeprecationWarning> XML tag.
      • Upgrade to version 1.42 of the WSAPI.
      • Note: For the 4.3.0 version of this connector, any custom code (such as a custom field handler) will require modifications. A working example (using the QC connector) can be found here.

        Previous method for doing requires:
        require 'yeti/field_handlers/other_field_handler'
        require 'rexml/document'

        class MyCustomFieldHandler < ....FieldHandler
          ....
        end
        New way of doing requires:
        require 'rallyeif/wrk/field_handlers/field_handler'

        module RallyEIF
          module WRK
            module FieldHandlers

              class MyCustomFieldHandler < ....FieldHandler
                # See example code in installation directory:
                # ./field_handlers/my_custom_field_handler.rb
              end
            end
          end
        end
  • 2.10.0-513 --- 14-Oct-2013
    • Enhancements:
      • Fixed incorrectly listing updated value in log file (DE18019).
      • Updated QC version log message from WARNING to INFO (DE18378 ).
      • Usability and reliability upgrades for HPQC Phase 1 (F3823).
      • Create a field handler to map users with a csv (S53878).
      • QC to Rally defect mapping of non-existant user is handled better (S50159).
      • Logfile incorrectly displayed Release/Iteration Reference and not the actual name (S50389).
      • Connector handles mapping of QC Date/Time in multiple formats to Rally Date/Time fields (S50391).
      • RequirementFolder did not act like CopySelector during Copy from QC to Rally (S50265).
      • Check for existence of CrosslinkUrlField in <QCConnection> section only (S51204).
      • The rally_rest_api interface was replaced with the rally_api to make the code more concise and improve performance (S38419).
      • For TestCase and TestCaseResult: Last Verdict does not change on Iteration Status page when new test case result is created via connector (S50262).
      • Refactored core sync to field level to prevent overwriting (F4214).
      • Added WSAPI 2.0 in EIF Connectors (F3097).
    • Fixes:
      • Management of case sensitive usernames in Rally and other (DE18025).
      • Lookback Time to copy/update Artifacts is invalid (DE17865).
      • EIF connectors now validate config files on command line (DE17492).
      • The has-changed did not correctly compare date fields (DE15628).
    • Known issues:
      • The <RallyUserFieldHandler does not properly return a value (DE18850).
  • 2.8.8-225 --- 14-Dec-2012
    • Enhancements:
      • Minor logging improvements.
    • Fixes:
      • DE15642: Email notification of errors and warnings, in the<Emailer> feature, would not send email if the <Level> was set to Error.
    • Known issues:
      • When mapping a QC Date/Time field to/from a Rally Date/Time field, in some cases the connector will fail with:
            Could not parse: Cannot convert "null" into a date. You must use the ISO8601 date+time format.
        This is usually resolved by using the <RallyDateTimeFieldHandler>.
      • If the SubmittedBy or Owner field is being mapped, and the artifact has a reference to a previously deleted user in one of those two fields, the connector will abort when attempting to get the artifact, with message: "undefined local variable or method `value' for #<RallyUserFieldHandler:0x149be48>"
  • 2.8.6-222 --- 01-Nov-2012
    • Enhancements:
      • Added more logging for <LogLevel>Any</LogLevel>.
      • Moved rally_api to revision 0.7.6.
      • Added Rally URL and user name to connection message.
      • Added ID in log message so user can see what artifact caused an error.
      • Added check for nil return value on tags/keywords.
      • Added more debugging output on connection to Rally.
      • Improved performance by removing refresh on Workspace read in find-workspace loop.
      • Updated to use rally_api 0.6.0 to fix "requirement is not a valid type" error.
    • Fixes:
      • DE14293: Test folders with spaces in the name would fail.
      • DE14312: When running in PREVIEW mode, connector would exit with error message: "unknown property or method: `length'".
      • DE14473: Duplicate attachments were created on update from QC to Rally UserStory when filename had special characters.
      • DE14528: An update from Rally to QC Runs have an extra prefix/append of the html/body tags.
      • DE14592: Two config files on the command would sometimes hang.
      • DE14655: Connector errors with "Object Type requirement is not query-able".
    • Known issues:
      • DE15642: The <Emailer> feature does not send email if the <Level> is set to Error.
      • When the connector finishes running in PREVIEW mode, it prints the error:
        INFO : ConnectorRunner.show_preview_message - ------- Preview Mode -------
        ERROR : ConnectorRunner.rescue in run_services - Unexpected exception occurred
        ERROR : ConnectorRunner.exception - Message unknown property or method: `length'
            HRESULT error code:0x80020006
              Unknown name.
  • 2.8.1-211 --- 25-Jul-2012
    • Log file now shows the name of the REF returned by the transform_in() function of a RallyReferenceFieldHandler on the map_fields_to_rally call.
    • Fixed an issue where a project named TEST would be returned erroneously on a query for project TEST+.
    • Change to throw exception on find by ExternalID if results are nil.
  • 2.7.9-207 --- 01-Jul-2012
    • Improved testing code.
    • Fixed issue where attachments were being duplicated if updates were going in both directions.
    • Fixed several minors issues.
    • Adding debug logging to attachment linker.
  • 2.7.6-184 --- 22-May-2012
    • Added <RallyToQCTestStepLinker>, <ValidationStep> Last </ValidationStep>, and <StepFields>
    • Added <RelatedObjectLinkers>, <QCToRallyTestStepLinker />
    • Added <RallyDateTimeFieldHandler>
    • Added <Emailer> functionality to the <ConnectorRunner> section.
    • Mods for migrating items from the Test Lab to Rally TestCases/TestSets/TestFolders.
  • 2.7.4-170 --- 01-May-2012
    • Added ability for FormattedID in QC system to have lower case prefix (us123) or upper case prefix (US123).
    • Added subfield specifications on CopySelectors from Rally using the precopy feature.
    • Fixed handling of "bad" characters in a Requirement 'Name' field
    • Expanded CopySelector/UpdateSelector criteria expression to include: field = (Foo or Bar)
    • Added facility to specify TestFolder or RequirementFolder ID instead of name (bypasses duplicate folder name issues)
    • Added capability to reflect Story relationships, TestCase relationships, Defect relationships
    • Added XML include capability so common text can be included as a separate file.

OLE error codes


OLE error codes reported by Rally’s QC connector:


Code: 80000482 Cause: Seen when running a QC10 connector on QC11 client Error: Invalid server response
Code: 80020006 Cause: Seen when running the 2.8.6 version of the connector in PREVIEW mode. This error is generated once the connector has finished and is attempting to generate summary messages. Fixed in version 2.8.8 of the connector. Error: INFO : ConnectorRunner.show_preview_message - ------- Preview Mode ------- ERROR : ConnectorRunner.rescue in run_services - Unexpected exception occurred ERROR : ConnectorRunner.exception - Message unknown property or method: `length' HRESULT error code:0x80020006 Unknown name.
Code: 800401F3 Cause: Something about the OTAClient.dll is not right. See notes in the Pre-installation checklist, step 4 (above). Error: INFO : QCConnection.connect - Connecting to Quality Center at http://10.10.10.10:8080/qcbin as user XYZ ERROR : QCConnection.rescue in connect - Could not create OLE Server "TDApiOle80.TDConnection.1" ERROR : QCConnection.initialize - unknown OLE server: `TDApiOle80.TDConnection.1' HRESULT error code:0x800401f3 Invalid class string ERROR : ConnectorRunner.exception - Message unknown OLE server: `TDApiOle80.TDConnection.1'
Code: 800403EA Cause1: Seen when using a <CopySelector> on BG_DETECTED_IN_REL The syntax was (incorrectly) specified like this: <CopySelector>BG_DETECTED_IN_REL = "Orgella")</CopySelector> The proper syntax is: <CopySelector>BG_DETECTED_IN_REL = (^Releases\Orgella^)</CopySelector> Error1: ANY : ConnectorRunner.process_service - Starting Service COPY_QC_TO_RALLY INFO : QCConnection.find_new - find_new query: BG_USER_01 ="" and BG_DETECTED_IN_REL ="Orgella" ERROR : QCConnection.initialize - (in OLE method `NewList': ) OLE error code:800403EA in Failed to Get Bug Value HRESULT error code:0x80020009 Cause2: Seen when the QC server had been updated, but the client OTAClient.dll was not updated (this is similar to error 800401F3 above). Error2: INFO : QCConnection.connect - Connecting to Quality Center at http://xxxx.com:8080/qcbin as user jpkole DEBUG : QCConnection.block in identify_qc_version - Preparing to open Registry to examine: Software\Classes\CLSID\{C5CBD7B2-490C-45f5-8C40-B8C3D108E6D7}\InprocServer32 DEBUG : QCConnection.block in identify_qc_version - Registry Software\Classes\CLSID\{C5CBD7B2-490C-45f5-8C40-B8C3D108E6D7}\InprocServer32 opened... DEBUG : QCConnection.block (2 levels) in identify_qc_version - Registry path to HPQC OTAClient.dll ==> C:\Program Files\Common Files\Mercury Interactive\Quality Center\OTAClient.dll DEBUG : QCConnection.win_path_expanded - expanded Registry path to DLL target: C:/Program Files/Common Files/Mercury Interactive/Quality Center/OTAClient.dll ERROR : QCConnection.rescue in connect - Could not Login to QC OLE Server with user:"jpkole" and pw:*** ERROR : QCConnection.initialize - (in OLE method `Login': ) OLE error code:800403EA in Failed to Login HRESULT error code:0x80020009 Exception occurred.
Code: 800403EC Cause: Reported on invalid Username or Password Error: ERROR : QCRunConnection.rescue in connect - Could not Login to QC OLE Server with user:"jpkole" and pw:*** ERROR : QCRunConnection.initialize - (in OLE method `Login': ) OLE error code:800403EC in <Unknown> Authentication failed. Verify your user name and password HRESULT error code:0x80020009
Code: 800403FF Cause: A custom field was created in QC (type = Lookup List; values were Y or N). The field was mapped to a Boolean in Rally; all was OK. The string “false” was copied from Rally into the QC Y/N field (not a desired action). I went back to the custom field in QC and checked the box “Verify Value”. When the connector ran again, the error was reported was: Error: Field < BG_USER_10_Boolean > requires a value from the corresponding list
Code: 80040518 Cause: (unknown thus far) Error: This field cannot be changed directly by user.
Code: 80040519 Cause1: There was no <QCDatetimeToDateFieldHandler> used with mapping Rally's CreationDate (see Map dates above) Error: DEBUG : Connector.block in map_fields_to_other - Mapping CreationDate(2012-10-24T18:16:40.887Z) - to - BG_DETECTION_DATE(2012-10-24T18:16:40.887Z) .... ERROR : QCConnection.rescue in block in create_internal - Unable to set bug field BG_DETECTION_DATE with value of |2012-10-24T18:16:40.887Z| ERROR : QCConnection.rescue in create_internal - failed on attempt to create QC Bug item from src item ERROR : QCConnection.cleanup_shell_artifact - Attempting to delete the shell bug item due to error. INFO : QCConnection.delete - Deleted QC bug with id -10 ERROR : QCConnection.cleanup_shell_artifact - The shell bug was deleted successfully. WARN : QCConnection.initialize - Could not create bug - (in OLE method `Field': ) OLE error code:80040519 in <Unknown> Invalid date field value. HRESULT error code:0x80020009 Cause2: User defined the ExternalID field in QC as type “Number” instead of “String”. Note: When the opposite is done (ExternalID is defined in Rally as type “Integer” instead of “String”, the error is: Cannot parse number: For input string: "" A simple way to test this is: Create a custom field in Rally named Foo, define it as type “Integer”, go to WSAPI, Defects, issue this query: (Foo = “”); Error returned is: OperationResultWarning Could not parse ""
Code: 8004051B Cause: This QC error code is not well understood here at Rally. We have seen two instances of this error: Error1: Required field <Detected on Date> can not be empty or SPACE filled. Cause?: We suspected a custom field in QC named “Detected on Date” has been marked “Required”, and it was not mapped (and thus empty). Error2: Required field <Build Written For> can not be empty or SPACE filled. Cause?: We suspected several TestCases were being copied from Rally to QC, and they all had the same value for the "Name" field, which is illegal in QC. The custom field <Build Written For> (TS_USER_01) was being mapped. And yes, assuming this was the real issue, this is a very strange error code/message (one would think the reported error would have been 80040556 below).
Code: 8004051C Cause: Created a new Requirement; named it MyNewRequirementsFolder; gave it a type of folder. I had declared custom field RQ_USER_01 (in my configuration file) as the <ExternalIDField>. But in QC under Tools → Customize... → Requirement Types → Folder → the "User Defined Fields" tab, the field RQ_USER_01 was not "checked" under "In Type" column. Error: The field < RQ_USER_01 > cannot be used with requirement type < Folder >.
Code: 8004053D Cause: CopySelector had “Y” (the quotes are not allowed)
Code: 80040556 Cause1: Attempt to copy a User Story from Rally to a QC requirement, but the Name (RQ_REQ_NAME) already existed on a requirement in QC... you can not have duplicate names on requirements in QC. Error: Unable to set req field RQ_USER_04 with value of |Rally| Cause2: The <ExternalEndUserIDField> tag was used in the <QCConnection> section, but the field name specified in it did not exist. Error: INFO : RallyConnection.find_new - Found 1 new userstorys in Rally INFO : Connector.copy_to_other - Copy US453 to Quality Center DEBUG : Connector.block in map_fields_to_other - Mapping Name(Test 97175) - to - RQ_REQ_NAME(Test 97175) DEBUG : Connector.block in map_fields_to_other - Mapping Description(mod1) - to - RQ_REQ_COMMENT(mod1) DEBUG : Connector.block in map_fields_to_other - Mapping Project(PR01) - to - RQ_REQ_PRODUCT() ERROR : QCConnection.rescue in block in create_internal - Unable to set req field RQ_USER_09 with value of |US453| ERROR : QCConnection.rescue in create_internal - failed on attempt to create QC Req item from src item ERROR : QCConnection.cleanup_shell_artifact - Attempting to delete the shell req item due to error. ERROR : QCConnection.rescue in delete - Delete failed for req -10 WARN : QCConnection.initialize - (in OLE method `RemoveItem': ) OLE error code:80040556 in <Unknown> Failed to delete requirement. HRESULT error code:0x80020009 Cause3a: There was a "Required" boxed checked on a field under Tools --> Customize --> Requirement Types --> User Fields. And this field was not being supplied a value. Cause3b: A required field was not given a value when creating an artifact. For example, copying from Rally to QC without providing a value for the Name field: Error: INFO : RallyConnection.find_new - Found 1 new hierarchicalrequirements in Rally INFO : Connector.copy_to_other - Copy to Quality Center DEBUG : Connector.block in map_fields_to_other - Mapping Project(Team 2) - to - RQ_REQ_PRODUCT(Team 2) DEBUG : QCConnection.create_internal - set all artifact fields ERROR : QCConnection.rescue in create_internal - failed on attempt to create QC Req item from src item ERROR : QCConnection.cleanup_shell_artifact - Attempting to delete the shell req item due to error. ERROR : QCConnection.rescue in delete - Delete failed for req -10 WARN : QCConnection.initialize - (in OLE method `RemoveItem': ) OLE error code:80040556 in <Unknown> Failed to delete requirement. HRESULT error code:0x80020009 Exception occurred. ERROR : QCConnection.rescue in cleanup_shell_artifact - Deletion attempt failed... WARN : QCConnection.initialize - (in OLE method `RemoveItem': ) ....
Code: 8004058D Cause: The <RallyAttachmentLinker /> was being used when copying a Rally UserStory to a QC Requirement. The destination project in QC had versioning enabled. This caused the error. NOTE: When this error occurs, the UserStory is copied to QC and the ExternalID is updated in Rally, but the attachment does not get copied. Error: INFO : Connector.copy_to_other - Rally userstory US413 copied to Quality Center req 16 DEBUG : RallyAttachmentLinker.block in link_related_objects_in_other - Copying attachment: Att1.txt ... WARN : QCConnection.initialize - Error saving attachment for req - 16. WIN32OLERuntimeError: (in OLE method `Post': ) OLE error code:8004058D in <Unknown> Server failed to create requested object HRESULT error code:0x80020009 Exception occurred.. .... <stack trace> .... ANY : ConnectorRunner.process_service - Finished Service COPY_RALLY_TO_QUALITY CENTER
Code: 8004058E Cause: Customer said: Validation failed in QC on 2 fields, only one of which appears on-screen when entering a new defect. The other one is a complicated field which requires a companion field and auto-fill to work properly. Error: INFO : Connector.copy_to_other - Copy to Quality Center DEBUG : Connector.block in map_fields_to_other - Mapping State(Open) - to - BG_STATUS(Open) DEBUG : Connector.block in map_fields_to_other - Mapping Notes(Dev1) - to - BG_DEV_COMMENTS(Dev1) DEBUG : Connector.block in map_fields_to_other - Mapping Description(test) - to - - to - BG_DESCRIPTION(test) WARN : OtherEnumFieldHandler.transform_in - For BG_PRIORITY field could not transform_in(None) DEBUG : Connector.block in map_fields_to_other - Mapping Severity(Major Problem) - to - BG_SEVERITY(4-Very High) DEBUG : Connector.block in map_fields_to_other - Mapping Name(Add to group) - to - BG_SUMMARY(Add to group) DEBUG : Connector.block in map_fields_to_other - Mapping QCPortfolioItem(RM) - to - BG_USER_08(RM) DEBUG : Connector.block in map_fields_to_other - Mapping SubmittedBy(joe@company.com) - to - BG_DETECTED_BY(user5) DEBUG : Connector.block in map_fields_to_other - Mapping CreationDate(2012-12-19TZ) - to - BG_DETECTION_DATE(2012-12-19) DEBUG : Connector.block in map_fields_to_other - Mapping SubmittedBy(joe@company.com) - to - BG_DETECTED_BY(user5) DEBUG : QCConnection.create_internal - set all artifact fields ERROR : QCConnection.rescue in create_internal - failed on attempt to create QC Bug item from src item ERROR : QCConnection.cleanup_shell_artifact - Attempting to delete the shell bug item due to error. ERROR : QCConnection.rescue in delete - Delete failed for bug -57 WARN : QCConnection.initialize - (in OLE method `RemoveItem': ) OLE error code:8004058E in <Unknown> You do not have the required permissions to execute this action. HRESULT error code:0x80020009 Exception occurred. ERROR : QCConnection.rescue in cleanup_shell_artifact - Deletion attempt failed... .... INFO : ConnectorRunner.process_service - Finished Service COPY_RALLY_TO_QUALITY CENTER

Based on a report from another user regarding the same error we recommend making sure that all required fields in QC are being supplied a value during copy service from Rally to QC. In this particular case a required field was not colored in red and marked with * in QC UI, and the user could not know it was required. But in Tools>Customize this field had the Required checkbox checked.


Codes: 80040640, 8000FFFF Cause: Invalid URL (or maybe a bad port number), therefore there was no connectivity to QC. Error1: Could not InitConnection to OLE Server at URL "http://vmwin2008qc11:80801/qcbin" Server has been disconnected while performing GetServerSettings action. Error2: OTA server is not connected.
Code: 800413EC Cause: Attempted to RE-copy the same UserStory from Rally To QC simply by clearing the ExternalID field on the Rally side. This will not work as it will be attempting to create two Requirements in QC with the same name, which is not supported in QC (even though it is in Rally).
Code: 800413ED Cause: User installs QC connector on system, then attempts to invoke the connector *BEFORE*f first connecting to their QC system, via the IE web browser, on the same system as the connector. This happens because the OTA client DLL must be loaded *BEFORE* the connector will work. And it is the act of connecting to the QC system via IE that gets the addins downloaded and installed. Error: Could not create bug - (in OLE method `AddItem':)
Code: 800456CF Cause1: Caused by a "Versioned" project in QC; details are not yet clear. Error1: INFO : QCConnection.find_new - Found 1 New reqs in QC INFO : Connector.copy_to_rally - Copy to Rally DEBUG : Connector.block in map_fields_to_rally - Mapping RQ_REQ_NAME(t1) - to - Name(t1) WARN : QCConnection.pre_copy - Ignoring QC req 1 because this record is locked by a user WARN : QCConnection.pre_copy - QC req 1 will be picked up next run Cause2: In QC, the project was "Versioned". A user was logged into QC (not necessarily the same user that was used in the configuration file). This user had the Requirement 1 highlighted (in the GUI). Requirement 1 was checked out (the padlock icon was open). The connector was invoked and the follow error occurred. Error2: INFO : QCConnection.find_new - Found 1 New reqs in QC INFO : Connector.copy_to_rally - Copy to Rally DEBUG : Connector.block in map_fields_to_rally - Mapping RQ_REQ_NAME(t1) - to - Name(t1) WARN : QCConnection.rescue in checkout_qc - Unable to Checkout req 1 ... skipping ... Exception was (in OLE method `CheckOut': ) OLE error code:800456CF in <Unknown> Entity t1 is already checked out by user1. HRESULT error code:0x80020009
Code: 80047535 or 800403EA Cause: ? (case 96542) We are not 100% sure, but check here: Community Knowledge Base at HP Is the proper revision of the QC Client component installed? The root cause of the issue is that the updated OTA client DLL was not downloaded and registered into the client machine. The solution is to remove the client component from the local machine and reinstall. You can do so by deleting the folder C:\users\\AppData\Local\HP and then access the QC URL and register the client component from the addin page (if you want to integrate QC with other application). Error: ERROR : QCRunConnection.rescue in connect - Could not Login to QC OLE Server with user:"qcuser" and password:********** ERROR : QCRunConnection.initialize - (in OLE method `Login': ) OLE error code:80047535 in <Unknown> OTA version is not compatible with the Application Lifecycle Management server: http://xxxx.org:8070/qcbin/wcomsrv.dll. OTA version: 11, OTA build number: 7484. Server version: 11, server build number: 8092. HRESULT error code:0x80020009 OR this error: ERROR : QCConnection.initialize - (in OLE method `Login': ) OLE error code:800403EA in Failed to Login HRESULT error code:0x80020009 Exception occurred.
English

Feedback

Need more help? The Rally Community is your one-stop shop for self-service and support. To submit feedback or cases to Rally Support, find answers, and collaborate with others, please join us at rallycommunity.rallydev.com.
© 2015 Rally Software Development Corp | Legal