Rally Integrations FAQ and Best Practices

Print this topicEmail this topicSave as PDF

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.

  1. General
  2. Debugging create and update services
  3. Managing the logger and log files
  4. Multiple configuration files
  5. When to use multiple configuration files
  6. Selecting a subset of artifacts
  7. Upgrading Rally Connector
  8. How to map fields
  9. Mapping Rally ID fields
  10. Rally text field considerations
  11. Field directionality
  12. How to map fields
  13. Mapping Rally ID fields
  14. Mapping required fields
  15. Mapping drop-down values
  16. Mapping user names
  17. Mapping reference fields from Rally
  18. Running as a schedule task on Windows

General

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

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 config.xml file, the <ConnectorRunner> tags contain the services to run settings:

       

Note: The connector will run the services in the order listed in the configuration file.

Recommendations

We generally recommend the following when listing multiple services:

  • When you are setting up the connector, start with just the creation services to get connections working, then add the update services
  • List the update services first, then the creation services

Debugging

If your connector is not finding any artifacts with the Copy services:

  1. Check your External or RallyID field names and make sure that they match what you have setup in Rally or the Other system.
  2. Rally uses the Display Name from the field. Spaces and Underscores are stripped so External ID becomes ExternalID.
  3. Check that the RallyID field in the other system really is null - run a test query in that systems test query.
  4. Check the CopySelectors and/or UpdateSelectors (assuming you are using them) to be sure they do not cause your artifacts to get excluded (via the compound AND criteria).

If your connector is not finding any artifacts with the Update to push across:

  1. Check that you have recently done an update. The connector stories a time file for each config.xml you have setup and that time file stores 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.
  2. Check the timezone that your Other system stores the last updated date and time – is it in the same timezone as the connector or offset?
  3. Check that the ExternalID or RallyID was really stored between the two systems.
  4. Check 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

The logger has the same logging framework for all connectors. There are four logging levels, each in an increasing level of detail:

Logger Level Level of Detail Example of Detail
Error Least Detailed Failed Create Artifact Messages
Warning ... Failed to Map field
Info ... Connection / Disconnection Information
Debug Most Detailed Display Field mapping values

In your config.xml file, the <ConnectorRunner> tags contain the Logger level setting:

   

We generally recommend the following:

  • When you are setting up the connector, leave the log level at Debug
  • When you are up and running with the connector, set the log level to Warning

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, declare the list of configuration files as arguments to the rally2_*_connector.exe command (or the rally2_*_connector.rb script). For example:

   

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

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

   

Note: We recommend a sleep value of 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 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 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)

Multiple directories

You can also install and setup the connector in multiple parallel directories, for example:
Defects in C:\Program Files\RallyConnectorFor<othersystem>\Defects\ all EIF files
Stories in C:\Program Files\RallyConnectorFor<othersystem>\Stories\ second copy of all EIF files

In this case, you can call 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.

Selecting a subset of artifacts

You can setup the connector to select a subset of artifacts from Rally or the Other system. 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 <RallyConnection> and <OtherConnection> tags of your configuration file.

Using CopySelectors

This example shows a QC Connection where only the bugs that have a custom field (BG_USER_06) equal to Y AND who have a BG_STATUS not equal to Closed are selected to move to Rally.

       

You can have multiple CopySelector elements contained within the CopySelectors container. Multiple CopySelector 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 CopySelector item 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:

       

The CopySelector 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:

       

As a general rule, a CopySelector supports the =, !=, <, >, <= and >= relational operators. However, because the configuration file is in XML, the '<' and '>' characters are problematic and confuse the XML parser. Therefore, you'll need to use the alphabetic abbreviation equivalents shown in the following table:

       

abbrev

Systems that don't support the full set of relational operators:

  • Bugzilla:
    • 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".

How to upgrade

Upgrading Rally Connector

Upgrading on Windows

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

Upgrading on non-Windows (using rally2*.rb script)

  1. Back-up your configuration XML file(s) and any custom field handlers. Best practice is to ALWAYS rename your configuration files and never use the default <connector_name>_config.xml files.
  2. Un-install the current gem. Open a console shell and type:
    gem uninstall yeti
  3. Once you have saved the gem locally. CD to the directory where the gem resides.
  4. Install the latest gem. Open a console shell and type:
    gem install yeti*.gem

Fields

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. Do this from the <FieldMapping> XML element. 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 IDs – one that is unique across all Rally Entities and another that is visible to your users and is only unique inside a workspace. For example on the Defect artifact, if you are on a specific detail page for a defect, you will see the ID listed as DE42. This is the FormattedID. If you click on the chain link icon next to the bold ID and name, you will go to a specific URL for that defect like: https://rally1.rallydev.com/slm/detail/df/123456789, the number at the end of the URL is the Object ID for the artifact.

The mappings for both of these ID fields can be set up in the <RallyConnection> or <OtherConnection> tags of your configuration file.

The connectors are programmed to map in the following pattern:

Rally OtherConnection
Object ID ExternalIDField
Formatted ID ExternalEndUserIDField

Example of the ExternalIDField and ExternalEndUserIDField tags

