VersionOne Integration for Microsoft TFS

VersionOne's integration for Microsoft Team Foundation Server (TFS) provides visibility into source code changes while freeing the development team to focus on deliverables.

Contents

Description

The integration is comprised of two parts: the TFS Listener and the TFS Policy, and each must be installed and configured separately.

The TFS Listener is a web service that is responsible for responding to check-in and build events from TFS. For each qualifying check-in event the listener creates a "ChangeSet" in VersionOne, providing the team visibility into the code changes for a story or defect. This visibility can be useful when tracking down defects or performing code reviews. For each qualifying build event, the listener creates a "BuildRun" in VersionOne. If possible, BuildRuns are associated with stories and/or defects in VersionOne, providing the organization visibility into build contents. This visibility is useful when selecting a build to release, identifying problem builds, or generating release notes.

In order for the listener to create associations in VersionOne, the check-in comment must include a VersionOne story or defect ID, such as "S-01454" or "D-21054". The TFS Policy ensures that this requirement is met. When this policy is enabled for a TFS project, each comment is scanned for a VersionOne ID. If not found, the policy fails and prompts the user to select an ID from a dialog box. The user may select from items they own in active iterations, or from all items in active iterations.

The following sequence diagram shows the primary workflows of the integration:

title VersionOne Integration for TFS (V1TFS)

Developer->VS: Check In Changes
VS->TFS: Check In Changes
TFS->V1TFS: CheckinEvent
V1TFS->VersionOne: ChangeSet
TFS->TFS: Build Project
TFS->V1TFS: BuildCompletionEvent2
V1TFS->VersionOne: BuildRun

System Requirements

Installation and Configuration

Before using the integration you will need to perform the following actions:

  1. Install and configure the TFS Listener.
  2. Install and enable the TFS Policy.
  3. Enable VersionOne for Build Integration.

Installing the TFS Listener

The VersionOne TFS Listener is a web service that must be installed on a machine that has access to your VersionOne server and your Team Foundation Server. It is recommended that you install the listener on the Team Foundation Server.

To install the listener, execute the VersionOne.Integration.TFS.Listener.Installer.msi on the appropriate machine and follow the steps in the installation wizard. You can verify the listener by navigating to the following URL into your browser:
http://[machine]:[port]/Service.svc

Note: Replace [machine] with the name of the machine hosting the service, and [port] with the TCP port number that you provided in the installer.

For instance, if the machine hosting your TFS Server is called "TFSServer" and you specified port 9090 during the install, your URL would be:
http://tfsserver:9090/Service.svc

If successful, you should see a page similar to the following:


Configuring the TFS Listener

In order for the TFS Listener to work it must know which VersionOne instance to use when creating assets and making associations, and which TFS instance to use for listening to events. Configuring the TFS Listener is accomplished using the TFS Listener Configuration tool. The configuration tool is a separate Windows application that is installed as part of the listener installation. If you need to reconfigure the listener at a later date, the configuration tool is available from the Windows Start menu under Program Files > VersionOne > TFS Listener > VersionOne.Integration.Tfs.Listener.Config.

The configuration tool has 3 tabs:

This tab allows you to configure the regular expression used to match VersionOne IDs in Check-in comments and enable a debug log. This configuration is optional since we set the default value to a working expression. We do not recommend you change this unless necessary.


 

Installing the TFS Policy

The VersionOne Check-in Policy ensures that each TFS Check-in contains a VersionOne identifier. This policy must be installed on each machine running Visual Studio. To install the VersionOne Check-in policy, execute VersionOne.TFSPolicy.Installer.vsix on the client machine.

Enabling the TFS Policy for a Project

In order to be considered when performing a check-in, the VersionOne TFS Check-in policy must be enabled on a TFS project.

Note: The screenshots displayed below depict Visual Studio 2013.  If using Visual Studio 2012 your screen may appear different, but the same actions apply.

Perform the following steps to enable the Check-in policy on a TFS Project:

  1. Open Visual Studio.
  2. Open the Team Explorer - Home.
  3. Click on Settings.
  4. Select "Source Control" from the Team Project List.
  5. Select the "Check-in Policy" tab.
  6. Click "Add".
  7. Select the "VersionOne Policy..."
  8. Click Ok to close the "Add Check-in Policy" dialog.

Enabling VersionOne Build Integration

In order to access TFS Build Runs in VersionOne you must configure the VersionOne application. The following steps describe how to enable Build Integration, create a Build Project, and assign that project to a project that containts stories and defects.

  1. Log into the VersionOne application as administrator.
  2. Navigate to the Administration > Configuration > System page.
  3. Under "Enable Features", check the "Build Integration" checkbox and click the Apply button.
  4. Navigate to the Administration > Projects > Build Projects page.
  5. Click Add to add a new Build Project.
  6. Specify the following:
    • Title: This is how the Build Project will be known to VersionOne users.
    • Reference: This should be the name of the Build Definition of the TFS Team project, and it is how the Build Project will be known to TFS.
    • TFS Build Definition: To find the TFS Team Project Build Definition, view Team Explorer - Home and click on Builds. In the Builds window, you should see the Build Definition of your project under the All Build Definitions section.
  7. Click Ok to save the new Build Project. The new Build Project should no be visible on the Administration > Projects > Build Projects page.
  8. Navigate to the Administration > Projects > Projects page.
  9. Click Edit on the row for the project you want associated with a Build Project.
  10. Using the "Build Projects" dropdown add the appropriate Build Project.
  11. Click OK to accept the changes.
  12. Logout of VersionOne.

Using the Integration

Perform the following steps to use the integration:

  1. Open a Visual Studio project that is in the selected TFS project.
  2. Open a file and make a change (e.g. add a comment).
  3. Save the change.
  4. Go to Team Explorer and select Pending Changes.
  5. You should be presented with the following dialog box:

  6. Provide the VersionOne URL and your credentials.

    You may want to wait until after testing to cache credentials.

  7. Click OK.

    You should now be presented with the following dialog, populated with information from your VersionOne Server:

  8. Select an Item in VersionOne.
  9. Click OK.
  10. The VersionOne work item Id should now appear in the Comment box in Team Explorer - Pending Changes. Check-in your change.

    Once the check-in completes, launch your browser and navigate to VersionOne. Login and locate the item you chose to associate with the check-in. Click on the item to open the details page. You should now see data in the following grids: Changesets and Affected Build Runs.

Troubleshooting Tips

Technology