Have it Your Way: Customizing Work Items in Team Foundation Server

Have it Your Way: Customizing Work Items in Team Foundation Server

ith the release of Visual Studio 2005 Team Edition last year and Team Foundation Server in March of this year, Microsoft delivered arguably one of the largest functional upgrades to the Visual Studio line of tools in years. When used with Team Foundation Server, Visual Studio Team Edition provides a wide range of tools that can help to organize teams of developers. As many groups begin to use Team Foundation Server, many groups are finding that the out-of-the-box configuration doesn’t quite meet their teams’ needs.

Team Foundation Servers define workflow and project tracking through Process Templates, which contain the types of work items, project organization, etc. for a project. Microsoft provides two process templates with Team Foundation Server

  • MSF for Agile Software Development
  • MSF for CMMI Process Improvement

The Agile process template defines a lean process that doesn’t require great amounts of documentation?it focuses on people. The CMMI process template defines a process more centered on process and documentation. Unfortunately, most teams find these generic default templates inadequate; the CMMI process is too complex, and the Agile process generally lacks sufficient flexibility for all but very small development teams.

Figure 1. Project View: This view displays the various work items provided by the Agile process template.
Author’s Note: The versions of Visual Studio that support the new team features are Team Edition and Team Suite. Team Edition comes in three flavors, supporting Software Developers, Software Testers, and Architects, each containing features intended to support each of those development roles. Team Suite supports all the features of the three Team Editions in a single tool. This article discusses features specific to the Team Editions and the Team Suite versions of Visual Studio. Visual Studio professional and other less feature-rich versions of Visual Studio do not integrate with Team Foundation Server. Unless otherwise stated, references to Visual Studio refer to either the Team Edition or Team Suite versions of the product.

Process Templates
When you open a team project using the Team Explorer inside Visual Studio Team Edition, you will see the list of components that make up a Team Foundation Server project (see Figure 1).

The first component type listed is the work items. Work items provide the framework for much of the communication and process flow inside Team Foundation Server. Work items provide generic customizable containers for various pieces of information that must be tracked during development of a project. The Agile process template provides work items for Scenarios, Quality of Service Requirements, Tasks, Bugs, and Risks. There are other important components of a team project that are defined by a process template, such as documents, reports, and source control, but especially in the Agile process, most of the communication takes place using work items.

The goal of this article is to show you how to modify a process template’s work items to meet the needs of your development team. Keep in mind that the team probably includes not only software developers, but also testers and project managers. Each of these roles likely requires different types of work items and might also require that work items include specific fields, field requirements, etc. The process template is the structure provided by Microsoft for defining these aspects (and more) of the software development project.

From the perspective of Team Foundation Server, the process template is a complete definition of a development process. To modify the work items, you’ll need to modify key areas of the process template. First, the template’s Process Guidance section contains the template documentation. It is set of HTML files that document the development process, which could prove valuable to the users of the Team Foundation Server project. Second, you’ll need to modify the work item definitions, defining the fields used in a work item, which fields are required, etc.

Getting Started: Exporting Existing Templates
To get started, you need a process template to modify. Rather than starting from scratch, the easiest way to make changes is to export an existing process template, modify the appropriate files, and then import the template back into Team Foundation Server. To export an existing process template, open the Team Explorer window in Visual Studio. Right click on the highest node in the tree view (should be the name of the Team Foundation Server you are connected to), click Team Foundation Server Settings, and then select Process Template Manger as shown in Figure 2.

Next, select the Process Template you wish to export, and click the Download button (see Figure 3). You will then be prompted to specify the location to save the Process Template. The export process can take several minutes to complete.

Figure 2. Selecting a Process Template Manager: Select Team Foundation Server Settings, and then Process Template Manager from the Team Foundation Server context menu.
Figure 3. Copying a Process Template: After selecting a Process Template, click the Download button to make a copy of the Process Template that can be modified.
Figure 4. Process Guidance: Process guidance provides documentation for the process template.

Using the location you specified, Visual Studio creates a folder named for the Process Template you selected. The folder can be quite large. If you export the Agile template, the folder will contain roughly 8 MB of files, while exporting the CMMI template requires closer to 43 MB?but don’t worry, you need to modify only a small amount of the content in those directories. As you can guess, after modifying the process templates, you’ll later upload the modifications using the Upload button pictured in Figure 3.

