TFS VCS Installation Guide

Document ID : KB000057558
Last Modified Date : 14/02/2018
Show Technical Document Details


The VCS TFS (Microsoft Team Foundation Server) to Rally Connector helps you show traceability of code changes to artifacts in Rally.

  1. Basic Workflow / Overview
  2. Supported Platforms
  3. Download the Connector
  4. Prerequisites
  5. Install the Connector
  6. Rally Configuration
  7. Connector Configuration
  8. Running the Connector
  9. Extending the Connector

1. Basic Workflow / Overview

The VCS TFS to Rally connector comprises code that skims a centralized-master TFS repository for recent commits. It extracts information from the commit messages, and posts?Changeset?/?Change?information to a?Rally SCMRepository, according to specifications in a configuration file. The connector needs to be installed on only one computer for your company.

Developers can put FormattedIDs, for example US42, in their commit messages and the connector will process all commits for configured repositories and will push information about those commits into?Changeset objects?and?Change objects?in Rally. If a valid FormattedID is found in a commit message, the Changeset created by the connector will be associated with that Defect, Story or Task in Rally.

A typical workflow would be for one of your team members to be assigned DE42 in Rally. When they make a code change and commit it. They would include text in the commit message like "Found an issue with line breaks - fixed DE42". When the connector runs again, it will find that commit message and link the information about the commit to Rally Defect DE42.

2. Supported Platforms

This software is written in Ruby and has been tested using Ruby 1.9.2-p290, but should also work with Ruby 1.9.3. We would expect the connector work with subsequent "stable" versions of Ruby.

You can only run the connector in Microsoft Windows as a packaged executable.

3. Download the Connector

4. Prerequisites

  • The connector runs on a Windows platform only
  • TFS Collection Name, Team Project, Project, Version
  • TFS Protocol, Server, Port, TFS Virtual Path
  • The Rally Workspace into which the Changeset/Change information will be posted
  • Visual Studio Ultimate, Premium, Professional, Express or Team Explorer (the later requires a modification to the PATH to include the location of?tf.exe)

5. Install the Connector

Installer vs. operator filesystem permissions

As this connector is intended to run on an ongoing basis initiated by Windows Task Scheduler (WTS), it is important to consider the identity of the user who installs the connector versus the identity of the user when run via WTS with regard to the permissioning / ACL of the directories and files in the connector installation. The runner of the connector must be able to read all files and must be able to write in the?configs?and?logs?subdirectories.

Distribution contents

Archive:  Length     Date   Time    Name --------    ----   ----    ----  3743709  11-18-13 14:31   TFSConnectorforRallyInstall-1.2.0-cib15.exe --------                   -------  3743709                   1 file

6. Rally Configuration

Verify that your target?WorkspaceConfiguration object?has BuildandChangsetEnabled set to true.

Your Rally Workspace administrator needs to enable this for your target Workspace. If it is not enabled, the connector will work, but you won't be able to see any of the Changeset/Change information that is associated with your Rally work items (Story, Defect, Task, etc).

Procedure: The Workspace administrator must edit the workspace and perform these steps:

  1. click on?Setup. (near top right of screen)
  2. click on the?Workspaces & Projects?tab
  3. find the desired Workspace in the list and click on it
  4. click on?Actions?(near top right) and select?Edit...
  5. scroll down and check the box labeled?Enable Build and Changeset:
  6. click on?Save & Close?(at the bottom of window)


7. Connector Configuration

