Rally Integrations Best Practices
RallyIntegrations 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
RallyEnterprise 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
Rallyprojects those work items would go to.
Debugging Create and Update Services
Review Field-level updates from
Rallyfor additional information regarding services.
- SearchesRallyfirst 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 intoRally.In yourconfig.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
Rallyand other systems:
- Find new work items inRallyand copy them to the other system.QueryRallywhere (ExternalID = null) AND (work item project is in projects listed in RallyConnection) AND (all RallyConnection CopySelectors conditions are satisfied)
- Find new work items in the Other system and copy them toRally.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.
- Find work items inRallythat are connected to the Other system and move updates.QueryRallywhere (ExternalID != null) AND (LastUpdateDate is updated since last connector run time) AND (all RallyConnection CopySelectors conditions are satisfied).
- Find work items in the Other system connected toRallywork 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.
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
- The connector is not finding all of my work items:All three systems (theRallyserver, 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:
- ExternalID custom field issues:
- Check theTypeon the ExternalID custom field inRally. It must be of typeString. (NOTE: If it is of typeText, 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 theRallysystem or the Other system.
- Rallyaccesses 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.
- 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).
- 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.
- 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:
- 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
- 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?
- Check that the ExternalID or RallyID was really stored between the two systems.
- 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).
- 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.login 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:
-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 --
-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
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
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).
Level of Detail
Example of Detail
Display Field mapping values
Connection / Disconnection Info
Failed to Map field
Failed Create work item Messages
...(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>
- 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 inRally
- 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:
rally2_xxx_connector.exe config_workspaceA.xml -1 rally2_xxx_connector.exe config_workspaceB.xml -1
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 oneconfig.xmlfile for each QC Project.
- If you are connecting multiple Jira Projects, you will need oneconfig.xmlfile for each Jira Project.
- If you are connecting multipleRallyWorkspaces, you will need oneconfig.xmlfile for eachRallyWorkspace.
- If you are connecting multiple work item types, oneconfig.xmlfile will be needed for each work item type (Defect, User Story, Test Case).
You can also install and setup the connector in multiple parallel directories, for example:
all EIF files
second copy of all EIF files
In this case, you can call
rally2_*connector.exe config.xmlin 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.logfiles 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 Entitiesfeature. 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:
<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
Rallyfield 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
Rallyor 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
<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
<UpdateSelector>elements contained within the
<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
<!-- 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> ....
Another way to move a smaller set of work items from the other system to
Rallyis 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".
<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
Rallyreferenced 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
RallyConnector on a Windows Machine
Upgrading instructions are unique to your system environment.
- 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.xmlfiles as the uninstall (step 2) will delete those files permanently.
- Go to the directory where you installed theRallyConnector (by defaultC:/Program Files/RallyConnectorfor<connector_name>) and double-clickunins000.exe.
- Run the installer,RallyConnectorfor<connector_name>Install-<version>.exe, for the latestRallyConnector version.
Upgrading a Rally Connector on a Non-Windows Machine
RallyConnector on a Non-Windows Machine
Upgrading instructions are unique to your system environment.
Upgrading on non-Windows systems uses the
- 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.xmlfiles.
- Uninstall the current gem. Open a console shell and type:gem uninstall yeti
- Once you have saved the gem locally, CD to the directory where the gem resides.
- 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
Rallyare 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
Rallyfield 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
If you are mapping a drop-down value in
Rallyto 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.
<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
RallyObjects have two identifiers, one which is unique across all
ObjectID) and the other which is only unique inside a workspace (the
FormattedID). These can be viewed by going to a
Rallydefect's detail page (using the
RallyGUI) and near the top left corner, you should see the
FormattedIDlisted 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
ObjectIDfor the Defect.
The mappings for both of these ID fields can be set up in the
<OtherConnection>elements of your configuration file.
The following example XML shows a QC Connection where both the
FormattedIDare being mapped to the QC custom fields named in the
<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
RallyRich Text Field 32 KB Character Limit
Rallyhas 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,
Rallyadvises 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
Rallyrestricts the field to 32 KB, then only allow the copy/update from
Rallyto 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> ....
To restrict when a particular field is copied or updated, add a Direction tag to the FieldMapping section for that field.
TO_OTHER(upper or lower case) if you want
Rallyto be the source of record, meaning changes from the other system are never pushed to
TO_RALLY(upper or lower case) if you want the other system to be the source of record, meaning changes from
Rallyare 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:
- Use the<FieldMapping>element described in How to map fields.
- 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
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
Rallyfor 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.
The connector runs and a work item is copied and up to date in both systems.
- InRally, 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
Rallydata to the other system and the Description change would not be processed.
Now, however, the connector will search
Rallyfor updates and check what mapped
Rallyfields 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 toRally, we recommend still using COPY_OTHER_TO_RALLY and UPDATE_OTHER_TO_RALLY.
- In yourconfig.xmlfile, 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).
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
Rallyfield Priority to the other systems field of BG_PRIORITY. The value in the
<FieldName>element should be the name of the field being mapped.
<Mappings>element defines the
Rallyvalue within the
<Rally>tags and the corresponding other system's value within the
<Other>tags. In the example, in the
BG_PRIORITY, the value
Rallymaps to a value of
1in the other system and
Rallymaps to a value of
2in the other system.
- The connectors are not able to handle drop-down fields inRallywhich 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
Rallyto Other, a
Rallyvalue 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
Rallyfields 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
Rallybefore 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
Rallyso that the system can have a valid user reference in the copied work items. You may, however, mark those users as inactive in
Rallyif 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.
SubmittedByfields 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
Rallyuser name. To accomplish this task, the connector can use one of the four methods for mapping user names between
Rallyand the Other system.
- Using the<Domain>XML tag
- If you want to map users betweenRallyand 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 inRally. In the example,peterin the Other system would be mapped to inRally.
- Using the MiddleName (or other) field on the User object.
- On each User profile inRally, you could assign theMiddleName(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 searchRallyfor a User object whoseMiddleName(or whichever field is specified in the<ReferenceFieldLookupID>tag) matches the Other system's user name string. When a match is found, thisRallyuser will be used in the field mapping for this newRallywork item. Valid fields areUser,Owner,SubmittedByandTester. 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 bothRallyand 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
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
Rallyreference 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:
These fields are found inRallywork 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 attributeotherthan 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 aRallywork item attribute such as "DisplayName", "FormattedID", "ObjectID".
<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
Rallyprojects listed in the
<RallyConnection>, then the work items from the other system will be copied to
Rallyand placed in the first
Mapping Boolean Fields To and From Rally
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.
<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> ....
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>
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 existsThe 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).
- Create a batch file (such as the following examplerallyWin-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 namedrallylog.login your working folder (thewfoldervariable).
- Any catastrophic error messages (like permission denied, and so on) would be found in the fileConnector.login your working folder (thewfoldervariable).
- cfolder- the folder where the connector is installed (typically something likeC:\Program Files (x86)\RallyConnectorforQualityCenter)
- wfolder- the folder where the user works (the working directory). This is typically your home directory, which is something likeC:\Users\johndoe\QCconfigFiles.
- 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 toError, then a summary email containing all the errors is sent.
- If the level is set toWarning, then a summary email containing all the errors and warnings is sent.
Only these two values for the
<Level>tag are supported:
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>
Sample Configuration Files
- Atlassian Jira
- Micro Focus ALM/Quality Center
- VCS TFS
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
Also note that syntax errors in the configuration file are typically logged in the
rallylog.logfile. For example:
- Special characters in the<WorkspaceName>or<Project>tags:If these fields contain special characters, the characters must be escaped as in:
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 ....
- "&" (ampersand) must be entered as "&"
- ">" (greater than) must be entered as ">"
- "<" (less than) must be entered as "<"
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 inRally
- Only the following connector supportsRallyTags:
- Jira (see example here)
- SSO not supported
- Some new fields onRallywork items are not available.
- In previous versions of the EIF connectors, the framework upon which the connectors were built was tied to theRallyWSAPI version 1.42. Because of this, new fields in the most current version of theRallyWSAPI (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 + Cwhile 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>'