Adding Change Request Cards to a TFS Agile Board

Most teams work in some sort of agile methdology today, and by definition, change requests are something that are welcomed, and have no real special significance in agile when you're running through iterations (or sprints), and making changes based on user feedback. There are some instances, however, where having change requests added to your Kanban board are necessary. For example, in some corporate environments, just because a team is using an agile methodology, doesn't mean that the project doesn't come with a due date. When you have a due date, but the requirements are constantly changing--creating a greater workload--it's important to be able to keep track of these requests, and how they weren't in the original scope.

Microsoft's Team Foundation Server (TFS) has different process templates to choose from, and if you've chosen the agile process template, you're familiar with user stories, tasks, and bugs, and higher level categories like epics and features. There is no card for changes requests. Through the magic of XML, however, we can add it.

The first thing to do is download your current process template. You can also download all process template in Visual Studio. Select Team from the menu. Then select Team Project Collection Settings, and then Process Template. Select whatever templates you want, and then download them. For change requests, download the CMMI process template, and then move the ChangeRequest.xml file to a working folder of your choosing. Also, download the Agile process template.

To be more specific about the files you download from your collection/project, you can use the witadmin command line utility. This utility is found in C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE--basically the IDE folder of your Visual Studio installation.

All components of the TFS process template can be exported and imported from the command line. We'll focus on what you need to get change requests on your TFS Kanban board.

First, since we want change requests in the backlog with other requirements, open the UserStory.xml file from the Agile process template that you downloaded, copy the entire <States> XML block and paste it over the <States> XML block in the ChangeRequest.xml file that is in your working folder. This will prevent conflicts about state when you import the file.

You're also going to want to copy over some of the scheduling XML nodes for user stories. Paste this just above the comment about "Build Integration Fields":

     <FIELD name="Story Points" refname="Microsoft.VSTS.Scheduling.StoryPoints" type="Double" reportable="measure" formula="sum" >
              <HELPTEXT>The size of work estimated for implementing this user story</HELPTEXT>
            </FIELD>
            <FIELD name="Stack Rank" refname="Microsoft.VSTS.Common.StackRank" type="Double" reportable="dimension">
              <HELPTEXT>Work first on items with lower-valued stack rank. Set in triage.</HELPTEXT>
            </FIELD>
            <FIELD name="Start Date" refname="Microsoft.VSTS.Scheduling.StartDate" type="DateTime" reportable="dimension">
              <HELPTEXT>The start date for implementation of this story</HELPTEXT>
            </FIELD>
            <FIELD name="Finish Date" refname="Microsoft.VSTS.Scheduling.FinishDate" type="DateTime" reportable="dimension">
              <HELPTEXT>The completion date for all the tasks implementing this story</HELPTEXT>
           </FIELD>
      

Once done, you should be able to import your new work item definition:

.\witadmin.exe importwitd /collection:http://URL_TO_TFS:PORT/tfs/COLLECTION_NAME /p:PROJECT_NAME /f:"C:\PATH_TO_WORKING_FOLDER\ChangeRequest.xml"
      

Next, export your current Categories.xml file:

.\witadmin.exe exportcategories /collection:http://URL_TO_TFS:PORT/tfs/COLLECTION_NAME /p:PROJECT_NAME /f:"C:\PATH_TO_WORKING_FOLDER\Categories.xml"
      

In the Categories.xml file, edit the Requirements Category to include the new change request:

<CATEGORY name="Requirement Category" refname="Microsoft.RequirementCategory">
          <DEFAULTWORKITEMTYPE name="User Story" />
          <WORKITEMTYPE name="Change Request" />
      </CATEGORY>
      

Now import this file:

.\witadmin.exe importcategories /collection:http://URL_TO_TFS:PORT/tfs/COLLECTION_NAME /p:PROJECT_NAME /f:"C:\PATH_TO_WORKING_FOLDER\Categories.xml"
      

The last change is to edit the process configuration. This will allow you to change the work item color. Otherwise, it'll be blue like user stories.

Download the ProcessConfiguration.xml file:

.\witadmin.exe exportprocessconfig /collection:http://URL_TO_TFS:PORT/tfs/COLLECTION_NAME /p:PROJECT_NAME /f:"C:\PATH_TO_WORKING_FOLDER\ProcessConfiguration.xml"
      

Add the following node for change requests to the <WorkItemColors> node:

<WorkItemColor primary="FFFF9D00" secondary="FFFCEECF" name="Change Request" />
      

Once you've done that, import the file:

.\witadmin.exe importprocessconfig /collection:http://URL_TO_TFS:PORT/tfs/COLLECTION_NAME /p:PROJECT_NAME /f:"C:\PATH_TO_WORKING_FOLDER\ProcessConfiguration.xml"
      

Assuming you haven't received any errors thus far, change requests should now be available to put on the backlog.

You may get a configuration error on the backlog that requires you to remap some of your columns, if you've set up custom columns.