The VCS-TFS connector is control by 3 different files:

  1. The repository configuration file
    Each repository under VCS-TFS control must have a configuration file which resides in the?configs?subdirectory. This configuration file describes the repository and all its attributes. The file must be in?YAML?format.?

    There is an example configuration file, shipped with the product, named?sample.yml. Make a copy of the?sample.yml?file in the?configs?subdirectory and use it for your repository. We suggestion naming your YAML configuration file similar to your repository name. For instance, if your repository name is My-Tfs-Repo, then name your YAML configuration file?My-Tfs-Repo.yml?(for simplicity). Edit your new repository configuration file and modify the values to fit your environment.?

    Warnings about YAML syntax:
    • The "tab" character is not a valid YAML character.
    • Enclose special characters in quotes, such as if the password has exclamation marks ("!") or hashes ("#").
    • The comment character "#" must be separated from any previous element by at least one space (i.e. this string: ".../dir/dir2#this is a comment", is invalid).

    Within the "Rally:" section of your YAML configuration file, the value for "RepositoryName:" is the name of the Rally?SCMRepository?to which Changeset/Change items will be associated. If this SCMRepository container does not exist, the connector will create it in the user's target workspace.?

    There is an optional "Lookback:" variable which can appear on either (or both) of the "Rally:" and "TFS:" sections. By default, the value for this parameter is assumed to be in minutes. You may use other units of time by specifying a suffix character of "m" (minutes) or "h" (hours) or "d" (days). Examples:

    If you do not explicitly provide a "Lookback:" value, the connector uses a default value of 1 hour. If you do specify a "Lookback:" value in one section, we highly recommend specifying the value for it in the other section. If the "Lookback:" values are not identical in the two sections, there is the possibility that a changeset from TFS would not be reflected in Rally.?

    Example repository configuration file:

    # The content of the file below should follow YAML specifications
    # Non standard characters should be enclosed?with?double quotations
    # Legend:?(R)=required,?(O)=optional

    # Parameters?for?Rally Server
    ? ? Server ? ? ? ? ? ? ?:?""??#?(R)
    ? ? Protocol ? ? ? ? ? ?:?https ? ? ? ? ? ? ? ? #?(R)?https?(SaaS),?https/http?(On-Premises)
    ? ? Username ? ? ? ? ? ?:?""?? ?#?(R)
    ? ? Password ? ? ? ? ? ?:?"BigS3Krates"?? ? ? ? #?(R)?encoded after first?use
    ? ? Workspace ? ? ? ? ??:?"Target Workspace"?? ?#?(R)
    ? ? RepositoryName ? ? ?:?"CodeTank"?? ? ? ? ? ?#?(R)
    # ? Proxy ? ? ? ? ? ? ??:?"server:port"?? ? ? ? #?(O)
    # ? ProxyUser ? ? ? ? ??:?"Proxy User"?? ? ? ? ?#?(O)?for?an authenticating proxy
    # ? ProxyPassword ? ? ??:?"Proxy Password"?? ? ?#?(O)?for?an authenticating proxy
    ? ? Lookback ? ? ? ? ? ?:?90?? ? ? ? ? ? ? ? ? ?#?(O)?60?minutes?(default)
    ? ? UpdateArtifactState?:?False?? ? ? ? ? ? ? ? #?(O)?False?(default)
    ? ? StateExtractorClass?:?BasicActionsAndArtifactsExtractor(message)??#?(O)?only used?if?above?is?True
    ? ? Debug ? ? ? ? ? ? ??:?False?? ? ? ? ? ? ? ? #?(O)?False?(default)

    # Parameters?for?Microsoft Team Foundation Server
    ? ? Server ? ? ? ? ? ? ?:?"localhost"?? ? ? ? ? #?(O)?fully qualified domain?name,?ip address,?or localhost(default)
    ? ? Port ? ? ? ? ? ? ? ?:?8080?? ? ? ? ? ? ? ? ?#?(O)?8080?(default)
    ? ? Protocol ? ? ? ? ? ?:?http ? ? ? ? ? ? ? ? ?#?(O)?http?(default)?or https
    ? ? TfsServerVersion ? ?:?2012?? ? ? ? ? ? ? ? ?#?(O)?2010?or?2012?(default)
    ? ? TfsVirtualPath ? ? ?:?tfs ? ? ? ? ? ? ? ? ? #?(O)?tfs?(default)
    ? ? CollectionName ? ? ?:?"Collection Name"?? ? #?(R)
    ? ? TeamProject ? ? ? ??:?"Team Project"?? ? ? ?#?(R)
    ? ? Project ? ? ? ? ? ??:?"Project"?? ? ? ? ? ? #?(R)
    ? ? Lookback ? ? ? ? ? ?:?90?? ? ? ? ? ? ? ? ? ?#?(O)?90?minutes?(default)
    ? ? MaxItems ? ? ? ? ? ?:?100?? ? ? ? ? ? ? ? ? #?(R)?max items to process?in?a run,?1000?(default)

    # Parameters?for?Microsoft Team Foundation Server
    ? ? Preview ? ? ? ? ? ??:?True?? ? ? ? ? ? ? ? ?#?(O)?True?or?False?(default)
    ? ? LogLevel ? ? ? ? ? ?:?Debug ? ? ? ? ? ? ? ? #?(O)?Info?(default)
    # ? PostBatchExtension ?:?MetricsPoster ? ? ? ? #?(O)?future?use

    # Mapping TFS username to a Rally username?-?choose one from the?6?below
    # ? Author ? ? ? ? ? ? ?:?Passthru ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?#?(O)?Passthru?(default)
    # ? Author ? ? ? ? ? ? ?:?EmailAddressAsRallyUser ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? #?(O)
    # ? Author ? ? ? ? ? ? ?:?FileBasedUserNameLookup(user_map.txt,?":")?? ? ? ? ? ? ? ? ?#?(O)
    # ? Author ? ? ? ? ? ? ?:?RallyUserNameLookup(FirstName,?LastName)?? ? ? ? ? ? ? ? ? ?#?(O)
    # ? Author ? ? ? ? ? ? ?:?UserNameDomainAugmentLookup(DomainName)?? ? ? ? ? ? ? ? ? ? #?(O)
    # ? Author ? ? ? ? ? ? ?:?UserLookupChainGang(FirstName,?LastName,?user_map.txt,?":")?#?(O)

    Notes about the above configuration file:

    • Proxy
      The three "Proxy..." items are commented out by using a?"#"?in front of the item. Within a YAML file, any line beginning with a?"#"character is ignore and any content following a?"?#"?character sequence is ignored (including the?"?#"?sequence).
    • Syntax warnings
      • The "tab" character is not a valid YAML character.
      • Enclose special characters in quotes, such as if the password has exclamation marks ("!") or hashes ("#").
      • The comment character "#" must be separated from any previous element by at least one space (i.e. this string: ".../dir/dir2#this is a comment", is invalid).
  2. The user mapping file
    The file?configs/user_map.txt?determines how user names are translated between your TFS system and your Rally subscription. If the user names are universally identical in both systems, then you can either comment out all Author subitems underneath the Transforms section or you can set the value for the Author field in the Transforms section to 'Passthru'. If, on the other hand, there is a deterministic mapping that can transform a TFS user name to a Rally user name, you'll need to adjust the transformation value for Author to the appropriate classname. Consult the?User-Mapping-Strategies?text document (part of the installaton) to determine which technique fits your particular situation.

    Once you've identified a suitable Author transformation technique, you'll need to edit the configuration to identify the Ruby class name that will implement that transformation. The Ruby class name must exist in a file of Ruby source code that is in a file in the?plugin?subdirectory.

    Example user_map.txt file:
    # TFS repo username ? ? ? Rally username
    jpkole ? ? ? ? ? ? ? ? ?:?
    user1 ? ? ? ? ? ? ? ? ??:?
    user2 ? ? ? ? ? ? ? ? ??:?
  3. The repository time file
    Each time the connector finishes running, it will update a repository time file in the base installation directory, which has a name like "My-Tfs-Repo_time.file". This file contains the date of the last TFS commit processed by the connector. Therefore, when the connector runs again, it knows where (i.e. at what time in the past) to begin processing commits made by the user.?

    On the first invocation of the connector, there is no time file, so the connector will look back 72 hours into the past for commits.?

    The user may edit this file (using their favorite editor) and set the time to whatever value they desire. For instance, if you have 50,000 checkins which were performed over the previous 5 years, you may not want all of that past history reflected in Rally. In that case, one would edit this time file and enter a date of last week (or what ever starting point they desired).?

    The file contains only one line, and it is a time stamp (in GMT/UTC time). The general format of the file is "YYYY-mm-dd HH:MM:SS Z" (where the "Z" is for "Zulu" or GMT/UTC time). Following are the contents of a typical time file:

