Rally Integrations FAQ and Best Practices
This page is designed as a supplement to our connector specific Install and Usage guides. Let us know if you have a additional topic we should cover here.
- Sample configuration files
- Debugging create and update services
- Managing the logger and log files
- Multiple configuration files
- When to use multiple configuration files
- How to include other XML files
- Using field handlers
- Selecting a subset of artifacts
- Using selectors on reference fields
- Upgrading Rally Connector
- How to map fields
- Mapping Rally ID fields
- Rally text field considerations
- Field directionality
- Mapping required fields and field defaults
- Field-level updates from Rally
- Mapping drop-down values
- Mapping user names
- Mapping reference fields from Rally
- Connector lockfile
- Running as a Scheduled Task on Windows XP
- Running as a Scheduled Task on Windows 7
- Email notification of errors and warnings
- Finding XML syntax errors
- Known limitations of the EIF connectors
- Generic errors generated by the EIF connectors
Getting started with Enterprise Integration Framework
Welcome to working with Rally's 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. This should be something like: "We currently have all of our bugs in system X. We now have a team working and defining stories in Rally. It would be really nice to have defects from system X in Rally so that the team can prioritize and schedule those defects." If your current option is to just have a person export and import defects, then the EIF connectors can definitely help your team solve this problem. From that problem, you can pick a small team and subset of defects from the other system to start with the connector.
Once you know what team and subset of artifacts you want to move, you can start to look at what the minimum set of information you would want to map would be. To get things going, we usually recommend starting with something as simple as Name, Description, Owner and then figure out what Rally projects those artifacts would go to.
Debugging create and update services
|Service Name in Config||Service Detail||Service Configuration|
|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
Review Field-level updates from Rally in this document for additional information regarding services.Old services
The previous version of services is described below. However, we recommend using the new service described above, UPDATE_RALLYFIELDS_AND_OTHER. The connectors run four basic services to move information between Rally and other systems:
|Service Name in Config||Service Detail||Service Query|
|COPY_RALLY_TO_OTHER||Find new artifacts in Rally and copy them to the other system||Query Rally where (ExternalID = null) AND (artifact project is in projects listed in RallyConnection) AND (all RallyConnection CopySelectors conditions are satisfied)|
|COPY_OTHER_TO_RALLY||Find new artifacts in the Other system an copy them to Rally||Query Other system where (RallyID is null) AND (all OtherConnection CopySelectors conditions are satisfied, like MoveToRally = Yes)|
|UPDATE_RALLY_TO_OTHER||Find artifacts 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 artifacts in the Other system connected to Rally artifacts and move updates||Query Other system where (RallyID is not null) AND (Other system's artifact 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 service can be specified:
Note: 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 my artifacts:
- 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 artifacts with the Copy service:
- 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 artifacts 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.
- Check the
<CopySelectors>(assuming you are using them) to be sure they do not cause your artifacts 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.
- The connector is not finding any artifacts 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 artifacts 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.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:
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).
These levels are documented at http://corelib.rubyonrails.org/classes/Logger/Severity.html.
In your configuration file, the
<ConnectorRunner> tag is where the
<LogLevel> setting is declared, as follows:
We generally recommend the following:
- When you are setting up the connector, leave the
- When you are up and running with the connector, set the
If you use Debug, you will get the values the connector tries to map for fields along with other debug information.
If you want to leave the connector at Info, you will also see information for when the connector is connected to each system on wake and sleep.
We also 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 artifact types
- Mapping to multiple containers in the other system, such as:
- domain/projects in Quality Center
- databases in ClearQuest
- team projects in TFS
Note: 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 the above invocation 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 left this designed 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 as noted above - 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 for each QC Project
- If you are connecting multiple JIRA Projects, you will need one config.xml for each JIRA Project
- If you are connecting multiple Rally Workspaces, you will need one config.xml for each Rally Workspace
- If you are connecting more than one ClearQuest Schema, you will need a config.xml for each CQ Schema
- If you are connecting multiple artifact types, one config.xml will be needed for each artifact type (Defect, User Story, Test Case)
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 the 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 artifacts 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
In the main configuration file, include the following as the first 4 lines:
<!DOCTYPE config SYSTEM "config.dtd" [
<!ENTITY usersFile SYSTEM "users.xml">
Then, in your main configuration file, where ever the text should occur, enter the string &usersFile;. For example:
Known limitations with XML include:
- When this feature is used to include a file which 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.
WARNING: 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 artifacts through
The connector can be instructed to select a subset of artifacts from either Rally or the Other system when performing the COPY or UPDATE service. Selecting only a few of your artifacts 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.
Please 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 our FAQ here.
An example of the selector syntax:
<CopySelector>FormattedID = DE351</CopySelector>
<CopySelector>SyncToJIRA = "True"</CopySelector>
<CopySelector>State = "Open"</CopySelector>
<CopySelector>Priority != "Normal"</CopySelector>
<CopySelector>Priority != Low</CopySelector>
You can have multiple
<CopySelector> elements and
<UpdateSelector> elements contained within the
<CopySelectors> container and
<UpdateSelectors> container respectively. Multiple selector elements are AND`ed 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 don't 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:
<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:
<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:
<CopySelector>LastModified gte 2011-04-05</CopySelector>
Systems that do not support the full set of relational operators:
- supports: =, !=, < (lt) and > (gt) relational operators
- not supported: <= (lte) and >= (gte) relation operators
Tip: Another way to move a smaller set of artifacts from the other system to Rally is to create a custom field named "Move to Rally?" that is a Yes/No drop-down or checkbox. The connector can then select and move only those artifacts where the custom field is "Yes".
NOTE: When using
<CopySelectors>, the query is Project scoped.
Therefore only the projects declared in the
<Projects> element of the configuration file will be searched.
Using selectors on reference fields
Reference fields, which is any field in an artifact 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:
<CopySelector>Project.Name = MyNewProj1</CopySelector>
<CopySelector>Iteration.Name = Iter2</CopySelector>
Upgrading Rally Connector
Upgrading on Windows
- 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.
- Go to the directory where you installed the Rally Connector (by default C:/Program Files/RallyConnectorfor<connector_name>) and double-click the unins000.exe.
- Run the installer, RallyConnectorfor<connector_name>Install-<version>.exe, for the latest Rally Connector version.
Upgrading on non-Windows (using rally2*.rb script)
- 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.
Un-install 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 artifacts (user stories, defects, test cases, ...) from Rally, to another system (or vice versa), the configuration file must specify which fields of the artifacts 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 the 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 artifact if you try to map a string field to a custom field of type integer in 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 the next section Mapping drop-down values.For example:
In the above 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. And if you click on 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 Quality Center custom fields named in the
<ExternalEndUserIDField> tags, respectively. The connectors for JIRA, TFS, Bugzilla and ClearQuest can also recognize these tags.
<!-- The following custom field will contain the Rally ObjectID -->
<!-- The following custom field will contain the Rally FormattedID -->
Rally text field considerations
Rally has a 32k character limit for rich text fields. Examples are the Summary, Description and Notes fields. Other systems such as Quality Center or Bugzilla support a limit beyond 32k for text fields which causes data constraint inconsistencies.
How does the connector handle text greater than 32k in Rally?
If you copy/update a work item from the target system to Rally, the connector will warn you that the text is beyond the 32k 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.
How to prevent this from happening?
If you want to avoid warnings for the 32k 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 32k limit. Please speak 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 32k, then only allow the copy/update from Rally to the other system. This ensures that the text for that field is never too big.
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.
Mapping required fields and field defaults
When you want to copy artifacts (such as user stories, defects, test cases) from one system to another (Rally, QC, JIRA, CQ) and the destination system has required fields defined on the artifact, you can use one (not both) of the following two methods:
- Use the <FieldMapping> element described above 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>
In the above example, the XML element
<QCConnection>could be something like
<CQConnection>, depending on which connector you are using. In this example, the QC field "Severity" is automatically assigned the default string value of "Rally-Severity" for any artifact created in the QC system. And the QC field "Status" automatically gets a string value of "Rally-Status".
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.
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 artifacts are modified in both systems.
The connector runs and an artifact 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.
Configuring the new service:
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).
A warning is logged if the old update services are listed with the new one, noting that the old update services will be skipped.
<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.
Generic field handlers
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:
<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>
The above 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.
<Mappings> element defines the Rally value within the
<Rally> tags and the corresponding other system's value within the
<Other> tags. In the above 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.
IMPORTANT: 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).
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.
Note: 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:
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 system 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:
Note: We currently 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 artifacts. 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 an artifact (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 an artifact 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 4 methods for mapping user names between Rally and the Other system, as follows:
- Using the
- 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>
<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 above example, peter in the Other system would be mapped to peter@YourCompanyName.com in Rally.
- Using the
- 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 an artifact, it will search Rally for a User object whose MiddleName (or whichever field is specified in the
<ReferencedFieldLookupID>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 artifact. Valid fields are User, Owner, SubmittedBy and Tester. Example configuration file syntax:<Config>
- Using an
- 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>
- NOTE 1: 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 above
<OtherEnumFieldHandler>mapping, you could also use the XML entity feature described above under How to include other XML files.
- NOTE 2: When using the 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 above example (as opposed to the "Email Address" fields).
- Using an
- Using a
- User name mapping can be done using a CSV file. See example configuration file here.
- Using a
Mapping reference fields from Rally
In Rally, some fields within an an artifact 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 the third bullet below).
- Advanced field handling for other Reference fields.
These fields are found in Rally artifacts, 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.
- Within the
<Connector>section of the configuration file, specify the field to be mapped in the
- Also within the
<Connector>section of the configuration file, create a
- Within this section, specify the field in a
- 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 artifact attribute such as "DisplayName", "FormattedID", "ObjectID".
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.
Note: If there are multiple Rally projects listed in the
<Projects> element under
<RallyConnection>, then the artifacts from the other system will be copied to Rally and placed in the first Rally project listed.
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:
The connector will then attempt to determine if the PID (process ID) which created the lockfile still exists, and:WARN : ConnectorRunner.acquire_lock - A LOCK.tmp file exists
- 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 the PID is still running, the connector will exit after printing this error
- 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 XP
When you are ready to deploy to production, you may want to consider running as a scheduled task. Follow these steps to set up a scheduled task on Windows (this example assumes Quality Center):
- Create a batch file (such as the following example rallyWin7-qc.bat). Note in the following script there are two variables defined:
- 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".
:: Set the "Connector folder" (where the connector has been installed).
set cfolder="C:\Program Files (x86)\RallyConnectorforQualityCenter"
:: Set the "Working folder" (where the configurations files are kept and
:: modified; this is typically somewhere in the user's home folder).
:: Invoke the connector.
%cfolder%\rally2_qc_connector.exe %wfolder%\qc-config.xml -1 >> %wfolder%\Connector.log 2>&1
Note: In the above script:
- 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, again in your working folder (the wfolder variable).
- Click on Start, select All Programs → Accessories → System Tools → Scheduled Tasks.
- In the Scheduled Tasks window, double click on Add Scheduled Task.
- In the Scheduled Task Wizard window, click Next.
- In the next window (where you are to select the program to run), click on Browse... and find the batch file created above (such as rallyWInXP-qc.bat), select it (highlight) and click Open. Then:
- In the next window, give the task a name of your choosing (or use the default).
- Under Perform this task: selection, click Daily and click Next.
- In the next window (the heading is Select the time and day you want this task to start):
- In the Start time: box, select 12:00 AM.
- Select Every Day
- Select a Start date: (or use the default).
- Click Next
- In the next window, enter the username and password of the user the scheduled task should run as (this should be a valid user on the windows box), then click Next.
- In the next (and final) window (You have successfully scheduled the following task:), select the box Open advanced properties for this task when I click Finish, then click Finish.
- In the next window, verify the following:
- Under the Task tab, the Run: box should contain the correct path name to your BAT script created previously.
- The Start in: box should contain the correct path name to the folder where you wish this script to run.
- The box Run only if logged on should NOT be checked.
- Under the Schedule tab, click the Advanced button.
- In the next window, Advanced Schedule Options, check the box labeled Repeat task.
- In the Repeat task: section:
- In the Every: boxes, enter 15 and minutes.
- In the Until: box, select Time: and enter 11:59 PM.
- Click OK.
- Click OK again.
The above procedure configures the task to run every day (from 12:00am to 11:59pm) at an interval of every 15 minutes. If you review the list of Scheduled Tasks, under the Schedule column, you should see Every 15 minute(s) from 12:00 AM for 1439 minutes every day, starting MM/DD/YYYY and the Next Run Time column should show a time stamp in less than 15 minutes or so. If the list does not display an upcoming time stamp, please review the steps again or refer to the Microsoft documentation for information on setting up Windows scheduled tasks (for example, for WindowsXP or for Windows7).
Running as a Scheduled Task on Windows 7
The following is a real world example of setting up a scheduled task on Windows 7. This example was done for Rally's Quality Center connector:
- Create a simple batch file (such as the example startqc-simple.bat on the QC help page).
- Click on Start, select All Programs, select Accessories select System Tools and click on Task Scheduler.
- In the "Task Scheduler" window, click on "Action" --> "Create Task...".
- The "Create Task" window opens into the first tab, "General":
- In the "Name:" box, enter "RallyQCconnector".
- In the "Description:" box, enter "Rally's HP ALM/QC connector".
- Select the "Run whether the user is logged in or not" option.
- Check the box labeled "Do not store password. ...".
- NOTE: If using the TFS WorkItem Connector, then leave this box unchecked as the password should be stored to allow the connector to run unattended.
- Click on the "Triggers" tab:
- Click "New..." (near bottom left) and a window called "New Trigger" opens.
- In the "Begin the task:" pull-down, select "At task creation/modification".
- Check the box labeled "Repeat task every:", select "15 minutes" in the pull-down.
- Select "Indefinitely" in the pull-down labeled "for a duration of:".
- Check the "Activate:" box (the current date and time should already be present).
- Check the "Enabled" box (it's probably already checked).
- Click "OK".
- Click on the "Actions" tab:
- Click "New..." (near bottom left again) and a new window called "New Action" opens.
- In the box labeled "Action:", select "Start a program" (it's probably already selected).
- Under the box labeled "Program/script:", click "Browse..." and find your BAT file. Mine was located at: C:\Users\jpkole\MyQCfiles\startqc-simple.bat
- Under the box labeled "Start in (optional):", enter the folder name "C:\Users\jpkole\MyQCfiles".
- Click "OK".
- Under the "Conditions" tab, I left the defaults in place.
- Under the "Settings" tab, I left the defaults in place.
- Click "OK" at the bottom of the "Create Task" window.
- The task should run.
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. All errors and/or 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.
NOTE: 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:
SMTP server - with TLS and Authentication:
Sample configuration files
A configuration file which will transfer Tags on Rally Defects to Keywords on Bugzilla Bugs.
A simple configuration file which will connect to Bugzilla and Rally, thus providing proof the client has: - Ruby is installed and accessible; - all Ruby gems are in place; - there is connectivity to both systems; - the config file syntax is correct; - pathnames to files are correct;
<Emailer>featue of Rally's JIRA (and others) connector. This will send a non-authenticated email to the designated user only when ERRORs or WARNINGs occur.
featue of Rally's JIRA (and others) connector. This will send an email to the designated user only when ERRORs or WARNINGs occur.
Used to copy Discussions or Comments between Rally and JIRA.
A simple configuration file which will connect to JIRA and Rally, thus providing proof the client has: - Ruby is installed and accessible; - all Ruby gems are in place; - there is connectivity to both systems; - the config file syntax is correct; - pathnames to files are correct;
<RelatedObjectLinkers>featue of Rally's JIRA connector. This will copy a Bug from JIRA, which has attachments, to a Defect in Rally with attachments.
A configuration file used to copy Rally UserStories to JIRA Tasks.
A simple configuration file which will connect to JIRA5 and Rally, thus providing proof the client has: - Ruby is installed and accessible; - all Ruby gems are in place; - there is connectivity to both systems; - the config file syntax is correct; - pathnames to files are correct;
A simple configuration to copy Rally Defects to JIRA5 bugs.
A configuration which can be used to copy Bugs from JIRA to Defects in Rally. When copy has completed, both the Bug in JIRA and the Defect in Rally will have a clickable link to the artifact in the other system.
<RallyAttachmentLinker />featue of Rally's JIRA connector. This will copy a Story from JIRA, which has attachments, to a Story in Rally with the attachments, and vice versa.
Demonstrate coping Rally's "CreationDate" (a read-only field) to JIRA's "Due Date" (this is a one-way copy).
Used to copy and update Rally Tags with JIRA Labels, in both directions (with caveats).
<Emailer>featue of Rally's QC (and others) connector. This will send a non-authenticated email to the designated user only when ERRORs or WARNINGs occur.
This configuration file will COPY (in one direction only) from Quality Center to Rally, in this fashion: FROM: "Tests" in QC's TestPlan TO: "TestCases" in Rally's TestFolder (under TestPlan)
To connect to the Quality Center system and the Rally system, thus providing proof the client has: - there is connectivity to both systems; - the config file syntax is correct; - pathnames to files are correct;
To copy a QC Bug, which contains a custom field containing a Rally UserStory FormattedID, to a Rally Defect such that the "Requirement" Field on the new Rally Defect will contain a pointer to the Rally UserStory.
A simple QC connector configuration file which will copy Defects from Rally to Bugs in QC.
A simple QC connector configuration file which will copy Bugs from QC to Defects in Rally.
A configuration file used to copy QC Requirements to Rally User Stories.
A configuration file which will perform a one-time COPY (only) of Rally TestCases and Steps --to-- QC Tests and TestSteps.
NOTE: UPDATE is not supported.
A configuration file which will perform a one-time COPY (only) of QC Tests and TestSteps --to-- Rally TestCases and Steps.
NOTE: UPDATE is not supported.
This is two configuration files which will: 1) Copy QC Tests to Rally TestCases 2) Copy QC Runs to Rally TestCaseResults
Test a custom field handler which will be used by the QC connector to translate all occurrences of a given text string in "Description".
A custom field handler (named
<RallyUsernameToQcUserFieldHandler>) used by the QC connector to map Rally's "SubmittedBy" and "Owner" fields on a Defect to QC's fields "BG_DETECTED_BY" and "BG_RESPONSIBLE" (respectively), when the only difference between the Rally's Username field and QC's User field is the at-sign (@) versus the underscore (_).
Used to copy Rally's "Test Cases" and "Steps" to QC, and to copy QC's "Tests" and "Design Steps" to Rally.
Used to copy QC requirements from a specific QC folder, and copy Rally UserStories into the same QC folder.
- QC-config-concat.pxml (contains 2 configuration files)
Used to demonstrate
- QC-config-ReqTest-2-StoryTestcase.pxml (contains 2 configuration files)
These two configuration files will copy QC Requirements and QC Tests (under Test Plan in QC) in a way which will preserve the relationship between the QC Requirement and QC Test.
NOTE: This functionality works in the direction of QC to Rally only.
An example configuration file used to copy Rally Defects to/from QC Bugs, while mapping the Rally's Owner and SubmittedBy fields to QC's BG_RESPONSIBLE and BG_DETECTED_BY fields, using a CSV file to define the relationship between Rally Usernames and QC Usernames.
A minimal configuration file used to connect to both Rally and TFS, then exit (tested on TFS2010 & TFS2012)
A configuration file used to copy Rally UserStories to TFS Requirements.
A configuration file used to test the TFS2012
Used to copy Rally Stories and their associated tasks, to TFS2012 (maintaining the association in TFS2012. This example uses
<TFSTreePathFieldHandler>and the two
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 click the "Validate" button.
Also note that syntax errors in the configuration file are typically logged in the rallylog.log file. For example:
- Special characters in the
- If these fields contain special characters, the characters must be escaped as in:
- "&" (ampersand) must be entered as "&",
- ">" (greater than) must be entered as ">",
- "<" (less than) must be entered as "<",
<Project>JP & Nick Project</Project>
....Example2: Note that with a small change, the error report is different:ERROR : Class.initialize - xmlParseEntityRef: no name
ERROR : ConnectorRunner.initialize - xmlParseEntityRef: no name
ERROR : Object.exception - Message xmlParseEntityRef: no name
ERROR : Object.exception - Stack Trace
....ERROR : Class.initialize - EntityRef: expecting ';'
ERROR : ConnectorRunner.initialize - EntityRef: expecting ';'
ERROR : Object.exception - Message EntityRef: expecting ';'
ERROR : Object.exception - Stack Trace
- Special characters in the
Known limitations of the EIF connectors
There are five 5 connectors built upon a common library called EIF (Extensible Interface Framework): Atlassian JIRA, Bugzilla, IBM ClearQuest, HP Quality Center (ALM), and TFS. Below is a list of known limitations in these connectors.
- Using the Tag object in Rally
- Only the following connectors support 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 artifacts are not available
- The EIF framework, upon which the connector is built, is tied to the Rally WSPAI 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) are not available to the connector. Some commonly desired "new" fields that are not avaliable 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 control-C is hit while the connector is running, it is likely to generate the following error in the logfile: