Rally
Integrations Best Practices

This topic is designed as a supplement to our connector-specific guides. Let us know if you have an additional topic we should cover here.

Getting Started with Enterprise Integration Framework

Welcome to working with the
Rally
Enterprise Integration Framework (EIF). When integrating two systems, we have found one recommendation that holds true for all connectors: Start simple.
If you are looking at a connector, the first thing we advise is to define the problem you are trying to solve.
Once you know what team and subset of work items you want to move, you can start to look at what the minimum set of information is that you would want to map. We recommend starting with something as simple as Name, Description, Owner and then figure out what
Rally
projects those work items would go to.

Debugging Create and Update Services

Review Field-level updates from
Rally
for additional information regarding services.
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
.
In your
config.xml
, locate the
<ConnectorRunner>
tag (usually at the bottom of your config file). Inside of the
<Services>
tag, list UPDATE_RALLYFIELDS_AND_OTHER and remove the UPDATE_RALLY_TO_OTHER and UPDATE_OTHER_TO_RALLY service(s).

Old Create and Update Services

The previous versions of services are described below. However, we recommend using UPDATE_RALLYFIELDS_AND_OTHER. The connectors run four basic services to move information between
Rally
and other systems:
COPY_RALLY_TO_OTHER
Find new work items in
Rally
and copy them to the other system.
Query
Rally
where (ExternalID = null) AND (work item project is in projects listed in RallyConnection) AND (all RallyConnection CopySelectors conditions are satisfied)
COPY_OTHER_TO_RALLY
Find new work items in the Other system and copy them to
Rally
.
Query Other system where (RallyID is null) AND (all OtherConnection CopySelectors conditions are satisfied, like MoveToRally = Yes).
The Jira connector queries for "-1" (minus one) instead of null.
UPDATE_RALLY_TO_OTHER
Find work items in
Rally
that are connected to the Other system and move updates.
Query
Rally
where (ExternalID != null) AND (LastUpdateDate is updated since last connector run time) AND (all RallyConnection CopySelectors conditions are satisfied).
UPDATE_OTHER_TO_RALLY
Find work items in the Other system connected to
Rally
work items and move updates.
Query Other system where (RallyID is not null) AND (Other system's work item updated timestamp is since last connector run time) AND (all OtherConnection CopySelectors conditions are satisfied).
In your configuration file, the
<ConnectorRunner>
tag contains the
<Services>
tag where you can specify which services to run. There are four services to chose from; multiple services can be specified:
<Config> .... <ConnectorRunner> <Preview>False</Preview> <LogLevel>Debug</LogLevel> <Services> UPDATE_RALLY_TO_OTHER, UPDATE_OTHER_TO_RALLY, COPY_RALLY_TO_OTHER, COPY_OTHER_TO_RALLY</Services> </ConnectorRunner> </Config>
The connector will run the services in the order listed in the configuration file.

Recommendations

We generally recommend the following when listing multiple services:
  • When you are setting up the connector, start with just the creation services to get connections working, then add the update services
  • List the update services first, then the creation services

Debugging

  • The connector is not finding all of my work items:
    All three systems (the
    Rally
    server, the Other server and the connector server), should have times synchronized fairly closely (within a couple minutes). This can be accomplished through NTP (Network Time Protocol).
  • The connector is not finding any work items with the Copy service:
    1. ExternalID custom field issues:
      • Check the
        Type
        on the ExternalID custom field in
        Rally
        . It must be of type
        String
        . (NOTE: If it is of type
        Text
        , no work items will be found on a query.)
      • Check the spelling of the ExternalID names in the configuration file and ensure they match what you have setup in the
        Rally
        system or the Other system.
      • Rally
        accesses a custom field through its "Display Name" (not its "Name"). Also, spaces and underscores are stripped, so something like "External ID" becomes "ExternalID".
      • Check the custom field in the other system that is to hold the RallyID Be sure it is really "empty". For some of the Other systems, empty is "null", for Jira empty is a minus one (-1). Run a test query in other system, assuming it has a query feature.
    2. Check the
      <CopySelectors>
      (assuming you are using them) to be sure they do not cause your work items to get excluded (from the compound AND criteria).
    3. When running the Copy service, the query is Project scoped. Therefore only the projects declared in the
      <Projects>
      element of the configuration file will be searched.
    4. When running the Update service, the query is Workspace scoped. Therefore all projects in the workspace will be searched
  • The connector is not finding any work items with the Update service:
    1. Be sure you have done an update since the connector was last run. For each configuration file, the connector stores a time file, and it contains the time of the last successful run of the Update services. If you made an update 10 minutes ago and the connector ran in the last 5 minutes, that update may not show up – this sometimes happens when you are debugging. The time file is named "
      <Config-File-Name>time.file
      ", and it contains one line as follows:
      2012-05-24 17:18:58 UTC
    2. Check the timezone that your Other system stores the last updated date and time. Is it in the same timezone as the connector or offset?
    3. Check that the ExternalID or RallyID was really stored between the two systems.
    4. Check the
      <UpdateSelectors>
      (assuming you are using them) to be sure they do not cause your work items to get excluded (from the compound AND criteria).
    5. Check for errors or warnings in the log file – you may need to turn up the level of logging. One of the two systems may have failed on a POST in trying to update.

Managing the Logger and Log Files

As the connectors are running, they will log messages into a file named
rallylog.log
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 as follows:
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 --
log-file-size <integer>.
The
-m <integer>
option pair can be used to specify the maximum number of files in the log file rotation scheme. This can also be expressed as
--max-log-files <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 --log-file-size 50 --max-log-files 20 xxx_config.xml -1
The connector uses multiple logging levels, each increasing in the level of detail. Note in the table below that each level includes all higher level information (for example, WARNING includes all warnings, errors and fatals).
Logger Level
Level of Detail
Example of Detail
0: Debug
Most Detailed
Display Field mapping values
1: Info
...
Connection / Disconnection Info
2: Warning
...
Failed to Map field
3: Error
...
Failed Create work item Messages
4: Fatal
...
...
5: Unknown
Least Detailed
...(shows as ANY in the log file)
These levels are documented at Ruby Logger utility.
In your configuration file, the
<ConnectorRunner>
tag is where the
<LogLevel>
setting is declared, as follows:
<Config> .... <ConnectorRunner> <Preview>False</Preview> <LogLevel>Debug</LogLevel> <Services>UPDATE_OTHER_TO_RALLY, COPY_OTHER_TO_RALLY</Services> </ConnectorRunner> </Config>
General recommendations:
  • When you are setting up the connector, leave the
    <LogLevel>
    at Debug. If you use Debug, you will get the values the connector tries to map for fields along with other debug information.
  • When you are up and running with the connector, set the
    <LogLevel>
    to Warning.
  • If you leave the connector at Info, you will also see information for when the connector is connected to each system on wake and sleep.
We recommend checking the log on a daily or weekly basis to look for exceptions or errors to resolve.

Multiple Configuration Files

Multiple configuration files may be needed if your setup requires:
  • Mapping to more than one workspace in
    Rally
  • Mapping multiple work item types
  • Mapping to multiple containers in the other system, such as:
    • domain/projects in Quality Center
    • team projects in TFS
We recommend naming the configuration files using descriptive names for easier troubleshooting.
To run the connector with multiple configuration files, it is recommend to invoke it once per configuration file. For example:
For Windows:
rally2_xxx_connector.exe config_workspaceA.xml -1 rally2_xxx_connector.exe config_workspaceB.xml -1
For Linux:
rally2_xxx_connector.rb config_workspaceA.xml -1 rally2_xxx_connector.rb config_workspaceB.xml -1
To have these repeated at regular intervals, define a Windows Scheduled Task (or a cron job in Linux) which will be invoked at regular intervals. We recommend such a task be repeated every 10 minutes or more and advise against anything less.

When to Use Multiple Configuration Files

We designed this to be fairly flexible to meet various needs among our connectors. The information below covers some scenarios that can help clarify when and how to use multiple configuration files.

One Directory, Multiple Configuration Files

For running in one process with multiple configuration files, we usually recommend or require this setup if any of the following are true:
  • If you are connecting multiple Quality Center Projects, you will need one
    config.xml
    file for each QC Project.
  • If you are connecting multiple Jira Projects, you will need one
    config.xml
    file for each Jira Project.
  • If you are connecting multiple
    Rally
    Workspaces, you will need one
    config.xml
    file for each
    Rally
    Workspace.
  • If you are connecting multiple work item types, one
    config.xml
    file will be needed for each work item type (Defect, User Story, Test Case).

Multiple Directories

You can also install and setup the connector in multiple parallel directories, for example:
Defects in
C:\Program Files\RallyConnectorFor<othersystem>\Defects\
all EIF files
Stories in
C:\Program Files\RallyConnectorFor<othersystem>\Stories\
second copy of all EIF files
In this case, you can call
rally2_*connector.exe config.xml
in two different processes. Each process can then have its own timer interval.
You could, for example, run every 10 minutes for defects and every 30 minutes for stories.
This setup will also allow you to have two different
rallylog.log
files for the two work items which may help with monitoring of the log files.

How to Include Other XML Files

Within a configuration file, it is possible to have other files of XML text included, resulting in all the files being treated as one XML file. This is accomplished by making use of the XML
External Entities
feature. For example, the normal user mapping in the
<OtherEnumFieldHandler>
section of a configuration file could be removed from the main XML configuration file and pasted into a new XML file named
users.xml
. It might look something like this:
File name:
users.xml
<OtherEnumFieldHandler> <FieldName>BG_RESPONSIBLE</FieldName> <Mappings> <Field><Rally>[email protected]</Rally><Other>qcuser1</Other></Field> <Field><Rally>[email protected]</Rally><Other>qcuser2</Other></Field> <Field><Rally>[email protected]</Rally><Other>qcuser3</Other></Field> .... </Mappings> </OtherEnumFieldHandler>
In the main configuration file, include the following as the first 4 lines:
<?xml version="1.0"?> <!DOCTYPE config SYSTEM "config.dtd" [ <!ENTITY usersFile SYSTEM "users.xml"> ]>
Then, in your main configuration file, wherever the text should occur, enter the string
&usersFile;
. For example:
<Config> .... <Connector> .... <OtherFieldHandlers> &usersFile; ....
Known limitations with XML include:
  • When this feature is used to include a file that contains the user's clear-text password, the connector rewrites the password as an encoded (not encrypted) string. However, the connector will write the encoded string into the main XML file instead of the included password file (and thus overwriting the "include" line). Workaround: If the included file contains the encoded password, the connector will not attempt to rewrite the string.
  • When specifying the full path to the include file, use slashes (
    /
    ) instead of backslashes (
    \
    ). For example, this would be a valid path designation:
    C:/Users/jpkole/RallyQC/x073-Entity-Test-RALLYstory.xml

Using Field Handlers

A field that has been mapped in the
<FieldMapping>
section can have a "field handler" registered against either field (the
Rally
field or the "Other" field). Once done, the field handler is invoked each time that mapping occurs.
It is not supported to register two different field handlers on the same field name. While the connector will silently ignore such a situation and the connector will normally remember only the last one registered, the results are unpredictable (and this is not a supported configuration).

Selecting a Subset of Work Items Through <CopySelectors> and <UpdateSelectors>

The connector can be instructed to select a subset of work items from either
Rally
or the other system when performing the Copy or Update service. Selecting only a few of your work items is helpful when setting up the connector for the first time.
Copy and Update selection criteria are configured in the
<RallyConnection>
and
<OtherConnection>
elements of your configuration file.
Note that the QC connector has both some limitations and extensions to the selector syntax where other connectors do not. The details can be found in the FAQ here.
An example of the selector syntax:
<Config> .... <RallyConnection> .... <CopySelectors> <CopySelector>FormattedID = DE351</CopySelector> <CopySelector>SyncToJIRA = "True"</CopySelector> <CopySelector>State = "Open"</CopySelector> <CopySelector>Priority != "Normal"</CopySelector> <CopySelector>Priority != Low</CopySelector> </CopySelectors> ....
You can have multiple
<CopySelector>
elements and
<UpdateSelector>
elements contained within the
<CopySelectors>
container and
<UpdateSelectors>
container, respectively. Multiple selector elements are ANDed together. If you need an OR capability, we suggest using multiple configuration files to effect that result, or possibly using the not-equal on all the values you do not want selected.
A selector element must have a field name, a space, a relation operator, a space and then your target value. If your target value contains spaces, you do not need to quote the value. For example:
<UpdateSelectors> <UpdateSelector>AssignedTo = John Q. Public</UpdateSelector> ....
The selector syntax supports evaluating a field against a value with a relational operator. The value must be non-null and non-blank. The following is an example of syntax that is
NOT
supported:
<!-- Invalid syntax: --> <CopySelectors> <CopySelector>X_FIELD = </CopySelector> ....
As a general rule, a selector element supports the =, !=, <, >, <= and >= relational operators. However, because the configuration file is in XML, the '<' and '>' characters are problematic and confuse the XML parser. Therefore, use the alphabetic abbreviation equivalents shown in the following table:
<CopySelectors> <CopySelector>LastModified gte 2011-04-05</CopySelector> ....
Relation
Abbreviation
<
lt
<=
lte
>
gt
>=
gte
Another way to move a smaller set of work items from the other system to
Rally
is to create a custom field named "Move to
Rally
?" that is a Yes/No drop-down list or check box. The connector can then select and move only those work items where the custom field is "Yes".
When using
<CopySelectors>
, the query is Project scoped. Only the projects declared in the
<Projects>
element of the configuration file will be searched.

Using Selectors on Reference Fields

Reference fields, which are any field in a work item that actually points to another object (as opposed to containing a simple value) in the OTHER system are not supported.
Fields in a
Rally
referenced object can be used in the selector elements. For example:
<CopySelectors> <CopySelector>Project.Name = MyNewProj1</CopySelector> <CopySelector>Iteration.Name = Iter2</CopySelector> ....

Upgrading a
Rally
Connector on a Windows Machine

Upgrading instructions are unique to your system environment.
  1. Back-up your configuration file(s) and any custom field handlers. The best practice is to ALWAYS rename your configuration files and never use the default
    <connector_name>_config.xml
    files as the uninstall (step 2) will delete those files permanently.
  2. Go to the directory where you installed the
    Rally
    Connector (by default
    C:/Program Files/RallyConnectorfor<connector_name>
    ) and double-click
    unins000.exe
    .
  3. Run the installer,
    RallyConnectorfor<connector_name>Install-<version>.exe
    , for the latest
    Rally
    Connector version.

Upgrading a
Rally
Connector on a Non-Windows Machine

Upgrading instructions are unique to your system environment.
Upgrading on non-Windows systems uses the
rally2*.rb
script.
  1. Back-up your configuration XML file(s) and any custom field handlers. Best practice is to ALWAYS rename your configuration files and never use the default
    <connector_name>_config.xml
    files.
  2. Uninstall the current gem. Open a console shell and type:
    gem uninstall yeti
  3. Once you have saved the gem locally, CD to the directory where the gem resides.
  4. Install the latest gem. Open a console shell and type:
    gem install yeti*.gem

How to Map Fields

When transferring work items from
Rally
, to another system (or vice versa), the configuration file must specify which fields of the work items in
Rally
are to be mapped to which fields in the other system. This is done within the
<FieldMapping>
XML element in the configuration file. When the connector performs a create or update, only the fields specified in this section will be modified.
When you set up your mapping, ensure the fields are compatible between the two systems (for example, an integer field should map to an integer field, or a rich text should map to a rich text in the other system. Otherwise, you might experience situations where information is not created/updated between the two systems and you will see an error in the log file. For example, the connector will post an error for a particular work item if you try to map a string field to a custom field of type integer in
Rally
.
When specifying
Rally
field names, the "Display Name" must be used (as opposed to the "Name"). Also, when specifying the Display Name in the
<FieldMapping>
section, if there are spaces in the Display Name, they should be removed (that is, a Display Name of "Foo Bar" would be declared as
<Rally>FooBar</Rally>
).
If you are mapping a drop-down value in
Rally
to the other system, the drop-down values match. Otherwise, the connector will generate 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 Mapping drop-down values.
For example:
<Config> .... <Connector> <FieldMapping> <Field><Rally>State</Rally> <Other>Status</Other></Field> <Field><Rally>Severity</Rally> <Other>Importance</Other></Field> <Field><Rally>Priority</Rally> <Other>Urgency</Other></Field> </FieldMapping> ....
In the example, the
Rally
"State" field will be mapped to the other system's "Status" field, "Severity" to "Importance", and "Priority" to "Urgency".

Mapping
Rally
ID Fields

Rally
Objects have two identifiers, one which is unique across all
Rally
Entities (the
ObjectID
) and the other which is only unique inside a workspace (the
FormattedID
). These can be viewed by going to a
Rally
defect's detail page (using the
Rally
GUI) and near the top left corner, you should see the
FormattedID
listed as something like DE42. If you select the chain link icon to the left of the bold name and ID, you will go to a specific URL for that defect, which is something like:
https://rally1.rallydev.com/#/3026904716ud/detail/defect/3026966119
. The number at the end of the URL (3026966119 in this example) is the
ObjectID
for the Defect.
The mappings for both of these ID fields can be set up in the
<RallyConnection>
and the
<OtherConnection>
elements of your configuration file.
The following example XML shows a QC Connection where both the
Rally
ObjectID
and
Rally
FormattedID
are being mapped to the QC custom fields named in the
<ExternalIDField>
and
<ExternalEndUserIDField>
tags, respectively. The connectors for Jira and TFS can also recognize these tags.
<!-- This first line is an XML comment --> <Config> .... <QCConnection> <Url>server:port</Url> <Domain>Domain Name</Domain> <Project>Project Name</Project> <User>qcusername</User> <Password>password</Password> <artifactType>BUG</ArtifactType> <!-- The following custom field will contain the Rally ObjectID --> <ExternalIDField>BG_USER_XX</ExternalIDField> <!-- The following custom field will contain the Rally FormattedID --> <ExternalEndUserIDField>BG_USER_YY</ExternalEndUserIDField> </QCConnection> ....

Rally
Rich Text Field 32 KB Character Limit

Rally
has a 32 KB character limit for rich text fields, such as the Description and Notes fields. Other systems such as Micro Focus ALM/Quality Center support a limit beyond 32 KB for text fields which causes data constraint inconsistencies.
If you copy/update a work item from the target system to
Rally
, the connector will warn you that the text is beyond the 32 KB limit and not copy/update the particular work item. The warnings will not prevent the connector from running as it will continue to copy/update the next work item that needs processing.
If you want to avoid warnings for the 32 KB limit,
Rally
advises that you enforce this limit on the connection target system. For example, if you are using Quality Center, you can write a custom script that is executed when the user saves the bug or requirement that automatically restricts any text field to the 32 KB limit. Talk to your system administrator to explore solutions that ensure consistency between text fields in each system when different character limits exist.
Another alternative is to only map the field in one direction. For example, if
Rally
restricts the field to 32 KB, then only allow the copy/update from
Rally
to the other system. This ensures that the text for that field is never too big.
<Config> .... <Connector> <FieldMapping> <Field> <Rally>Description</Rally> <Other>BG_DESCRIPTION</Other> <Direction>TO_OTHER</Direction> </Field> ....

Field Directionality

To restrict when a particular field is copied or updated, add a Direction tag to the FieldMapping section for that field.
Specify
TO_OTHER
(upper or lower case) if you want
Rally
to be the source of record, meaning changes from the other system are never pushed to
Rally
. Specify
TO_RALLY
(upper or lower case) if you want the other system to be the source of record, meaning changes from
Rally
are never pushed to the other system.
<Config> .... <Connector> <FieldMapping> <Field> <Rally>Description</Rally> <Other>BG_DESCRIPTION</Other> <Direction>TO_OTHER</Direction> </Field> <Field> <Rally>Notes</Rally> <Other>BG_NOTES</Other> <Direction>to_rally</Direction> </Field> ....

Mapping Required Fields and Field Defaults

When you want to copy work items (such as user stories, defects, test cases) from one system to another (
Rally
, QC, Jira) and the destination system has required fields defined on the work item, you can use one (not both) of the following two methods:
  1. Use the
    <FieldMapping>
    element described in How to map fields.
  2. If you do not use field mappings, and you want a required field in the destination system to always have the same default value, use the
    <FieldDefaults>
    XML element. For example:
    <Config> .... <QCConnection> .... <FieldDefaults> <Field><Name>Severity</Name><Default>Rally-Severity</Default></Field> <Field><Name>Status</Name> <Default>Rally-Status</Default></Field </FieldDefaults> ....
    In the example, the XML element
    <QCConnection>
    could be something like
    <RallyConnection>
    or
    <OtherConnection>
    , depending on which connector you are using. The QC field "Severity" is automatically assigned the default string value of "Rally-Severity" for any work item created in the QC system. The QC field "Status" automatically gets a string value of "Rally-Status".

Mapping Fields With Null Values

When the connector updates field values, if one side of the connections is a null value, the connector skips the update. If it is the only update to the underlying artifact, the
rallylog.log
will say
Skipped update for
<id>
since no fields changed
.
Different systems treat null or empty values for given field types inconsistently, so we chose not to nullify values during updates due to this disparity. Reflection of null values is further complicated by the fact that users are able to map a field of one type in one system to a field of another type in the other system.

Field-Level Updates From
Rally

A service is available for updates with the work item EIF connectors. UPDATE_RALLYFIELDS_AND_OTHER has been introduced to help the connector deal with updates in both systems. The service will override the UPDATE_RALLY_TO_OTHER and UPDATE_OTHER_TO_RALLY services.
<Config> .... <ConnectorRunner> .... <Services>UPDATE_RALLYFIELDS_AND_OTHER</Services> </ConnectorRunner> </Config>
This service first searches
Rally
for updates and pushes only the recently-changed fields (that were mapped) to the other system. It then searches the other system for updates and pushes all mapped fields into
Rally
. This reduces the chance of overwriting data when work items are modified in both systems.
Example:
The connector runs and a work item is copied and up to date in both systems.
  • In
    Rally
    , a user changes Severity to Low
  • In QC, a user updates the Description
With the older services, the first update service listed would take precedence. For example, if UPDATE_RALLY_TO_OTHER were listed first, the connector would copy all the
Rally
data to the other system and the Description change would not be processed.
Now, however, the connector will search
Rally
for updates and check what mapped
Rally
fields have changed. In this example, only Severity changed and the connector will send only the Severity change over to the other system instead of all of the mapped fields. Then the connector will search the other system for updates and the Description change will be pushed to
Rally
, along with all other mapped fields.

Configure the New Service

  • A warning is logged if the old update services are listed with the new one, noting that the old update services will be skipped.
  • Field Level
    <Direction>
    tag mappings are still respected.
  • If you wish to configure a one-way feed of data and updates from another system to
    Rally
    , we recommend still using COPY_OTHER_TO_RALLY and UPDATE_OTHER_TO_RALLY.
  1. In your
    config.xml
    file, locate the
    <ConnectorRunner>
    tag (usually at the bottom of your config file).
  2. Inside of the
    <Services>
    tag, list UPDATE_RALLYFIELDS_AND_OTHER and remove the UPDATE_RALLY_TO_OTHER and UPDATE_OTHER_TO_RALLY service(s).

Mapping Drop-Down Values

If you have different drop-down values between the two systems, you can setup up another type of field handler in your configuration file which defines the mapping. For example:
<Config> .... <Connector> <FieldMapping> <Field><Rally>Priority</Rally> <Other>BG_PRIORITY</Other></Field> <Field><Rally>Severity</Rally> <Other>BG_SEVERITY</Other></Field> .... </FieldMapping> <OtherFieldHandlers> <OtherEnumFieldHandler> <FieldName>BG_PRIORITY</FieldName> <Mappings> <Field><Rally>Resolve Now</Rally><Other>1</Other></Field> <Field><Rally>High</Rally> <Other>2</Other></Field> <Field><Rally>Normal</Rally> <Other>3</Other></Field> <Field><Rally>Low</Rally> <Other>4</Other></Field> <Field><Rally>Trivial</Rally> <Other>5</Other></Field> <Field><Rally>None</Rally> <Other>6</Other></Field> </Mappings> </OtherEnumFieldHandler> .... </OtherFieldHandlers> <RallyFieldHandlers> <RallyEnumFieldHandler> <FieldName>Severity</FieldName> <Mappings> <Field><Rally>Crash Data/Loss</Rally> <Other>S1</Other></Field> <Field><Rally>Major Problem</Rally> <Other>S2</Other></Field> <Field><Rally>Minor Problem</Rally> <Other>S3</Other></Field> <Field><Rally>Cosmetic</Rally> <Other>S4</Other></Field> </Mappings> </RallyEnumFieldHandler> .... </RallyFieldHandlers> ....
This sets up a mapping of the values from the
Rally
field Priority to the other systems field of BG_PRIORITY. The value in the
<FieldName>
element should be the name of the field being mapped.
The
<Mappings>
element defines the
Rally
value within the
<Rally>
tags and the corresponding other system's value within the
<Other>
tags. In the example, in the
<OtherEnumFieldHandler>
for
BG_PRIORITY
, the value
Resolve Now
in
Rally
maps to a value of
1
in the other system and
High
in
Rally
maps to a value of
2
in the other system.
  • The connectors are not able to handle drop-down fields in
    Rally
    which have a
    <<No Entry>>
    value in the UI (for example, the field is empty).
  • Multi-value drop-down fields are not supported.
You could add additional mappings for other fields to the configuration file by following this same format and adding another
<OtherEnumFieldHandler>
element with the corresponding values.
This field handler allows for both many-to-one (or many-to-fewer) value mappings. However, for any field which has many-to-one mapping defined, the inverse operation, one-to-many (or fewer-to-many) is undefined. For instance, given this configuration file syntax:
.... <OtherEnumFieldHandler> <FieldName>MyFieldName</FieldName> <Mappings> <Field><Rally>Submitted</Rally> <Other>NEW</Other></Field> <Field><Rally>Submitted</Rally> <Other>STUDY</Other></Field> <Field><Rally>Closed</Rally> <Other>FIXED</Other></Field> <Field><Rally>Fixed</Rally> <Other>FIXED</Other></Field> </Mappings> </OtherEnumFieldHandler> ....
When mapping from
Rally
to Other, a
Rally
value of "Submitted" will produce unpredictable results. Also, when mapping from Other to
Rally
, a Other value of "FIXED" will produce unpredictable results.
There is also a
<OtherConditionalEnumFieldHandler>
, which is very similar to the
<OtherEnumFieldHandler>
except only the exceptions need to be declared, such as corresponding entries in the pull-down lists of both systems which are identical, need not be declared.

Mapping User Names

To map
Rally
fields which reference a user name, add a field mapping to the
<FieldMapping>
section (within the
<Connector>
section) as in one or both of the following examples:
<Field><Rally>Owner</Rally> <Other>Bug_Owner</Other></Field> <Field><Rally>SubmittedBy</Rally><Other>Bug_Finder</Other></Field>
We recommend that all users which are expected to be mapped between the two systems be created in
Rally
before you start using the connector. Even for those users of the Other system which do not intend to use
Rally
, there should be an account created for them in
Rally
so that the system can have a valid user reference in the copied work items. You may, however, mark those users as inactive in
Rally
if you do not wish them to ever be active users. In this case, the connector will still be able to set the fields to point to these inactive users.
In
Rally
, the
Owner
and
SubmittedBy
fields on a work item (HierarchicalRequirement, Defect, Test Case, and so on) are "reference" fields. This means they do not contain a simple string value, but rather they are pointers to yet another object (the User object in these examples). When the connector is updating or copying a work item from the Other system to
Rally
, it must translate the Other system's user name into a valid
Rally
user name. To accomplish this task, the connector can use one of the four methods for mapping user names between
Rally
and the Other system.
Using the
<Domain>
XML tag
If you want to map users between
Rally
and the Other system, you can specify a
<Domain>
XML tag in the
<Connector>
section as follows:
<Config> .... <Connector> <OtherFieldHandlers> <OtherUserFieldHandler> <FieldName>Bug_Owner</FieldName> <Domain>YourCompanyName.com</Domain> </OtherUserFieldHandler> </OtherFieldHandlers> </Connector> ....
The
<FieldName>
XML tag contains the name of the field in the Other system and the
<Domain>
XML tag specifies the expected domain for user names in
Rally
. In the example,
peter
in the Other system would be mapped to in
Rally
.
Using the MiddleName (or other) field on the User object.
On each User profile in
Rally
, you could assign the
MiddleName
(or other unused field on the User object) field to be the exact ID of the user in the Other system. When the connector is copying a work item, it will search
Rally
for a User object whose
MiddleName
(or whichever field is specified in the
<ReferenceFieldLookupID>
tag) matches the Other system's user name string. When a match is found, this
Rally
user will be used in the field mapping for this new
Rally
work item. Valid fields are
User
,
Owner
,
SubmittedBy
and
Tester
. Example configuration file syntax:
<Config> .... <Connector> <RallyFieldHandlers> <RallyUserFieldHandler> <FieldName>Owner</FieldName> <ReferencedFieldLookupID>MiddleName</ReferencedFieldLookupID> </RallyUserFieldHandler> .... </RallyFieldHandlers> </Connector> ....
Using an
<OtherEnumFieldHandler>
XML tag
User name mapping may be done the way it is described in "Mapping drop-down values" section of our help. This is basically a method where every user is explicitly mapped between systems. Example configuration file syntax:
<Config> .... <Connector> <OtherFieldHandlers> <OtherEnumFieldHandler> <FieldName>RQ_REQ_AUTHOR</FieldName> <Mappings> <Field><Rally>[email protected]</Rally> <Other>JDoe</Other></Field> <Field><Rally>[email protected]</Rally> <Other>JSmith</Other></Field> <Field><Rally>[email protected]</Rally> <Other>DThomp</Other></Field> .... </Mappings> </OtherEnumFieldHandler> </OtherFieldHandlers> </Connector> ....
The drawback to this approach is that it may require a very long list of users. If two different "username" fields need to be mapped, rather than repeating the
<OtherEnumFieldHandler>
mapping, you could also use the XML entity feature described in How to include other XML files.
When using the Micro Focus ALM/Quality Center connector with this method of user name mapping, the "User Name" field from both
Rally
and Quality Center are to be used in the example (as opposed to the "Email Address" fields).
Using a
<RallyCSVUserMappingFieldHandler>
XML tag
User name mapping can be done using a CSV file. See example configuration file here.

Mapping Reference Fields From
Rally

In
Rally
, some fields within a work item are string or number values while other fields are actually pointers (called a "reference") to other objects. For the most commonly used reference fields, no additional syntax is required to properly map these fields. For some of the more infrequently used
Rally
reference fields, the connector has special syntax when they are listed as fields to be mapped. More advanced and simple reference field handling was introduced with the 4.4.12 release.
  • No FieldHandler is necessary if the intended attribute value desired for the mapping is the Name field. RallyReferenceFieldHandler for the Project, Release, and Iteration fields has been deprecated (since 4.4.2). When you need to map an attribute other than Name for (Project, Release or Iteration), you'll need to use a
    <RallyReferenceAttributeLookupFieldHandler>
    (see below).
  • Advanced field handling for other Reference fields. Applicable fields:
    • Parent
    • Requirement
    • TestCase
    • TestCaseResult
    • TestFolder
    • WorkProduct
    These fields are found in
    Rally
    work items, including HierarchicalRequirement, Defect, and TestCase.
    Use a RallyReferenceFieldHandler with a
    <ReferencedFieldLookupID>
    tag for the intended lookup attribute. The lookup attribute should be a non-reference field. Examples of such attributes are "Name" and "ObjectID".
  • Project, Release or Iteration with an intended lookup attribute
    other
    than the "Name" field: use
    <RallyReferenceAttributeLookupFieldHandler>
    for this with a corresponding
    <ReferencedAttributeLookupID>
    tag for the specific attribute to be used as the map value.
  • Within the
    <Connector>
    section of the configuration file, specify the field to be mapped in the
    <FieldMapping>
    section.
  • Also within the
    <Connector>
    section of the configuration file, create a
    <RallyFieldHandlers>
    section.
  • Within this section, specify the field in a
    <RallyReferenceFieldHandler>
    element as
    <FieldName>the_name_of_the_field</FieldName>
    .
  • If no
    <ReferencedFieldLookupID>
    tag and value is specified, the "Name" attribute is used by default.
  • If the default value is not suitable for your purposes, explicitly provide a
    <ReferencedFieldLookupID>
    tag and value, where the value is a
    Rally
    work item attribute such as "DisplayName", "FormattedID", "ObjectID".
Example syntax:
<Config> .... <Connector> <FieldMapping> <Field><Rally>Requirement</Rally><Other>BG_USER_07</Other></Field> </FieldMapping> .... <RallyFieldHandlers> <RallyReferenceFieldHandler> <FieldName>Requirement</FieldName> <ReferencedFieldLookupID>FormattedID</ReferencedFieldLookupID> </RallyReferenceFieldHandler> </RallyFieldHandlers> </Connector> ....
When running any WorkItem Connector 4.4.0 or beyond (4.4.x, 4.5.x, ...), if the connector detects the use of a
<RallyReferenceFieldHandler>
for one of the Project, Release or Iteration fields, a deprecation notice (warning) will be written to the log file and the field handler for that particular field will not be registered. The field will be mapped using the referenced item's Name field.
If there are multiple
Rally
projects listed in the
<Projects>
element under
<RallyConnection>
, then the work items from the other system will be copied to
Rally
and placed in the first
Rally
project listed.

Mapping Boolean Fields To and From
Rally

In
Rally
, some fields within a work item have boolean values. These fields can be mapped to Jira Radio Buttons or Micro Focus ALM/Quality Center Boolean fields. They can also be mapped to Jira Check Box fields, however, we do not recommend this as the Jira Check Box fields are multi-value fields. This field handler will map the fields in both directions.
  • Within the
    <Connector>
    section of the configuration file, specify the field to be mapped in the
    <Fieldmapping>
    section.
  • Also within the
    <Connector>
    section of the configuration file, create a
    <RallyFieldHandlers>
    section.
  • Within this section, specify the field in a
    <RallyBooleanFieldHandler>
    element as
    <FieldName>the_name_of_the_Rally_field</FieldName>
  • Specify the values to map in the
    <Mappings>
    section.
Example syntax:
<Config> .... <Connector> <FieldMapping> <Field><Rally>TestBoolean</Rally><Other>JiraRadioButton</Other></Field> </FieldMapping> .... <RallyFieldHandlers> <RallyBooleanFieldHandler> <FieldName>TestBoolean</FieldName> <Mappings> <Field><Rally>true</Rally><Other>yes</Other></Field> <Field><Rally>false</Rally><Other>no</Other></Field> </Mappings> </RallyBooleanFieldHandler> </RallyFieldHandlers> </Connector> ....

Connector Lockfile

Whenever the connector runs, it will create a lockfile (in the working folder) named
LOCK.tmp
. This file will exist until the connector terminates, at which time the lockfile is deleted. The contents of the lockfile is one line of the form:
<PID> <DATE> <TIME> <TIMEZONE> <CONFIG-FILE-NAME> <DELAY-ARGUMENT>
For example:
1684 2012-06-20 16:24:00 Z MyConfig.xml -1
Each time the connector is invoked, it will check for the existence of a lock file in the working folder, and:
  • If found, the connector will issue this warning:
    WARN : ConnectorRunner.acquire_lock - A LOCK.tmp file exists
    The connector will then attempt to determine if the PID (process ID) which created the lockfile still exists, and:
    • if the PID is still running, the connector will exit after printing this error:
      ERROR : ConnectorRunner.acquire_lock - Another connector process (1234) is still running, unable to proceed ERROR : ConnectorRunner.acquire_lock - Simultaneous processes for this connector are incompatible, exiting now ERROR : ConnectorRunner.acquire_lock - Unable to proceed with this invocation of the connector
    • if the PID is gone, the connector will proceed normally after printing this warning:
      WARN : ConnectorRunner.acquire_lock - A prior connector process (1234) did not clean up the lock file on termination, proceeding with this run
  • If not found, the connector creates a lock file, and when done, the connector deletes the lock file.
This prevents more than one instance of the connector being invoked from the same working folder.

Running as a Scheduled Task on Windows

When you are ready to deploy to production, you may want to consider running the connector as a scheduled task. You can set up a scheduled task on Windows (this example assumes Quality Center).
  1. Create a batch file (such as the following example
    rallyWin-qc.bat
    ). Note in the following script there are two variables defined:
    :: :: rallyWin-qc.bat :: :: Set the "Connector folder" (where the connector has been installed). set cfolder="C:\Program Files (x86)\RallyConnectorforQualityCenter" :: Set the "Working folder" (where the configuration files are kept and :: modified; this is typically somewhere in the user's home folder). set wfolder="C:\Users\johndoe\QCconfigFiles" :: Invoke the connector. %cfolder%\rally2_qc_connector.exe %wfolder%\qc-config.xml -1 >> %wfolder%\Connector.log 2>&1 ::the end::
    In this example:
    • The -1 as the second argument tells the connector to run only once, then exit.
    • When the connector runs, it will append its status messages into a file named
      rallylog.log
      in your working folder (the
      wfolder
      variable).
    • Any catastrophic error messages (like permission denied, and so on) would be found in the file
      Connector.log
      in your working folder (the
      wfolder
      variable).
    • cfolder
      - the folder where the connector is installed (typically something like
      C:\Program Files (x86)\RallyConnectorforQualityCenter
      )
    • wfolder
      - the folder where the user works (the working directory). This is typically your home directory, which is something like
      C:\Users\johndoe\QCconfigFiles
      .
  2. Set up a scheduled task in Windows to run your script, specifying your batch script as the task action.

Email Notification of Errors and Warnings

The connectors can send email when errors or warnings occur in the logfile. With this feature enabled, the connectors can send a summary email for each configuration file used, and the subject line of the email will contain the name of the configuration file. To send email to multiple emails use a semi-colon to delimit each email address. All errors and warnings encountered during the connector run for that configuration file will be collected and reported in an email as follows:
  • If the level is set to
    Error
    , then a summary email containing all the errors is sent.
  • If the level is set to
    Warning
    , then a summary email containing all the errors and warnings is sent.
Only these two values for the
<Level>
tag are supported:
  • <Level>Error</Level>
  • <Level>Warning</Level>
Here are two examples of the configuration file syntax required to enable this feature:
Standard SMTP server - No Authentication:
<Config> .... <ConnectorRunner> <Preview>False</Preview> <LogLevel>Debug</LogLevel> <Services>COPY_RALLY_TO_OTHER</Services> <Emailer> <Level>Warning</Level> <SendEmailFrom>[email protected]</SendEmailFrom> <SendEmailTo>[email protected]</SendEmailTo> <SMTPServer>smtp.acme.com</SMTPServer> <SMTPPort>25</SMTPPort> </Emailer> </ConnectorRunner> </Config>
SMTP server - with TLS and Authentication:
<Config> .... <ConnectorRunner> <Preview>False</Preview> <LogLevel>Debug</LogLevel> <Services>COPY_RALLY_TO_OTHER</Services> <Emailer> <Level>Warning</Level> <SendEmailFrom>[email protected]</SendEmailFrom> <SendEmailTo>[email protected]</SendEmailTo> <SMTPServer>smtp.acme.com</SMTPServer> <SMTPPort>587</SMTPPort> <SMTPDomain>Your-Domain.com</SMTPDomain> <SMTPUser>[email protected]</SMTPUser> <SMTPPassword>Your-Password</SMTPPassword> <SMTPSec>TLS</SMTPSec> </Emailer> </ConnectorRunner> </Config>

Finding XML Syntax Errors

The XML configuration files can get rather lengthy and cumbersome, hindering the hunt for syntax errors. For such issues, this web page can be used for XML validation: http://www.w3schools.com/xml/xml_validator.asp.
Copy your XML text and paste it into the window and select
Validate
.
Also note that syntax errors in the configuration file are typically logged in the
rallylog.log
file. For example:
  • Special characters in the
    <WorkspaceName>
    or
    <Project>
    tags:
    If these fields contain special characters, the characters must be escaped as in:
    • "&" (ampersand) must be entered as "&amp;"
    • ">" (greater than) must be entered as "&gt;"
    • "<" (less than) must be entered as "&lt;"
    Example 1: Note the following (invalid) configuration file snippet, and the log file output:
    <Config> <RallyConnection> <Projects> <Project>JP & Nick Project</Project> ....
    ERROR : Class.initialize - xmlParseEntityRef: no name ERROR : ConnectorRunner.initialize - xmlParseEntityRef: no name ERROR : Object.exception - Message xmlParseEntityRef: no name ERROR : Object.exception - Stack Trace ....
    Example 2: Note that with a small change, the error report is different:
    <Config> <RallyConnection> <Projects> <Project>JP&Nick Project</Project> ....
    ERROR : Class.initialize - EntityRef: expecting ';' ERROR : ConnectorRunner.initialize - EntityRef: expecting ';' ERROR : Object.exception - Message EntityRef: expecting ';' ERROR : Object.exception - Stack Trace ....

Known Limitations of the EIF Connectors

Several connectors are built upon a common library called EIF (Extensible Interface Framework): Atlassian Jira, Micro Focus ALM/Quality Center (formerly HP ALM/Quality Center), and TFS. Below is a list of known limitations in these connectors.
Using the Tag object in
Rally
Only the following connector supports
Rally
Tags:
SSO not supported
The
Rally
WorkItem Connectors (and the
Rally
SCM connectors) are not compatible with the SSO feature; however, these connectors can be used in SSO Exception Mode.
Some new fields on
Rally
work items are not available.
In previous versions of the EIF connectors, the framework upon which the connectors were built was tied to the
Rally
WSAPI version 1.42
. Because of this, new fields in the most current version of the
Rally
WSAPI (v2.0 at the time of this writing) were not available in those older versions of the connectors. Some commonly desired "new" fields that are not available in the older versions of the connectors are:
Connectors will not copy mapped fields which are empty.
When a mapped field is manually cleared by a user, this "clearing" will not be copied to the Other system by the connectors (for example, the field in the Other system will not be cleared). This was a design feature in the connectors and the reasons for it are varied. A possible work-around is to define a string value in each system which essentially represents "unset", and map those values together.

Generic Errors Generated by the EIF Connectors

If you press
Control + C
while the connector is running, it is likely to generate the following error in the logfile:
ERROR : ConnectorRunner.initialize - ERROR : Object.exception - Message ERROR : Object.exception - Stack Trace ERROR : Object.block in exception - /Users/..../yeti-2.8.8/lib/yeti/connector_runner.rb:170:in `sleep' ERROR : Object.block in exception - /Users/..../yeti-2.8.8/lib/yeti/connector_runner.rb:170:in `run' ERROR : Object.block in exception - ./rally2_<connector>_connector.rb:30:in `<main>'