The largest component of both process templates lies in the Process Guidance HTML sections, which are likely to be an important part of the modification process. As stated above, these contain the documentation for the work items and processes defined in the process template. Because the process guidance is simply a set of HTML files, I won’t go into detail on how to modify them. You can find the HTML files in the Windows SharePoint ServicesProcess Guidance directory (see Figure 4) inside the process template folder created when you downloaded the process template. These files will be hosted on the project’s SharePoint portal.

While it is not yet in final form, if you are interested in modifying the process guidance for a process template, you should check out the MSFWinBuild project on GotDotNet. That project compiles process guidance XML files into HTML files that you can publish on a project’s SharePoint portal.

Modifying Work Items
Before starting to modify work items, it’s worth exploring why you would want to modify them in a process template. Many teams will find that one or more additional work item types are necessary to support their development process. For example, you may find that a given work item type does not provide fields to capture the relevant details of the item. You may also decide to limit the transitions that are allowed between the various states of a work item to aid in support of a process flow, or make certain fields required to submit a work item. These are but a few of the possible reasons to modify the work items in a process template.

Work items are defined in the process template using an XML file. You can find them in the WorkItem TrackingTypeDefinitions directory in the downloaded process template directory. Notice that the list of work item types provided in the TypeDefinitions directory matches the types that can be created inside Visual Studio. Figure 5 demonstrates the process used to create new work items from within Visual Studio.

Figure 5. Creating Work Items in Visual Studio: The figure shows the various default work item types that Visual Studio users can create when using the MSF for Agile Software Development process template.

The type definition file for each work item uses the same overall structure. Open the bug.xml type definition file to observe how the file is organized (see Listing 1). First, you’ll see the work item type’s name and description, followed by the list of fields for that work item. Each field can include help text and rules. The rules help by providing default values for fields, forcing values to be entered in required fields, providing lists of acceptable values for dropdown fields, etc.

The next section of the type definition file defines the workflow for the work item. The item’s workflow is based heavily on the state field assigned to the work item. In fact, unlike the manner in which other fields’ acceptable values are defined, the allowable states for a workflow item are defined in the workflow element of the type definition file. The Agile process template defines Active, Resolved, and Closed states. Each state contains a list of field rules. The type definition specifies that a bug in the Active state will have the Resolved Date, Resolved By, Resolved Reason, Closed Date, and Closed By fields empty. These rules make sense because an active issue is neither closed nor resolved. Other states define similar rules.

Finally, the last major section of the type definition file describes how Visual Studio should render the fields on the form. If you compare the element hierarchy under the Layout element to the visual layout of the bug work item form, it is easy to see how the Layout section of the XML document relates to the rendered form.

The real workflow magic comes in the definition of transitions between states for a work item. By modifying the rules defined for transitions, your team can define a workflow based on the team’s existing processes. As an example, the bug work item type definition specifies that when a bug work item is moved from the Active to the Resolved state, several things should happen.

  • The file defines a list of reasons that allow users to specify why the state is changing. In this case, the acceptable values are Fixed, Deferred, Duplicate, As Designed, Unable to Reproduce, and Obsolete.
  • The Assigned To field will be populated with the value of the Created By field.
  • The Activated Date field will be made read-only.
  • The Activated By field will be made read-only.
  • The Resolved By field will be made required, must be set to the name of a valid user of the system, and will be defaulted to the name of the current user.
  • The Resolved By field will be set to the current time on the server.

Other transitions are defined, but all are similar to the functionality defined for the Active to Resolved state.

Example: Making a Field Required
At this point, you are no doubt beginning to see how you could modify work items to satisfy your group’s development process needs. In working with the bug work item, I noticed that the Description field is not required, so I’ll show you how to modify the template slightly to demonstrate how to require users to populate the Description field when creating a bug. This is a very simple task. Find the field definition for Description in the type definition. It should appear similar to the line below.


Modify the file to match the example below.


Adding the Required element to the field’s type definition forces users to fill in the Description field before a bug can be saved.

