Microsoft TFS for Work Items Installation & User Guide

Print this topicEmail this topic

The Rally Connector for TFS Work Items can synchronize work items in TFS with artifacts in Rally. The connector runs on a Windows computer behind your firewall using Microsoft's TFS interface and accesses Rally through the Rally Web Services API, version 1.43. Most work item artifact fields between the two systems can be reflected.

The connector is configured through an XML file. A log file is created to track all changes made in Rally and TFS by the connector. The connector requires that a custom field exists in each system to store the unique ID of the linked objects in the other system. The connector copies fields from Rally or TFS based on field mapping specified in the configuration file. Standard and custom fields can be mapped between the two systems.

Important: Only certain item hierarchies are supported
TFS allows you to create arbitrary hierarchies of work items. For example, you could have user stories as children of bugs. Because of the domain model mismatch between these arbitrary hierarchies and the Rally object model, the connector in general does not support reflecting hierarchical relationships between work items. However, one exception is linking TFS tasks to their parent story. Learn how to Copy story-task bundles from Rally to TFS. So, while you can map any TFS work item type to a Rally story or defect, you cannot configure the connector to synchronize a work item's children or parents, unless you are specifically using stories and tasks.

The connector provides five services to synchronize objects between Rally and TFS:

  • Copy work items created in TFS to Rally (defects, user stories, or test cases only)
  • Copy work items created in Rally (defects, user stories, tasks, or test cases only) to TFS work items
  • Update Rally work items based on changes made in TFS
  • Update TFS work items based on changes made to Rally work items
  • Update Rally fields and TFS fields (may not be used in conjunction with the other update services)

The configuration file specifies which services to run, and in what order.

An alternative update service, UPDATE_RALLYFIELDS_AND_OTHER, searches Rally first for updates and pushes only the recently changed fields to the other system. It then searches the other system for updates and pushes all mapped fields in to Rally.

This makes the chances of overwrites of data highly unlikely. The only scenario where an overwrite might occur is if Peter made changes in Rally and Al made changes in the other system for the same fields, the Rally information is copied over to the other system (possibly overwriting the data of the other system), then all data is copied over to the Rally system.

It is important to recognize that the data models of Rally and TFS are not identical. The data models of the two connected systems are only partially compatible. We recommend that you take some time to identify the key data items that you want to track in both systems and what you want the policy to be as far as having a primary system of record. You'll see specific information later in this document discussing things to be considered and some potential approaches.

Known limitations

  • Attachments are not supported by this connector
  • There are no RTF (rich text field) field handlers
  • Tasks can be copied from Rally to TFS (but not in the opposite direction)
  • Tasks can be updated from Rally to TFS or from TFS to Rally

Basic installation steps

  1. Download the installer .zip file from the Download the connector section. This .zip file contains an installer for the connector and the TFSBridge:
    • RallyConnectorforTFS201xWorkItemsInstall-x.x.x-master-yyy.zip
  2. Extract the contents of the .zip file in to a temporary folder.
  3. Run the TFS connector installer (RallyConnectorforTFS201xWorkItemsInstall-x.x.x-master-yyy.exe).
  4. Make the appropriate configuration changes in Rally and the TFS system.
  5. Edit the tfs_config.xml to reflect your environment.
  6. Run rally2_tfs_connector to start the synchronization process.

This installation and user guide includes:

System setup