This example shows a QC Connection where both the Rally Object ID and Rally Formatted ID are mapped to different custom fields in Quality Center. Jira, TFS, Bugzilla and ClearQuest can also use the ExternalEndUserIDField tags.

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.

     

Field directionality

To restrict when a particular field is copied or updated, add a Direction tag to the FieldMapping section for that field.

Specify TO_OTHER if you want Rally to be the source of record, meaning changes from the other system are never pushed to Rally. Specify TO_RALLY 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

There may be times when you want to copy artifacts (such as user stories, defects, test cases, etc) from one system to another (Rally, QC, JIRA, CQ, etc). If 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 the required field in the destination system to always have the same default value, use the <FieldDefaults> XML element. For example:

    In the above example, the XML element <QCConnection> could be something like <RallyConnection> or <CQConnection>, depending on which connector you are using. In this example, the QC field "Severity" is automatically given a default value of "Rally-Severity" for any artifact created in the QC system. And the QC field "Status" automatically gets a value of "Rally-Status".

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:

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 in the other system.

The <Mappings> element defines the Rally value within the <Rally> tags and the corresponding other system's values within the <Other> tags. For example, Resolve Now in Rally maps to a value of 1 in the other system and High maps to a value of 2 in the other system. Finally, a non-required drop-down in Rally has a None value that you will want to map to a value in the other system.

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 and many-to-fewer value mappings.

Mapping users

To map Rally fields which reference a user name, add a field mapping to the <Connector><FieldMapping> 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 3 methods for mapping user names between Rally and the Other system, as follows:

  1. Using the <Domain> XML tag
    If you want to map users between Rally and the Other system, you can specify a <Domain> XML tag in the <Connector> section as follows:
     

    The <FieldName> XML tag contains the name of the field in the Other system and the <Domain> determines 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.

  2. 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 field (or whichever field is specified in the tag) matches the Other system's user name string. When a match is found, this Rally user becomes the Owner (or SubmittedBy) of this new Rally artifact. Example configuration file syntax:
     

  3. 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. Example configuration file syntax:
     

    The drawback to this approach is that it may require a very long list of users.

Mapping reference fields from Rally

In Rally, some fields within an object (an artifact) are string values while other fields are actually pointers (called a "Reference") to other objects. For the following fields, the connector has special syntax when they are to be mapped:

  • mapping Iteration
  • mapping Parent
  • mapping Project
  • mapping Release
  • mapping Requirement
  • mapping TestCase
  • mapping TestCaseResult
  • mapping TestFolder
  • mapping WorkProduct

These fields are found in artifacts (Hierarchical Requirement, Defect, Test Case, etc.) and are basically URLs which point to the another artifact in Rally. However, in the other system, those fields may appear to the connector as a string containing the actual name.

In order to map one of these fields:

  • 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,
  • optionally, within this <RallyReferenceFieldHandler> element, specify a <ReferencedFieldLookupID> which will be used to represent this referenced object. Typical fields used here are "DisplayName", "FormattedID", "MiddleName", "Name", "ObjectID", etc. If this <ReferencedFieldLookupID> is not specified, then "Name" is used by default.

Example syntax:

NOTE: If the Project field is not mapped, and there are multiple Rally projects listed in the <Projects> element under <RallyConnection>, then the artifacts in the other system will be copied to Rally (new and updated) and placed in the first Rally project listed in the <Projects> element.

Running as a Scheduled Task on Windows

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

  1. Create a batch file (such as rally-qc.bat) for each connector version with the contents similar to this:

    or

    2. The -1 on the above command lines causes the connector to run only once, the quit.

  2. Go to All Programs → Accessories → System Tools → Scheduled Tasks, and click Add a Scheduled Task.

  3. On the Scheduled Task Wizard, for Program to Run, browse to the batch file created above (such as rally-qc.bat) and:
    1. Give the task a name of your choosing.
    2. In the schedule dialog, select Daily.
    3. Select 12:00 AM as the time to start running the task.
    4. Enter the name of the user the scheduled task should run as and that user's password.
    5. On the final wizard dialog, You have successfully scheduled the following task, select Open advanced properties when I finish.
  4. In the Advanced Properties dialog, verify the following:
    • On the Task tab, ensure the Run only if logged on field is not selected.
    • On the Schedule tab, click the Advanced button, then click Repeat task. In the Repeat task section, verify these values:
      • Every: 15 minutes
      • Until time: 23:59 PM

The above procedure configures the task to run every day (from 12:00am to 11:59pm) at an interval of 15 minutes. If you review the list of Scheduled Tasks, you should see Schedule Every 15 minute(s) from 12:00 AM... and Next Run Time should show a time stamp in approximately 15 minutes. 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.

Every time the connector runs as a scheduled task, the connector opens a lock file and deletes the lock file once the connector finishes running to ensure that more than one instance of the connector is not running at the same time. If the connector repeatedly produces an error that the lock file is found causing the connector to not run, you can manually delete the lock file called LOCK.tmp. The LOCK.tmp file resides in the same directory as the Rally connector.

© 2012 Rally Software Development Corp | Legal