Add a Field to the Form
Another useful feature that could be added to the bug work item is a “Found By” field indicating who found the bug. To make this change, you need to add a new field and indicate where Visual Studio should place the field on the work item form.

To add a field to the work item definition, insert the following XML text directly below the field definition for the Description field.

                 Who found the bug?                                                                    

The new field definition adds a required field named “Found By,” and provides a list of allowed values: Customer, Tester, Developer, and Other. Tester is the default value for the field.

To finish up, you need to specify where Visual Studio should place the field on the work item form. In this case, put it in the General section under the Details tab. The highlighted code below shows where to place the Control element required to add the Found By field to the form.


Finishing Up: Uploading Your New Process Template
Before you can use the process template you just modified, you must upload your process template to Team Foundation Server. However, before doing that, you must provide a distinguishing name and, optionally, a description for your new process template. You can modify those items in the ProcessTemplate.xml file in the root of the process template directory created during the earlier download process. You set the name and description in the name and description elements, respectively, near the top of the ProcessTemplate.xml file. Name the new process template DevX Agile, and abridge the description to “Choose the DevX Agile process for small projects that require enhanced bug tracking features.”

Figure 6. Uploaded Process: After uploading the new DevX Agile process, here it is in the Process Template Manager.
Author’s Note: When modifying any of the XML files in the process template folder it’s important to ensure that the files are well-formed XML. Attempting to import a process template containing files that are not well-formed results in an import error. A simple way to ensure that an XML file is well-formed is to open it using Internet Explorer?which will display an error when opening a non-well-formed XML file.

When you’ve completed the process template file modifications, use the Upload button on the Process Template Manager dialog (see Figure 3) to upload your new process template. After a successful upload, you can create new team projects that use the new process template. Figure 6 shows the newly uploaded DevX Agile process selected in the Process Template Manager.

After uploading the DevX Agile process template, create a new team project using the DevX Agile process. Create a new bug and verify that the Description field is required and that there is now a new Found By field under the Details tab. Figure 7 shows before and after screen shots of the area of the bug work item form under the Details tab.

Figure 7. The Details tab of the bug work item form. The before screenshot was taken using the MSF for Agile Software Development process template. The After screenshot was taken using our new DevX Agile process template.

Stepping Back
At this point, you have successfully downloaded a process template, modified the bug work item type, uploaded the modified process template, and demonstrated that the changes produced the desired results. One severe drawback to the approach taken in the example discussed here is that you cannot use it to modify a process template that is already in use; you can apply the approach only to new team projects created after uploading the modified process template. This could be a big problem for existing projects that need slight modifications to the work items.

Therefore, instead of destroying a team project, uploading a new process template, and then recreating the team project based on the modified process template, you need a way to modify a process template that is already in use. Microsoft has provided a tool to help with this process. Using witexport you can export a single work item definition file, modify it, and then use witimport to import the modified work item definition into the process template.

Other modifications that could be made to the MSF for Agile Software Development process template would be to add a work item type for general requirements. The bug work item type should probably also be extended to include a more elaborate workflow (by adding more states with rules governing the state transitions) that would work more cooperatively with a quality assurance group.

Lastly, it is important to note that the example in this article only scratches the surface of the possibilities for extending and customizing process templates for Team Foundation Server. In addition, you may not need to make the modifications yourself; there are already many third-party process template publishers. Visit Microsoft’s Visual Studio Developer Center for links to vendors and free projects offering customized process templates. In addition, you’ll soon find many different tools for modifying process templates directly. The VSTS Customization Toolkit is a project hosted at GotDotNet that provides a tool used to visually edit process templates, preventing the tedious manual editing of the XML files.

Review your development processes and determine whether you can use Visual Studio’s integration with Team Foundation Server to better support your development group. It is likely that Team Foundation Server can be modified to support many of the processes you currently have in place while improving on some of the processes that need attention. Use work items as a way to communicate within your development group and customize the work items to suit your group’s needs.


About Our Editorial Process

At DevX, we’re dedicated to tech entrepreneurship. Our team closely follows industry shifts, new products, AI breakthroughs, technology trends, and funding announcements. Articles undergo thorough editing to ensure accuracy and clarity, reflecting DevX’s style and supporting entrepreneurs in the tech sphere.

See our full editorial policy.

About Our Journalist