The following people should be involved in getting fields set up in both Rally and TFS:

  • A TFS administrator user who can create a custom field on the work items you want to synchronize with Rally
  • A Rally administrator user who can create a custom field on the Rally artifact you want to synchronize with TFS (this is only for initial setup; user access is all that's needed to run the connector).
  • Someone with access to the Windows machine described above to install and configure the connector

Consider the process you want to set up between Rally and TFS:

  • Where do objects start and end their lifecycle?
  • Which fields need to be updated?

You will also need to:

  • Identify a test project in TFS to use for testing the connector.
  • Identify a test Rally workspace or project to use for testing the connector.
  • Find a Windows machine to run the Rally connector.

Software and hardware requirements

  • A Rally subscription.
  • A Windows computer to run the connector (both 32-bit and 64-bit Windows versions are supported).
  • For TFS 2010 only (i.e. does not support 2012):
    • Microsoft .NET Framework 4 installed (for the installer to run)
    • Microsoft Visual Studio 2010 installed (for the connector to function)
    • A working instance of TFS 2010
  • For TFS 2012 only (i.e. does not support 2010):
    • Microsoft .NET Framework 4.5 installed (for the installer to run)
    • Microsoft Visual Studio 2012 installed (for the connector to function)
    • A working instance of TFS 2012

Pre-installation checklist

  • Access to test projects in Rally and TFS.
  • A Rally account with administrator privileges is needed for setup (but only user access is needed to run the connector).
  • Proxy server details if the machine used to run the connector uses a proxy server to connect to Rally or TFS.
  • A TFS user with at least team project contributor (access, read, and write work items) permissions. A user with team project reader permissions is not sufficient to run the connector.

Before installing

If you are installing the connector on a computer that has a previous version of the connector installed, you need to uninstall Rally TFS Work Item Bridge and Rally Connector for TFS Work Items version, in that order. Go to:

  • WinXP: Control Panel → Add/Remove Programs
  • Win7: Control Panel → Programs → Programs and Features

Download the connector

See Rally Integrations FAQ and Best Practices for useful information.

Install the connector

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

  1. On Windows, right-click My Computer and select Properties.
  2. Select the Advanced tab, and then click Environment Variables.
  3. Click New under System Variables and enter http_proxy as the full HTTP URL, such as http://www-cache:8000.
  4. If your proxy sever requires username-password authentication, you could specify it in the http_proxy variable as such: http://Username:Password@www-cache:8000.
  5. You may need to restart your system in order for the change to take effect.

Installation for Windows

Double-click the RallyConnectorforTFS201xWorkItemsInstall-x.x.x-master-yyy.exe to open the install wizard. Follow the prompts to complete the installation.

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

  • rally2_tfs_connector.exe: Executable to run the connector
  • TFSBridge.dll component
  • tfs_config.xml: Sample configuration file
  • WinTail.exe*: Utility to tail the log file output for debugging purposes
  • starttfs.bat: Batch file that automatically runs the connector and shows the log file; useful for testing

*WinTail is a free text file tail utility for Windows, generously made available by Bare Metal Software Pty Ltd. for redistribution without restriction. We have found it to be far superior to Notepad and other text editors for watching log files in real time as they are updated by the connector.

TFS setup

Create a custom field in TFS to contain Rally object IDs

There are two options for creating the custom fields in TFS:

Use Visual Studio Power Tools for witadmin

Download the appropriate version of Team Foundation Server Power Tools


Using Power Tools to add a custom field for the Rally ID:

  1. Open Visual Studio.
  2. Go to Tools → Process Editor → Work Item Types → Open WIT from Server
  3. Connect to the appropriate team project collection.
  4. Select Work Item Type.
  5. Click New in Toolbar.
  6. Add Name ExternalID (this can also be RallyID).
  7. Ensure Type is a string.
  8. Add the Reference Name as Rally.Common.ExternalId.
    Note: This name must be used in the configuration file as the <ExternalIDField> in the <TFSConnection> element.
  9. File → Save to upload the change back to the server.

TFS command line using witadmin

You may need to contact your TFS administrator to perform these steps:

  1. On your Windows system, go to Start → Run to open a Command Prompt window.
  2. Enter cmd and click OK.
  3. Add the path to your TFS Command Line Tools to your PATH environment variable by entering in the following into your Command Prompt window (replacing the path if yours is different):
    set  path=%path%;C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE
  4. Export the XML definition of the work item type in TFS that you wish to associate with Rally work items. For example, to export the XML definition for a bug, where <collection> and <project> are the names of your team project collection and team project, into a file named MyBugDef.xml, enter the following command: (this is a one-line command even though it may appear as more due to line wrapping):
    witadmin  exportwitd  /collection:http://<server>:<port>/tfs/<collection>  /p:<project>  /n:bug  /f:MyBugDef.xml
  5. Add a custom field to the work item definition file (MyBugDef.xml in this example). Under the <FIELDS> tag, there are several <FIELD> entries. Add another <FIELD> entry just before the closing </FIELDS> tag. The new entry should look like this:
    <FIELD name="ExternalID" refname="Rally.Common.ExternalId" type="String">
       <HELPTEXT>The objectID of a defect in Rally</HELPTEXT>
    </FIELD>
    The name used for this custom field (Rally.Common.ExternalId) above must exactly match the name used in the <ExternalIDField> in the configuration file (within the <TFSConnection> element).
  6. Recommended: Add this field to the work item form displayed in team explorer. Find the <FORM> tag, and within it find the <Layout> tag, and within that find the <TabGroup> tag. Scroll down to the matching </TabGroup> tag, and just above it, add:
    <Tab Label="Rally">
       <Control FieldName="Rally.Common.ExternalId" Type="FieldControl" Label="Rally Internal ID:" LabelPosition="Left" />
    </Tab>
  7. Validate your modified XML file using the following command, where <collection> and <project> are the names of your team project collection and team project. Note the /v flag at the end of the command. Fix any errors reported:
    witadmin  importwitd  /collection:http://<server>:<port>/tfs/<collection>  /p:<project>  /f:MyBugDef.xml  /v
  8. Import the modified XML file with the following command (this is the same command used above to validate the XML, but without the /v switch):
    witadmin  importwitd  /collection:http://<server>:<port>/tfs/<collection>  /p:<project>  /f:MyBugDef.xml

To create a configuration file for copying TFS tasks to Rally user stories, you must perform the same procedure above (export, edit, validate, import), but instead of using /n:bug /f:MyBugDef.xml, use /n:task /f:MyTaskDef.xml.

For more information on customizing work items in TFS, see Customizing and Managing Work Item Types for TFS 2010 or for TFS 2012 in the MSDN documentation at Microsoft.

Use Power Tools to add a custom field for the Rally ID

  1. Open Visual Studio.
  2. Go to Tools → Process Editor → Work Item Types → Open WIT from Server.
  3. Connect to the appropriate team project collection.
  4. Select Work Item Type.
  5. Click New in Toolbar.
  6. Add Name ExternalID (this can also be RallyID).
  7. Ensure Type is a string.
  8. Add the Reference Name as Rally.Common.ExternalId.

    This name must be used in the configuration file as the <ExternalIDField> in the <TFSConnection> element.

  9. Go to File → Save to upload the change back to the server.

Add a custom field to a TFS artifact

  1. Open Visual Studio
  2. Go to Tools → Process Editor → Work Item Types → Open WIT From Server.
  3. Select the appropriate Team Foundation Server.
  4. Select the appropriate Team Project Collection, then click Connect.
  5. Select the appropriate Team Project .
  6. Select the appropriate Work Item Type, then click OK.
  7. Select Layout.
  8. Select the appropriate Group → Column.
  9. Right-click and select New Control.
  10. Rename the Label field to an appropriate name.
  11. Click within Field Name and search for the reference name set up in Step 8 of Use Power Tools to add a custom field for the Rally ID.
  12. Click Save (Disk image) or File → Save to upload the change back to the server.

Rally setup

Create a custom field in Rally to contain TFS work item IDs

  1. Log into Rally as a workspace or subscription administrator.
  2. Go to Setup → Workspaces & Projects.
  3. Click on the workspace that you wish to map to TFS. This will take you to the detail page for the given workspace.
  4. Click the Fields link in the sidebar and ensure the Work Item type selected is defect (or whatever work item you are mapping).
  5. Click Actions → New Field.
  6. Enter a Name of ExternalID, Display Name of ExternalID (name and display name must match), and type of String. You can choose a different name (such as TfsId) for the custom field in Rally, but the name you choose must conform to these rules:
    • Begin with an uppercase letter
    • Less than 41 characters (40 is the maximum for display name)
    • No underscores, dashes, or spaces
  7. Click Save & Close.

Make note of the name of this field. Once you start using the connector, this will contain the TFS ID of the TFS work item you are mapping between the two systems.

Connector configuration

Edit the configuration file

A sample configuration file, tfs_config.xml, is part of the installation and should be in the root directory of the installation. This is the directory you specified during the wizard-based Windows install (such as C:\Program Files\RallyConnectorforTFSWorkItems). We recommend making a backup copy of the tfs_config.xml in case you need to reference a valid configuration file later.

Edit tfs_config.xml and enter the appropriate values between each begin and end tag.

<Config>
  <RallyConnection>
    <Url>rally1.rallydev.com</Url>
    <WorkspaceName>Workspace Name</WorkspaceName>
    <Projects>
      <Project>Project Name</Project>
    </Projects>
    <User>user@company.com</User>
    <Password>password</Password>
    <ArtifactType>Defect</ArtifactType>
    <ExternalIDField>ExternalID</ExternalIDField>
    <CrosslinkUrlField>TFSLink</CrosslinkUrlField>
     <!--
    <CopySelectors>
        <CopySelector>Field_Name = Value</CopySelector>
    </CopySelectors>
    <UpdateSelectors>
       <UpdateSelector>Field_Name = Value</UpdateSelector>
   </UpdateSelectors>
-->
    <SuppressDeprecationWarning />
       
    <CopySelectors>
                <CopySelector>SyncStoryToTFS = True</CopySelector>
        </CopySelectors>

        <UpdateSelectors>
           <UpdateSelector>State != Closed</UpdateSelector>
        </UpdateSelectors>
  </RallyConnection>

  <TFSConnection>
    <Collection>http://server:port/tfs/collectionname</Collection>
    <TeamProject>team project Name</TeamProject>
    <ArtifactType>Bug</ArtifactType>
    <IDField>System.Id</IDField>
    <ExternalIDField>Rally.Common.ExternalId</ExternalIDField>
    <CrosslinkUrlField>RallyLink</CrosslinkUrlField>

  <!--  <CopySelectors>
     <CopySelector>System.AssignedTo = My User</CopySelector>
   </CopySelectors>
   <UpdateSelectors>
       <UpdateSelector>Field_Name = Value</UpdateSelector>
   </UpdateSelectors>
 -->
  </TFSConnection>

  <Connector>
    <FieldMapping>
      <Field><Rally>Name</Rally>  <Other>System.Title</Other></Field>
      <Field><Rally>Priority</Rally>  <Other>Microsoft.VSTS.Common.Priority</Other></Field>
    </FieldMapping>

    <OtherFieldHandlers>
      <OtherEnumFieldHandler>
        <FieldName>Microsoft.VSTS.Common.Priority</FieldName>
        <Mappings>
          <Field><Rally>Resolve Immediately</Rally> <Other>1</Other></Field>
          <Field><Rally>High Attention</Rally>    <Other>2</Other></Field>
          <Field><Rally>Normal</Rally>      <Other>3</Other></Field>
          <Field><Rally>Low</Rally>     <Other>4</Other></Field>
        </Mappings>
      </OtherEnumFieldHandler>
    </OtherFieldHandlers>
  </Connector>

  <ConnectorRunner>
    <Preview>False</Preview>
    <LogLevel>Debug</LogLevel>
    <Services>UPDATE_RALLY_FIELDS_AND_OTHER</Services>
  </ConnectorRunner>
</Config>

Each major section is surrounded by a tag to delineate that section. In the example above, here is a description of each section:

  • RallyConnection
    Defines the connection information for Rally, including Rally URL, user, password, and so on.
  • TFSConnection
    Defines the connection information for TFS, including TFS Collection URL, project name, artifact type, user, and so on.
  • Connector
    Defines the field mapping between the two systems. Generally, strings should be mapped to strings, integers to integers, and so on. You can get a list of all the fields for a TFS team project collection with the command:
    witadmin listfields /collection:http://<server>:<port>/tfs/<collection_name>
  • ConnectorRunner
    Specifies parameters related to the services the connector is to run and how often to run the services.

Field Mapping

The field mapping section is located between the <Connector> tags in the configuration file and defines what fields map between the two systems.

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

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

When you set up your mapping between the two systems, ensure the fields are compatible between the two systems (an integer field should map to an integer field in the other system, a rich text field should map to a rich text field in the other system).

Otherwise, you might experience situations where information is not created or updated between the two systems and you will see an error in the log file. For example, the connector will post an error for a particular work item if you try to post a string to a custom field of type integer in Rally.

You can add subsequent mappings by appending to this list. For example, this sets up a mapping of:
Rally Name → Headline
Rally Description → Description
Rally Priority → Priority

<Connector>
  <FieldMapping>
    <Field>
      <Rally>Name</Rally>
      <Other>Headline</Other>
    </Field>
    <Field>
      <Rally>Description</Rally>
      <Other>Description</Other>
    </Field>
    <Field>
      <Rally>Priority</Rally>
      <Other>Priority</Other>
    </Field>
  </FieldMapping>
  .... </Connector>

If you are mapping a drop-down value in Rally to the other system, be sure the drop-down values match. Otherwise, the connector will generate an error that the value was not found in the list. If the drop-down values are different between the two systems, see Mapping drop-down values section of the FAQ.

Individual fields may also have a directionality specified, whereby that specific field will be mapped in one direction only. For more information on this feature, see Field Directionality.

Field handlers

Mapping drop-down values
Mapping user names
Mapping reference fields from Rally (like Project, Release, Iteration)

XML tags

Definition of tags in configuration file

Below is a more detailed explanation of each tag section in the configuration file.

 

XML tags in the <RallyConnection> section:

Tag Name Description Sample Values
     
<RallyConnection>
Required
Opening parent tag for this section.  
<Url>
Required
Server used to connect to Rally (excluding the HTTPS prefix, as the connector adds https:// to whatever is specified). sandbox.rallydev.com
rally1.rallydev.com
myRally.mydomain.com
192.168.23.24
<User>
Required
Login name for user to make the Web Services requests to create and update work items in Rally. user@company.com
<Password>
Required
Password associated with the above <User>. Note: The connector will encode this password string and update it in the configuration file as to avoid clear-text passwords being stored. mypassword
<WorkspaceName>
Required
Workspace in Rally you want to copy and update work items. My Workspace
MyWorkspace
<Projects>
Required
Contains a list of project tags. Each tag refers to one Rally project that will be used when finding new Rally work items to copy to the other system. For updating work items from Rally to the other system, all projects in <WorkspaceName> are considered. At least one Rally project must be specified in this tag. <Project>Rally1</Project>
<Project>Rally2</Project>
<ArtifactType>
Required
Type of artifact you want to create and update in Rally. (Defect, defect),
(story, userstory, hierarchicalrequirement),
test case
<ExternalIDField>
Required
Rally custom field of type string (name and display name must be identical) that stores the unique ID for the other system. Refer to the Create a custom field in Rally to contain TFS work item IDs section above. TFSID
<SuppressDeprecationWarning /> Prevents warning messages related to Rally WSAPI version deprecation from being generated in the logfile.  
<CrosslinkUrlField> A Rally custom field (of type String) which will be used to store a hyperlink to the corresponding artifact (bug or story) in TFS. TFSLink
<CopySelectors> Criteria to use when finding new Rally issues to copy to TFS. Multiple criteria are ANDed together. An individual selector specification has the form:
<field><relation><value>,
where:
<field> is the name of a TFS work item field
<relation> is one of =, !=, gt, lt, gte, lte
<value> is a valid value for the <field>.
<CopySelector>Status = Open</CopySelector>
<CopySelector>Priority = Low</CopySelector>
<UpdateSelectors> Criteria to use when finding existing Rally issues to be updated in TFS. Multiple criteria are ANDed together. An individual selector specification has the form:
<field> <relation> <value>
where:
<field> is the name of a TFS work item field
<relation> is either = or !=
<value> is a valid value for the <field>.
<UpdateSelector>Release != alpha</UpdateSelector>
<FieldDefaults> Set a default value for a Rally field. <Field><Name>Rallyfieldname</Name><Default>defaultvalue</Default></Field>
<WorkProductType> The Rally Artifact Type name for the Task WorkProduct. At this time only the value of Story is valid. This limits Tasks copied from Rally to TFS to those Tasks whose WorkProduct is a Story. This tag only relevant when the ArtifactType tag value is Task. Story
<WorkProductExternalField>

The field name in the WorkProductType that holds the value of the corresponding Story in Rally. This tag only relevant when the ArtifactType tag value is Task


TFSId
</RallyConnection>
Required
Closing parent tag for this section.  

Tip: Special characters contained in a Rally workspace or project name, which are markup sensitive, must be escaped as follows:

& ampersand becomes &amp;
> greater than becomes &gt;
< less than becomes &lt;

Example: Research & Development → Research &amp; Development

 

XML tags in the <TFSConnection> section:

Tag Name Description Sample Values
     
<TFSConnection>
Required
Opening parent tag for this section.  
<Collection>
Required
The URL of a team project collection http://tfsserver:8080/tfs/CollectionName
<TeamProject>
Required
The TFS team project containing work items to be associated with Rally work items. Only one team project can be specified. If more than one team project is needed, use multiple configuration files. Test Project
<ArtifactType>
Required
TFS work item type for the work items you want to create and update in TFS. The exact set of default work item types that are available for your team project depends on the process template the team project was created with, along with any custom work item types that may have been imported. User story
Bug
Test case
Task
<IDField> TFS field used to store the unique ID of a work item, defaults to System.Id System.Id
<ExternalIDField>
Required
TFS custom field that stores the unique ID for a Rally work item. See Create a custom field in TFS to contain Rally object IDs. Rally.Common.ExternalId
<ExternalEndUserIDField> A custom user field in TFS of type String used to store the FormattedID of the Rally work item (DExx). See Create an External ID User Field in TFS. Rally.Common.ExternalId
<CrosslinkUrlField> A TFS custom field (of type HTML) used to store a hyperlink to the corresponding artifact (bug or story) in Rally. TFSLink
<CopySelectors> Criteria to use when finding new issues to copy to Rally. An individual selector specification has the form <field> <relation> <value>, where
<field> is the name of a TFS work item field,
<relation> is one of =, !=, gt, lt, gte, lte.
<value> is a valid value for the <field>.
<CopySelector>State = Open</CopySelector>
<UpdateSelectors> Criteria to use when finding existing issues in TFS that should be updated to Rally. An individual selector specification has the form <field> <relation> <value>, where
<field> is the name of a TFS work item field,
<relation> is either = or !=, and
<value> is a valid value for the <field>.
<UpdateSelector>System.CreateDate gte 2011-10-23</UpdateSelector>
<FieldDefaults> Set a default value for a TFS field. <Field><Name>TFSfieldname</Name><Default>defaultvalue</Default></Field>
<ParentType> The TFS Artifact Type name for the Task Parent. At this time only the value of Story is valid. This tag is only needed when the UPDATE_TFS_TO_RALLY service is specified and is only relevant when the ArtifactType tag value is Task. User Story
<ParentExternalField> The field name in the ParentType that holds the value of the corresponding Story in TFS. This tag only relevant when the ArtifactType tag value is Task. TFSId
</TFSConnection>
Required
Closing parent tag for this section.  

 

XML tags in the <Connector> section:

Tag Name Description Sample Values
<Connector>
Required
Opening parent tag for this section.  
<FieldMapping>
Required
Determine what fields map between the two systems. See Field Mapping
<RallyFieldHandlers> (opening tag)  
   <RallyConcatFieldHandler>
      <FieldName>
         Dest-fieldname
      </FieldName>
      <ConcatFields>
         <Field>Src-fieldname1</Field>
         <Field>Src-fieldname2</Field>
         <Field>.....</Field>
      </ConcatFields>
   </RallyConcatFieldHandler>
Using the contents of Dest-fieldname as the initial string, appends each additional Src-fieldnameN to Dest-fieldname, using HTML break tags (<br />) to separate each additional field value.

Some custom field


Description
some other field
.....
   <RallyDateTimeFieldHandler>
      <FieldName>F1</FieldName>
      <DateTimeFormat>S1</...>
   </RallyDateTimeFieldHandler>
Bi-directional.
Rally to Other: Convert the Rally ISO date in field F1 into a date string formatted as specified by the string S1 (as per Ruby's DateTime.strftime function) and store this new date string into the field F1 is mapped to.
Other to Rally: The date string contained in the field which F1 is mapped to, is converted into a Rally ISO date (in accordance with (through Ruby's DateTime.parse) and stored in Rally's F1 field. Note that string S1 is not used in this case.

TestDate
%m-%d-%Y%H:%M:%S
   <RallyEnumFieldHandler>
      ....
   </RallyEnumFieldHandler>
Allows for the mapping of non-alike drop-down values between the two systems. See Map Drop-Down Values.
   <RallyReferenceFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-field
      </ReferencedFieldLookupID>
   </RallyReferenceFieldHandler>
Used to map a field from an object.

User,Owner,Tester,...


Name,FormattedID,...
   <RallyUserEmailFieldHandler>
      <FieldName>Owner</FieldName>
   </RallyUserEmailFieldHandler>
Rally user to whom error and warning info will be emailed.
User,Owner,Tester,...
   <RallyUserFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <ReferencedFieldLookupID>
         name-of-field
      </ReferencedFieldLookupID>
   </RallyUserFieldHandler>
Used to map user names. See Map User Names.

User,Owner,Tester,...


Name,FormattedID,...
   <RallyCSVUserMappingFieldHandler>
      <FieldName>
         name-of-field
      </FieldName>
      <FileName>
         name-of-file
      </FileName>
   </RallyCSVUserMappingFieldHandler>
Specifies the name of a field being mapped (name-of-field) and a CSV file where user mappings are stored (name-of-file). The CSV file is used to lookup and transform usernames based on the mappings specified within. See a more detailed explanation on the FAQ page or an example XML file.

SubmittedBy


MyUserMappings.csv
</RallyFieldHandlers> (closing tag)  
<OtherFieldHandlers>
    <OtherEnumFieldHandler>
Allows you to map drop-down values for a field between systems. See Map Drop-Down Values.
<RelatedObjectLinkers>                 <TFSTaskToParentLinker />                 <RallyTaskToWorkProductLinker />
</RelatedObjectLinkers>
This is only relevant within a configuration for the Task artifact type.
</Connector>
Required
Closing parent tag for this section.  

 

XML tags in the <ConnectorRunner> section:

Tag Name Description Sample Values
     
<ConnectorRunner>
Required
Opening parent tag for this section.  
<Preview> Allows you to enable a preview mode for testing where NO objects are copied and updated in either system. false (default)
true
<LogLevel> Determines what type of messages are written to the log file. The highest level is Debug where all messages are displayed. The default log level is Info. Fatal, Error, Warn, Info, Debug
<Services>
Required

Use the copy services to initially reflect items between systems, then use the update services to keep those reflected items up to date.

The alternative update service searches Rally first for updates and pushes only the recently changed fields to the other system. It then searches the other system for updates and pushes all mapped fields into Rally. This allows changes done in both systems to not cause overwrites of old data.

Copy services:

COPY_JIRA_TO_RALLY
COPY_RALLY_TO_JIRA

Update services:

UPDATE_JIRA_TO_RALLY
UPDATE_RALLY_TO_JIRA

Alternative update service:

UPDATE_RALLYFIELDS_AND_OTHER (may not be used in conjunction with the other update services)

See FAQ for more information.

<Emailer>
   <Level>value</Level>
   <SendEmailFrom>value</SendEmailFrom>
   <SendEmailTo>value</SendEmailTo>
   <SMTPServer>value</SMTPServer>
   <SMTPPort>value</SMTPPort>
   <SMTPUser>value</SMTPUser>
   <SMTPPassword>value</SMTPPassword>
   <SMTPSec>value</SMTPSec>
</Emailer>
Opening tag for this feature.
Which logfile messages to email.








Closing tag for this feature.
See example.
Error or Warning
monitor@acme.com
monitor@acme.com
smtp.acme.com
587
Username@Domain.com
Password
TLS
 
</ConnectorRunner>
Required
Closing parent tag for this section.  

 

Incrementally set up the connector!

Start with a basic configuration file, test that you can connect to TFS and Rally in a test environment. Once you validate this is set up correctly, then start customizing the field mapping and field handler sections.

Run the connector

Once the tfs_config.xml configuration file is set up, you can start running the connector. On Windows, assuming you used the installer wizard, you can open a DOS shell and enter this command to start the connector:

  rally2_tfs_connector.exe  tfs_config.xml

Next, double-click on WinTail.exe to run WinTail. In WinTail, open the file rallylog.log to watch the log messages generated by the connector. This is an easy way to confirm that the connector is working properly, or to discover any errors.

Use starttfs.bat

We ship a starttfs.bat file to make it easier to test. Double-click on the batch file to automatically run the connector and open the log file in WinTail.

Optionally, you can add a number to the end of the command line that specifies the time in minutes the connector should sleep between successive executions of all services. The default is 15 minutes. We recommend sleep intervals of no less than 10 minutes. For example:

  rally2_tfs_connector.exe  tfs_config.xml  10

To stop the service, use Control-C in the command shell.

Multiple configuration files

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

To run multiple instances of the connector for different configuration files, pass in the list of config files as arguments to the rally2_tfs_connector.rb script or rally2_tfs_connector.exe.

  rally2_tfs_connector.exe  config_workspaceA.xml  config_workspaceB.xml

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.

  rally2_tfs_connector.exe  config_workspaceA.xml  config_workspaceB.xml  10

We recommend a sleep value of 10 minutes or more and advise against anything less.

Copy story-task bundles from Rally to TFS

You can set up the connector to copy Rally stories and their associated tasks to stories and tasks in TFS while preserving the story-task relationships in TFS. In order to do this, you will need two configuration files, one for story and one for task, then you need to run the connector to operate using these configuration files in that sequence.

Example:

rally2_tfs_connector.exe tfs_story_config.xml tfs_task_config.xml

If the following statements are true, this section of the guide does not apply to you:

  • You are not copying Rally tasks to TFS tasks.
  • You do not require that the tasks in TFS be linked to your TFS stories.
  • You are only copying Rally tasks to TFS tasks and not copying Rally stories to TFS stories.

Create configuration files

Create a configuration file to work with the Rally story type and the TFS story type. The following is an example for story.

<Config>
  <RallyConnection>
    <Url>rally1.rallydev.com</Url>
    <WorkspaceName>Workspace Name</WorkspaceName>
    <Projects>
      <Project>Project Name</Project>
    </Projects>
    <User>user@company.com</User>
    <Password>password</Password>
    <ArtifactType>Story</ArtifactType>
    <ExternalIDField>TFSId</ExternalIDField>
    <CrosslinkUrlField>TFSLink</CrosslinkUrlField>
  </RallyConnection>
  <TFSConnection>
    <Collection>http://server:port/tfs/collectionname</Collection>
    <TeamProject>team project Name</TeamProject>
    <ArtifactType>User Story</ArtifactType>
    <IDField>System.Id</IDField>
    <ExternalIDField>Rally.Common.ExternalId</ExternalIDField>
    <CrosslinkUrlField>RallyLink</CrosslinkUrlField>

  </TFSConnection>
  <Connector>
    <FieldMapping>
      <Field><Rally>Name</Rally>  <Other>System.Title</Other></Field>
      … other fields ...
    </FieldMapping>
   … any field handlers you need for mapped fields goes here ...
  </Connector>
  <ConnectorRunner>
    <Preview>False</Preview>
    <LogLevel>Info</LogLevel>
    <Services>COPY_RALLY_TO_TFS</Services>
  </ConnectorRunner>
</Config>  

Task example:

  <Config>
  <RallyConnection>
    <Url>rally1.rallydev.com</Url>
    <WorkspaceName>Workspace Name</WorkspaceName>
    <Projects>
      <Project>Project Name</Project>
    </Projects>
    <User>user@company.com</User>
    <Password>password</Password>
    <ArtifactType>Task</ArtifactType>
    <ExternalIDField>TFSTaskID</ExternalIDField>
    <CrosslinkUrlField>TFSLink</CrosslinkUrlField>
    <WorkProductType>Story</WorkProductType>
    <WorkProductExternalIDField>TFSId</WorkProductExternalIDField>
  </RallyConnection>
  <TFSConnection>
    <Collection>http://server:port/tfs/collectionname</Collection>
    <TeamProject>team project Name</TeamProject>
    <ArtifactType>Task</ArtifactType>
    <IDField>System.Id</IDField>
    <ExternalIDField>Rally.Common.ExternalId</ExternalIDField>
    <CrosslinkUrlField>RallyLink</CrosslinkUrlField>
   <!--  only needed when the UPDATE_TFS_TO_RALLY service is specified
    <ParentType>User Story</ParentType>
    <ParentExternalIDField>Rally.Common.ExternalId</ParentExternalIDField>
  -->
  </TFSConnection>
  <Connector>
    <FieldMapping>
      <Field><Rally>Name</Rally>  <Other>System.Title</Other></Field>
      … other fields ...
    </FieldMapping>
   … any field handlers you need for mapped fields goes here …
   <RelatedObjectLinkers>
       <TFSTaskToParentLinker/>
      <RallyTaskToWorkProductLinker/>
   </RelatedObjectLinkers>
  </Connector>
  <ConnectorRunner>
    <Preview>False</Preview>
    <LogLevel>Info</LogLevel>
    <Services>COPY_RALLY_TO_TFS</Services>
  </ConnectorRunner>
</Config>    

You need to set up a custom field in Rally for the task that will hold the identity of the corresponding item in TFS after it has been copied, also called the ExternalIdField. Adding this custom field in Rally for the task type is similar to the directions in Rally Setup.

Note that in your configuration for task you need to have two additional tags in the RallyConnection section.

The WorkProductType tag value identifies the type the Rally WorkProduct that must be associated with the task in order for it to be copied to TFS. At this time only the story type is supported.

The WorkProductExternalIdField tag value is the name of the WorkProduct type field that holds the identity of the corresponding WorkProduct type in TFS. Normally, you would use the value from the <ExternalIdField> tag in your story configuration file. For the example configuration files in this section, the tag value for WorkProductExternalIdField is TFSId.

The Rally stories must be copied over to TFS first so that this first part of the story-task relationship is reflected on both sides of the connection. Then when the connector is run with the task configuration, the tasks can be linked to their associated stories in TFS.

You must have both configuration files in the same directory and you should run the connector naming the story configuration file on the command line first, followed by the name of the task configuration file to ensure this sequence of operation.

Example:

rally2_tfs_connector.exe  tfs_story_config.xml tfs_task_config.xml

The connector runs using the story configuration and copies the Rally story to a corresponding TFS story. 

The connector runs using the task configuration and copies the Rally tasks to corresponding tasks in TFS.

After the task is copied, the connector sets the links on the newly copied TFS tasks to have them parented by their associated TFS story.

Update stories and tasks

Over time, you may want to reflect any changes in TFS stories and tasks to Rally stories and tasks (and vice-versa).

In order reflect changes from Rally to TFS, your configuration will need to specify the following:

  • The WorkProductType and WorkProductExternalIdField in the RallyConnection section:
    <WorkProductType>Story<WorkProductType>
    <WorkProductExternalIdField>TFSId<WorkProductExternalIdField>
  • The relevant services as in the following example configuration file fragment:  <Services>UPDATE_TFS_TO_RALLY, UPDATE_RALLY_TO_TFS, COPY_RALLY_TO_TFS</Services>

In order to reflect changes from TFS to Rally, your configuration will need to specify the following:

  • The ParentType and ParentExternalIDField in the TFSConnection section:
    <ParentType>Story</ParentType>
    <ParentExternalIDField>RallyID</ParentExternalIDField>
  • The relevant services as in the following example configuration file fragment:
    <Services>UPDATE_TFS_TO_RALLY, COPY_RALLY_TO_TFS</Services>

For the scenario where you are tasking out stories and tasks in Rally and then copying them to TFS, where your developers and testers work on the tasks and provide updates that you then want reflected back in Rally, you will need to adjust your Services specification in the configuration file to:

<Services>UPDATE_TFS_TO_RALLY, UPDATE_RALLY_TO_TFS, COPY_RALLY_TO_TFS</Services>

You will also need the relevant XML tags as discussed in the RallyConnection and the TFSConnection sections.

Troubleshoot the connector

  • The connector logfile:

    Once the connector is running, all errors are written to a log file in the working directory where the rally2_tfs_connector.exe was invoked. Informational messages, warnings, and errors are written to the log file depending on the value of the <LogLevel> tag in the <ConnectorRunner> section of the configuration file.

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

  • Order of operations: Before the connector starts synchronizing objects between the two systems, it performs the following steps:
    • Connecting to the TFS server is successful
    • Connecting to Rally is successful
    • Fields in the field mapping exist in Rally and in the TFS system
    • Ensures that each field handler has a corresponding field mapping section in the configuration file

  • Using preview mode:

    To make a test run of the connector (for example, without moving artifacts between the two systems), set the <Preview> tag in the configuration file to true. Use this technique to experiment with different configuration options to gain confidence or to debug a specific issue.

  • Using Reference Name: When creating the custom field for the <ExternalIDField> in the <TFSConnection> section of the configuration file, be sure to use the Reference Name as opposed to the Name field. If the name field used, it will generate an error as follows:
      INFO : Connector.copy_to_rally - Copy to Rally
     DEBUG : Connector.block in map_fields_to_rally -   Mapping System.Title(T1) - to - Name(T1)
      WARN : TFSConnection.initialize - Unable to obtain TFSEntity field value for: Rally.Common.RallyID
      WARN : ConnectorRunner.exception - Message Unable to obtain TFSEntity field value for: Rally.Common.RallyID

  • Contact support for help:

    If you cannot determine the root cause of an issue, please email the entire log file and configuration file to Rally Support at support@rallydev.com

  • Mapping Rally projects:

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

Known issues

  • Mapping releases or iterations with multiple projects: If you are using a <RallyReferenceHandler> to map releases or iterations with the same name in multiple projects, you may receive an error if the release or iteration you are updating on the defect references a different project than the given defect is assigned. The connector only returns the first release or iteration with the matching name in Rally so it could have a reference to a release or iteration in a different project.
  • User name mapping through MiddleName: Using the MiddleName feature for user name mapping does not work. A work-around is to use the <OtherEnumFieldHandler> instead.

Revision history

  • 4.3.0-master-8 Jan-2014
    • Enhancements
      • Upgrade from Ruby 1.9.2-p290 to Ruby 2.0.0-p247.
      • Performance improvement gained by using rally_api rather than rally_rest_api.
      • Added more build tests.
      • Connector would validate only the first config file on command line (DE17492).
      • Added <SuppressDeprecationWarning&nbsp;/> XML tag.
      • Added support for TFS 2012.
      • Support for Task Items.
      • Upgrade to version 1.42 of the WSAPI.

Note: For the 4.3.0 version of this connector, any custom code (i.e. a custom field handler) will require modifications. A working example can be found here (you must be logged into the Rally Support Community to view).
  • 4.0.2-master-520 Dec-2013
    • Enhancements
      • Support for task/story linking on items copied from Rally to TFS (and subsequent updates)
    • Known issues
      • None
  • 2.10.0-master-6 - 07-Oct-2013
    • Enhancements:
      • Support for TFS2012
    • Known issues:
      • (none)

  • 2.8.9-master-2 - 20-May-2013
    • Enhancements:
      • Support for TFS2012
    • Known issues:
      • (none)

  • 2.8.6-144 - 17-Oct-2012
    • Enhancements/Fixes:
      • Added artifact ID to message string
      • Added more debug output in Rally connection section
      • Improved performance by removing refresh on workspace read in find-workspace loop
      • Updated to rally_api 0.6.0 gem
    • Known issues:
      • The version of this connector is erroneously reported as 2.7.7

  • 2.7.4-129 - 13-May-2012
    • Enhancements/Fixes:
      • Added ability for FormattedID in TFS system to have lower or lower case prefix (us/US)
      • Added subfield specifications on CopySelectors from Rally using the precopy feature
      • Added XML include capability so common text can be included as a separate file
      • Installer now has both the TFS Connector and TFS Bridge in the same installer package
      • Added project path Field Handler
English

Feedback

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