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

Print this topicEmail this topic

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
Note: Rally development will no longer maintain the connector with bug fixes against Quality Center 10. Support will continue to assist with general usage issues. The connector is still fully supported when used with Quality Center 11.

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

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

  • 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 services to run, and in what order.

A new service, UPDATE_RALLYFIELDS_AND_OTHER, 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 makes the chances of overwrites of data highly unlikely. The only scenario where an overwrite might occur is if Peter made changes in Rally and Al made changes in the other system for the same fields, the Rally information is copied over to the other system (possibly overwriting the data of the other system), then all data is copied over to the Rally system.

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

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

workflow

Basic installation steps

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

The Rally Connector for Quality Center documentation includes:

System setup

Rally Integrations FAQ and Best Practices contains useful information for connector setup.

Software and hardware requirements

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

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

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

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

  • The base hardware recommended would be a Pentium IV or greater processor with 512MB of RAM for one installed location
  • Run no more than 5–10 configuration files per install location
  • As 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 for log file space

Pre-installation checklist

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

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

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

Installation for Windows

Double-click the RallyConnectorforQualityCenterInstall-X.Y.Z-bbb.exe to use the install wizard. Follow the prompts to complete the installation.
installer

The Windows installer will install the following files (by default in C:\Program Files\RallyConnectorforQualityCenter):

  • 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; 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 ExternalID field in Quality Center

Contact your Quality Center project administrator to perform these updates:

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

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

Rally setup

Create an ExternalID field in Rally

  1. Log in to Rally as a workspace or subscription administrator.
  2. Go to Setup → Workspaces & Projects.
  3. Click on the appropriate workspace that you wish to map to Quality Center.
  4. On the workspace detail page, click the Fields link in the sidebar and ensure the Work Item Type selected is TestCase (or whatever work item you are mapping).
  5. Click Actions → New Field.
  6. Enter a Name and Display Name of ExternalID (the Name and Display Name must be identical), and select a type of String.

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

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

Make note of the name of this field. Once you start using the connector, this will contain the ExternalID 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 TestCase work item type.

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

Connector configuration

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>
                    <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>
                    <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, user, password, and so on.
  • <RallyTestResultConnection>
    Defines the connection information to Rally including Rally URL, username, password, and so on. 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 between the <Connector> tags in the configuration file and defines what fields map between the two systems.

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

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

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 to Rally Name → Headline, Rally Description → Description, Rally Priority → 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>
  .... </Connector>

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

If your drop-down values are different between the two systems, see Map Drop-down Values.

Field handlers

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>

Map drop-down values
Map users
Map reference fields

XML tags

The <RallyConnection> XML tags:

Tag Name Description Sample Values
     
<RallyConnection>
Required
Opening parent tag for this section.  
<Url>
Required
Server used to connect to Rally. sandbox.rallydev.com
rally1.rallydev.com
<WorkspaceName>
Required
Workspace in Rally you want to copy and update work items. My Workspace
MyWorkspace
<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. <Project>Rally1</Project>
<Project>Rally2</Project>
<User>
Required
Login name for user to make the Web Services requests to create and update work items in Rally. user@company.com
<Password>
Required
Password associated with the above <User>. Note: The first time the connector runs, it will encode the password so it is not saved in plain text. mypassword
<ArtifactType>
Required
Type of artifact you want to create/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. Refer to the Create an External ID Field in Rally section above. ID
<CopySelectors>
   <CopySelector>
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>.
<CopySelector>
Status = Open
</CopySelector>
<CopySelector>
Priority = Low
</CopySelector>
<UpdateSelectors>
   <UpdateSelector>
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>.
<UpdateSelector>
Release != alpha
</UpdateSelector>
</RallyConnection>
Required
Closing parent tag for this section.  

Tip: Avoid 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;"

 

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.  
<TestExternalIDField>
Required
Quality Center user field of type String on TEST table that stores the unique ID for the Rally work item. TS_USER_xx
<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>
To be documented.

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>
To be documented.
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.  
   <RallyReferenceFieldHandler>
      <FieldName>
         ObjectName
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-field
      </ReferencedFieldLookupID>
   </RallyReferenceFieldHandler>
Used to map a field from an object.

User, Owner, Tester, etc


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

User, Owner, Tester, etc


Name, FormattedID, etc
   <RallyUserEmailFieldHandler>
      <FieldName>ObjectName</FieldName>
   </RallyUserEmailFieldHandler>
Uses the email address of the object ObjectName. User, Owner, Tester, etc
   <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>
To be documented.
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. This allows changes done in both systems to not cause overwrites of old data.

Copy services:

COPY_JIRA_TO_RALLY
COPY_RALLY_TO_JIRA

Update services:

UPDATE_JIRA_TO_RALLY
UPDATE_RALLY_TO_JIRA

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

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

  1. To start the connector on Windows, open a DOS shell and enter:
  2. rally2_qc_connector.exe  qc_config_test.xml  qc_config_run.xml
  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.

Multiple configuration files

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

To run multiple instances of the connector for different configuration files, pass in the list of configuration files as arguments to the rally2_qc_connector.exe executable (or rally2_qc_connector.rb ruby script). For example:

For Windows:
    rally2_qc_connector.exe  config_workspaceA.xml  config_workspaceB.xml

For Linux:
    ruby  rally2_qc_connector.rb  config_workspaceA.xml  config_workspaceB.xml

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

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

For Windows:
    rally2_qc_connector.exe  config_workspaceA.xml  config_workspaceB.xml  10

For Linux:
    ruby  rally2_qc_connector.rb  config_workspaceA.xml  config_workspaceB.xml  10

Rally recommends a sleep value of 10 minutes or more and advise against anything less.

 

Troubleshoot the connector

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

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

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

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

If you still cannot determine the root cause of an issue, log in to the Rally Success Community and attach the entire log file and config file along with your description of the problem you are experiencing.

The Rally Success Community is your one stop shop for self service and support. Accessing the Success Community is quick and easy!

To sign up:

  1. Navigate to https://rallydev.force.com/success/login
  2. First time to the site? Click "Not a member?"
  3. Complete the self service registration form and you'll be automatically logged into the Success Community

Mapping releases or iterations with multiple projects

If you are using a <RallyReferenceHandler> to map releases and iterations with the same name and multiple projects, you may receive an error if the release or iteration you are updating on the test references a different project than the given test 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.

Best practices

Map Rally projects

If you are copying tests from Quality Center to Rally using the RallyReferenceFieldHandler with projects, you may see a Could not find Rally Project with name ... error in the log file if the connector user does not have editor permissions to that project in Rally.

Pessimistic locking in Quality Center

When an entity is selected in Quality Center, QC assumes that you are editing the record and locks the entity. The update RALLY_TO_OTHER service will not update an entity in QC which was modified in Rally if you have locked the record in QC.

English

Feedback

Please send us your feedback regarding our help site. For feedback regarding the Rally product, click here to open a support case or click here to submit a new feature request
English
By submitting this form, you accept the Mollom privacy policy.
© 2014 Rally Software Development Corp | Legal