8. Running the Connector

  1. Preview mode
    Within the 'Services' section of your configuration file ("configs/repo_one.yml" for example), is an entry for 'Preview' that is set to 'False'. You may want to set this value to 'True' in the initial setup phase to ensure the connector can successfully connect to Rally with the credentials and information you've provided, as well as proving out the use of the 'tfs' command. Once you've determined that a connector run in Preview mode operates as expected, you can set the Preview value in your configuration to 'False'.
  2. Access to the?tf.exe?command
    Your PATH environment variable must contain a filesystem path where the?tf.exe?command can be found (it may be something like?C:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE\?for a default Visual Studio 2012 installation on a 64-bit system).
  3. Running as a scheduled task
    You can use the Windows Task Scheduler (or any other job/task scheduling software) to run the connector periodically. Initially, Rally recommends the connector to be run every 15 minutes during normal business hours and less frequently during non-business hours.
  4. Command line invocation
    You can have numerous configuration files in the?configs?subdirectory and specify any number of them for invocation. For example:
    cd?"C:\Program Files (x86)\Rally Software\TFSConnectorforRally\tfs2rally-1.0.3"
    tfs2rally.exe??apricot ?banana ?cherry ?dogwood
    In the above example, the files?apricot.yml,?banana.yml,?cherry.yml?and?dogwood.yml?must exist in the?configs?subdirectory of your current working directory. The connector only looks for configuration files in the?configs?subdirectory (which is under the installation base directory).
  5. The log files
    Whenever the connector is run, two different log files, under the current working directory, are updated for each configuration file named:
    1. logs/tfs2rally.log
      An entry is made in this log file to note the connector was invoked. For each configuration named at invocation, there will be an entry in this log file noting the return code from running the configuration. When the connector run has finished with all configurations, an entry is written to note the completion of the connector run.
    2. logs/<ConfigFileName>.log
      For each configuration file named on the command line, this log file will be updated with much more detail about the activity that occurred during the run.
    You can adjust the verbosity written to these log files by modifying the LogLevel value in the YAML configuration file. Normally, the LogLevel would be set to 'Info'. Should you encounter situations where the connector does not complete normally, you can adjust the LogLevel to 'Debug' and run the connector to begin the troubleshooting process. These log files can be sent to Rally Support to expedite the investigation of a case.
  6. The time files
    The connector will write a file in the base installation directory corresponding to the configuration name with the date of the last commit processed. The file is named <configuration-name>_time.file and simply has a time entry in the form 'YYYY-mm-dd HH:MM:SS Z', for?UTC?(or Zulu) time. When first run, there won't be a?time file?for the configuration and the connector defaults to looking for commits that occurred 72 hours prior to the run of the connector. You can override that behavior by creating and editing a?time file?for the configuration file you are about to process. By providing an entry in the format mentioned above, you can control that point from which commits are processed.

9. Extending the Connector

Within the?extension?subdirectory of the installation, there is an example Ruby class in the file named?statex.rb. The class definition contained in that file is named 'BasicActionsAndArtifactsExtractor'. This example class demonstrates the basic technique of examining a commit message and extracting Rally artifact identifiers and state transition target values. Using this class when the configuration file item 'UpdateArtifactState' value is set to True results in the transition of the State (or ScheduleState in the case of UserStory) of the identified artifact to the state value mentioned in the commit message.

For example, if there is a Rally Defect (identified as DE1987) mentioned in the commit message with a new valid state value either immediately preceding or following the artifact identifier, then the connector will change the State of the identified artifact in Rally to that state.

The extension subdirectory allows you to provide your own message processing to extract Rally artifact identifiers and state changes if the example provided does not fit your conventions. Your extension must be a class written in Ruby and must provide an instance method called 'service' which takes the commit message as an argument and must return a Ruby Hash instance with entries keyed by a State name (Fixed, Completed, etc.) or nil with a Ruby Array as the associated value populated by Rally artifact identifiers (FormattedID).