Microsoft TFS for Work Items Installation & User Guide

1.0 Introduction

The Rally Connector for TFS Work Items allows customers to use Rally for Agile lifecycle management and TFS for managing work items - bugs and user stories, for example. The connector provides synchronization capability between TFS and Rally through four services, described below.

2.0 Overview of features

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 and/or TFS based on a field mapping specified in the configuration file. Standard and custom fields can be mapped between the two systems.

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

• Copy work items created in TFS to Rally work items
• Copy work items created in Rally 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

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

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 some of the trade-offs to be considered and some potential approaches.

3.0 Before installing

Click on the Contact Support link at the bottom of any page in Rally to open a support case to obtain the Rally Connector for TFS Work Items. Once you've received a response and obtained the installation package, proceed with the following tasks.

Reinstallation Note

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

to uninstall Rally TFS Work Item Bridge and Rally Connector for TFS Work Items version ..., in that order.

3.1 Software and hardware requirements

The following are the hardware and software requirements to install and run the Rally Connector for TFS Work Items:

1. A Rally subscription.
2. A Windows computer to run the connector (both 32-bit and 64-bit Windows versions are supported).
3. Microsoft .NET Framework 4 installed (for the installer to run).
4. Microsoft Visual Studio 2010 installed (for the connector to function).
5. A working instance of TFS 2010 or higher.

3.2 Pre-installation checklist

1. Access to test projects in Rally and TFS.
2. Rally administrator privileges are needed for setup but only user access needed to run the connector.
3. Proxy server details if the machine used to run the connector uses a proxy server to connect to Rally or TFS.
4. 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.

4.0 Installation

4.1 Basic installation steps

1. Download the installer ZIP file from the Get TFS Connector for Work Items web page. This ZIP file actually contains two installers:
   • Bldxxx-RallyConnectorforTFSWorkItemsInstall-x.x.x.zip
   • TFSBridgeSetup.zip
2. Extract the contents of the ZIP file (the two installers) into some temporary folder.
3. Run the TFS connector installer (Bldxxx-RallyConnectorforTFSWorkItemsInstall-x.x.x.exe).
4. Then run the TFSBridgeSetup.msi installer which will install a .NET assembly that enables the connector to communicate with a TFS server.
5. Make the appropriate configuration changes in Rally and the TFS system.
6. Edit the tfs_config.xml to reflect your environment.
7. Run rally2_tfs_connector to start the synchronization process.

4.2 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 Bldxxx-RallyConnectorforTFSWorkItemsInstall-x.x.x.exe to bring up 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):

1. rally2_tfs_connector.exe - Executable to run the connector.
2. tfs_config.xml - Sample configuration file.
3. WinTail.exe* - Utility to tail the log file output for debugging purposes.
4. 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.

4.3 Make configuration changes in Rally and TFS

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 on Work Products & Fields and ensure the Work Product 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. Note: 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.

Create a custom field in TFS to contain Rally object IDs

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

1. Open up a Windows Command Prompt window by clicking "Start" --> "Run", then enter "cmd" in the "Open:" box and clicking "OK".


2. 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

3. 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: (the following intended to be 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

4. 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>

   WARNING: The name used for this custom field (Rally.Common.ExternalId above) must exactly match the name used in the <ExternalIDField> in the tfs_config.xml file (within the <TFSConnection> element).


5. You should probably add this field to the work item form displayed in Team Explorer. Find the <FORM> tag, and within it find the <Layout> tag, and finally, within it 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>

6. Validate your modified XML file using the following command, where again, <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

7. 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 the topic Customizing and Managing Work Item Types in the MSDN documentation at Microsoft.

4.4 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.

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, etc.
• 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.

Definition of tags in configuration file

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

Specification of elements contained in the RallyConnection section

<RallyConnection>

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

Specification of elements contained in the TFSConnection section

<TFSConnection>

</TFSConnection>

Specification of elements contained in the Connector section

Specification of elements contained in the ConnectorRunner section

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 and/or update, the connector will only update the Name field in Rally and the Headline field in the TFS system.

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

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 throw an error letting you know the value was not found in the list. If the drop-down values are different between the two systems, see the section called Mapping Drop-Down Values.

Field handlers

4.5 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 simply open a DOS shell and type this command to start the connector:

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.

Using starttfs.bat

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,

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 and/or need to map to multiple containers (such as domain/projects in Quality Center or ClearQuest databases) in the other system, setting up multiple configuration files may make sense. 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.

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.

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

5.1 Troubleshooting the connector

Once the connector is running, all errors are written to a log file in the directory where the rally2_tfs_connector.exe program file resides. Informational messages, warning and errors are written to the log file depending on the value of the <LogLevel> tag in the <ConnectorRunner> section of the config file.

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

Before the connector starts synchronizing objects between the two systems, it performs a validation that confirms that:

1. Connecting to Rally is successful
2. Connecting to the TFS server is successful
3. Fields in the field mapping exist in Rally and in the TFS system
4. Ensures that each field handler has a corresponding field mapping section in the configuration file

To confirm the validation is successful without moving objects between the two systems, ensure you set the <Preview> tag in the configuration file to true. Use this technique to experiment with some different configuration options to gain confidence or to debug a specific issue.

If you still cannot determine the root cause of an issue, then please email the entire log file and config file to Rally Support.

6.0 Tip

• 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.

7.0 Known issues

1. Mapping Release/Iterations with Multiple Projects: If you are using a <RallyReferenceHandler> to map Releases/Iterations with the same name an multiple projects, you may receive an error if the Release/Iteration you are updating on the Defect references a different Project than the given Defect is assigned. The connector only returns the FIRST Release/Iteration with the matching name in Rally so it could have a reference to a Release/Iteration in a different project.