Customizing Process Templates - Project Management - Professional Team Foundation Server 2013 (2013)

Professional Team Foundation Server 2013 (2013)

Part III

Project Management

Chapter 13
Customizing Process Templates

What's in this chapter?

· Understanding the artifacts contained in a process template

· Using the Process Template Editor

· Learning about custom work item controls

· Deploying custom work item controls to client machines Code Downloads for this Chapter

The code downloads for this chapter are found at on the Download Code tab. The code is in the Chapter 13 download and individually named according to the names throughout the chapter.

Although Team Foundation Server contains several great out-of-the-box process templates, and several quality third-party process templates exist in the supporting ecosystem, you may find the need to customize the process template in a multitude of different ways. Tools are available for editing the artifacts necessary for customizing a team project's process template.

This chapter introduces you to these tools and the different types of customizations available. You will also learn how to easily deploy changes to work item type definitions through the use of the automated build system in Team Foundation Server.

It is important to note that customizable process templates are currently enabled only for the on-premises Team Foundation Server product and not for the hosted Visual Studio Online offering at the time of this writing. It may be something that is enabled in the future but until then, customers using the Visual Studio Online are not able to customize their process templates.

Anatomy of a Process Template

Process templates are built around the concept that a process should enable you, rather than hinder you. If you implement too little of a process, you must expend significant effort to stay on track. The inroads you make on a project will fully depend on the organizational skills of your team. The infrastructure will not support or enforce your process. Too much process inhibits productivity and velocity.

Process templates in Team Foundation Server provide a way to introduce the process to the entire team without getting in the way. When you create a new team project, process templates are used to set up the work items, work item queries, agile tools settings and preferences, shared document libraries, dashboards, reports, and more. A process template is a collection of files, including XML files, documents, and reports.

Before you start exploring the contents of a process template, you might want to download an existing one by going to the Process Template Manager. From the Team Explorer home hub, you can choose the Settings link to take you to the Settings page where you will see a Process Template Manager link in the Team Project Collection page section, as shown in Figure 13.1.


Figure 13.1 Downloading a process template

Next, you select a process template, click the Download button, and then choose the location where you want to save the process template files. Figure 13.2 shows the Process Template Manager dialog box.


Figure 13.2 Process Template Manager dialog box

Plug-In Files

Plug-in files are artifacts essential to the New Team Project Wizard. Each plug-in file defines the tasks that will end up running during the wizard. The displayed screens used for gathering information during the wizard are also defined in the plug-in files.

Each plug-in reads the list of tasks and dependencies and creates an automation sequence that will run during the team project creation wizard experience.

Table 13.1 lists each of the plug-in folders, plug-in files, and a description of what each file contains. Figure 13.3 also shows the directory layout inside a process template where each of the configuration files is stored.

Table 13.1 Process Template Plug-In Files


Plug-in File




Defines the tasks to configure the initial security permissions assigned to identities for Team Foundation Server Build, and it uploads the build process template files.



Defines the initial iterations and areas of a team project

Groups and Permissions


Defines the initial security groups of a team project and their permissions



Defines the tasks to configure the initial security permissions assigned to identities for Visual Studio Lab Management



Defines the initial reports for a team project and sets up the report site.

Test Management


Defines the test management files to upload, which will create the initial test variables, configurations, settings, and resolution states of a team project. These settings are used by Microsoft Test Manager.

Version Control


Defines the initial security permissions for version control, check-in notes for a team project, and whether exclusive check-out is required

Windows SharePoint Services


Defines the project portal for the team based on a template for a SharePoint site; also defines template files and process guidance

WorkItem Tracking


Defines the initial work item types, queries, and work item instances of a team project. This plug-in also defines the settings to use for the agile-based planning tools in Team Web Access.

Source: MSDN Library (


Figure 13.3 Directories in a process template

Default Security Groups and Permissions

Each team project can contain security groups, and each has a set of permissions scoped to the team project level. The process template can create default team project security groups that can be used for setting permissions in each of the other plug-ins for the team project, as well as which permissions should be initially granted or denied for those security groups. For example, the Microsoft Visual Studio Scrum 2013 process template defines the following default team project security groups:

· Readers

· Contributors

· Build Administrators


Additionally, the Team Project Creation Wizard will create a security group called Project Administrators that will be granted all permissions. You do not have to define the group in the process template to be created.

Figure 13.4 shows an example of what the Visual Studio Scrum 2013 process template defines for the default security groups.


Chapter 24 provides more information about managing security privileges and permissions.


Figure 13.4 Default security group definitions for the Visual Studio Scrum process template

Initial Area and Iteration Nodes

If there will be standard area path and iteration path nodes that should be available for each new team project, you can define those initial nodes in the process template. Figure 13.5 shows the default iteration nodes created when using the Visual Studio Scrum process template.


Figure 13.5 Default iteration nodes

Work Item Type Definitions

Work item type definitions are the files that contain information about which states, transitions, fields, and form layouts exist on a particular work item type. Work item type definition files are by far the most commonly customized artifacts in a process template. The process template's main work items file lists each of the work item type definitions that should be included, as well as the location of the individual work item type definition files, as shown in Figure 13.6.


Chapter 12 provides more information about the default work item types available in the standard process templates.


Figure 13.6 Work item type definitions to be included and the location of files

Work Item Fields

One of the defining parts of the work item type definition is the list of fields contained for that work item type. Each field can have the attributes shown in Table 13.2 that define it.


You must be careful not to create too many fields, but, rather, reuse them across work item types, team projects, and team project collections as necessary. By reusing the same reference names (or reportable names if different) for fields, you also benefit from being able to report the same data across team projects and team project collections, even if they are using different process template types. You can even create work item queries that use the same field across multiple team projects for showing up as a column in the query results.

The maximum number of fields for all work item types in a team project collection is approximately 1,000. Additionally, approximately 1,000 reportable fields can be defined across all team project collections for one Team Foundation Server instance. These maximums happen to correspond to the number of columns that can be created in a SQL Server table, less some overhead used by Team Foundation Server.

Table 13.2 Field Attributes




This is the friendly name used for the work item query. Each field in a team project collection must contain a unique name.

Field Type

This attribute defines the type of data that will be stored in the field. Among all of the types available, the following types are commonly used: String, Integer, Double, DateTime, PlainText, and Html. The correct type should be chosen, because it cannot be changed after the field is created in the team project collection.

Reference Name

This attribute defines a longer name for use in organizing multiple fields. Each field in a work item type definition must contain a unique reference name. You will probably want to distinguish your company's custom fields by prefacing the reference name with your company name (for example, Contoso.MyNewCustomField).

Help Text

This describes the field's purpose to the end user. The help text is displayed whenever hovering over a field's label on the work item forms.


This attribute indicates how the field will be handled when the data warehouse jobs process it. The possible values for this attribute are None, Dimension, Detail, and Measure. For example, the number of hours remaining for a task would be defined as a measure, but the task's priority and to whom it is assigned would be defined as dimensions. Fields marked as a Detail do not show up in the Analysis Services warehouse cube, but they do show up in the relational data warehouse.


If the value for the Reportable attribute is Measure, the Formula attribute identifies how the warehouse will aggregate the values for the field. In most cases, you should use Sum.

Reportable Reference Name

By default, the name used for the data warehouse is the reference name. However, if fields in multiple team project collections must have a different reference name, but still be reported as the same field, this attribute can be defined. The reportable reference name should be unique for each team project collection.

Reportable Name

In addition to the reportable reference name, a friendly reportable name is offered as well. It is similar to the name of the field and is used in the warehouse.

Sync Name Changes

If you have a field meant to store a value for a user account/person and this attribute is set to true, Team Foundation Server will update the contents of the field as changes are made to the display names in Active Directory, User Profiles, and so on.

Work item fields can also contain rules applied to the field at run time. Multiple rules can be specified to be applied for a single field. Table 13.3 shows some examples of common field rules that can be used.

Table 13.3 Field Rule Examples




This rule allows for a value to be specified as the default value for a field. This can be the current date/time, user information, another field's value, or a specified literal value.


This rule indicates a list of values allowed for this field. This can be a list of literal values or an entry for a global list. For example, you might want to constrain the values of a Priority field to the integers 1 through 4.


This rule indicates that the field is required to contain a value.


This rule indicates that the value of the field must contain the name of a valid user who has permissions to access Team Foundation Server.


This rule is particularly useful in states and transitions whenever the current user, or the current date and time, should be stored in a particular field.


This rule can be used to copy a value from another field, date/time from the clock, current user information, or from a specified literal value.


This indicates that that field cannot be edited.


This rule allows for an existing value to still be valid even if it is removed as an allowed value in the future. This applies as long as the field does not change values.

Several rules have optional for and not attributes that can be specified to indicate whether that rule applies to a security group (for attribute) or does not apply to the security group (not attribute). For example, a REQUIRED rule can be added to a field for theContributors security group by specifying the group in the for attribute, but the Project Administrators security group can be excluded by specifying the group in the not attribute.


More information about the available work item rules can be found in the MSDN documentation article titled “Working with Field Rules” at

Work Item States and Transitions

Work items can be classified in different states, and a workflow between those states can be defined using transitions. Each transition can contain a reason for the transition. For example, a bug can be in the state of Active, and then transitioned to the Resolved state with a reason of Fixed, Duplicate, As Designed, Cannot Reproduce, Deferred, and so on. The combination of state and reason can be used for reporting and for work item queries to further distinguish between work items in the same state.

Each work item can have only one initial transition that can contain multiple reasons. Figure 13.7 shows the states and transitions for the Bug work item type in the MSF for Agile Software Development 2013 process template. Figure 13.7 also shows the available reasons for the transition between the Active and Resolved states.


Figure 13.7 States and transitions for the Bug work item type

Rules for States and Transitions

Previously in this chapter, you learned that rules can be applied to fields globally for the work item type. Rules can also be applied at the state level or at a particular transition or reason. A combination of all the rules is applied based on the rules defined at the field, state, transition, and reason scopes. Figure 13.8 shows the different field rules specified for the Microsoft.VSTS.Common.ResolvedBy field on the transition between the Active and Resolved states.


Figure 13.8 Different field rules

You can also restrict certain transitions using the same for and not attributes used for certain field rules. Figure 13.9 shows those attributes being specified for transition between the Active and Resolved states. As an example in this figure, you are allowing those in the Contributors security group to move the work item from the Active state to the Resolved state, but members of the Readers security group can never make this transition, even if they are a member of the Contributors security group.


Figure 13.9 Attributes being specified for transition

Work Item Form Layouts

Once all of the fields and the workflow of states and transitions have been defined, you can specify what the work item form will look like when it is opened in any of the Team Foundation Server client tools. The layout is specified by using a set of items. Figure 13.10shows a partial example of a layout for the Bug work item type in the MSF for Agile Software Development process template.


Figure 13.10 Layout for the Bug work item type

Following are the items that can be used on the form:

· Group—This container can include one or more columns, and optionally it can specify a display name for the container.

· Column—A column is contained within a group, and it can be either a fixed width, or have a percentage-based width relative to the other columns in the same group.

· Control—This item can be added to other container units, and it allows the presentation of a work item control that can edit a field or display other information.

· Tab Group—This container begins a new grouping of tab pages.

· Tab Page—This container stores all of the items that would exist inside a particular named tab.

Considerations for Different Client Layouts

Work item type definitions can actually specify multiple layout sections that target specific clients. For example, you might specify a particular layout when a work item is opened in Visual Studio Team Web Access, versus one displayed for the Visual Studio Team Explorer client. Following are the available work item form layout values:

· WinForms—This layout target is used in the Visual Studio Team Explorer client, and additionally in Microsoft Test Manager.

· Web—This layout target is used by Visual Studio Team Web Access.

· JavaSWT—This layout target is used by Visual Studio Team Explorer Everywhere, which displays within Eclipse-based products.

· Unspecified—If no other display targets are specified, clients can ultimately fall back to using the Unspecified layout.

The current version of the Process Template editor available in the Team Foundation Server 2013 Power Tools does not support editing multiple work item form layouts. If you choose to use multiple work item form layouts, you must use the XML editing approach described later in this chapter.

Standard Work Item Controls

Several standard work item controls are available for displaying and editing fields in the form layout. Table 13.4 describes each of the available standard work item controls.

Table 13.4 Standard Work Item Form Controls




Used for standard field editing and can accommodate many of the different field types without any special editing features

Date Time

Has special editing features available for date/time fields. For example, this control can be used to provide a standard calendar control that the user can use to edit a field.

HTML Field

Allows an end user to edit with rich text for HTML fields. A new rich editing toolbar is displayed immediately above the control to allow the end user to easily reach the commonly used rich editing options available for an HTML field.


Does not specify a particular field to edit, but instead allows a user to edit the different links of multiple link types currently set on a work item. The control additionally has filter options to filter certain types of work item link types, work item types, and external link types from showing in an instance of the links control.


Provides the end user with the ability to manage the file attachments on a work item. However, it does not modify a particular work item field.

Work Item Classification

Used only for editing the Area Path and Iteration Path fields and displays the available nodes in a tree control

Work Item Log

Shows a view of the historical revisions for a work item, including the comments for each of the revisions. Additionally, end users can specify a rich-text comment to be stored with a particular revision of the work item as soon as the end user saves the work item changes.


Allows for a label to be specified on the work item form. The label can specify a plain-text value and include a link to a static URL or a dynamic-based link that uses several supported macros, such as @ReportServicesSiteUrl, @ReportManagerUrl, @PortalPage, @ProcessGuidance, and @Me.


Can display literal HTML data, or point to a static or dynamic-based URL that can also use any of the support macros mentioned on the label control. Additionally, the UrlPath attribute can contain string parameters (similar to when using format strings in the .NET method String.Format()) and specify another field's value for use as the parameter to the dynamic URL.

Associated Automation

Used on the Test Case work item type to display and/or edit the associated automation for the Test Case work item

Test Steps

Used on the Test Case work item type to show and/or edit the test steps for the Test Case work item

Source: MSDN Library (

Work Item Categories

Team Foundation Server 2010 introduced a new work item tracking feature called work item categories. This feature allows for work item types with different names in different team projects to be used in external tools, in reporting, and in work item queries. For example, one team project may have a work item type with the name of “Bug” where another has a work item type called “Defect” that need to appear together in metrics on reports that pull data from both team projects.

Microsoft Test Manager is one example of an external tool that uses the work item categories to create and select work items based on their categories. Multiple work item types can be included in a work item category, and one is identified as the default work item type for the individual category.

Figure 13.11 shows the default work item categories specified in the Visual Studio Scrum 2013 process template.


Figure 13.11 Default work item categories for Visual Studio Scrum 2013 process template

The Hidden Types Category is unique in that it specifies the set of work item types that you do not want users to create manually. By default, the feedback and code review work item types are included in this category because of tools specially made for those user experiences. Each of the different user interfaces then no longer exposes the work item types included in this category in the lists of available work item types to use for creating a new work item.

Team Foundation Server 2013 introduced a new Features Category in its process templates. Work items belonging to this category represent high-level goals in the project portfolio. They will be shown at a high level in the Web Access UI and can be useful for managing groups of backlog items.

Work Item Link Types

Team Foundation Server 2010 introduced the concept of rich link types, which can be used throughout Team Foundation Server for reporting and querying work items. These rich link types truly allow full traceability between work items stored in Team Foundation Server. Each link type can have a specific topology and also have a different name that describes each end of the link.

Table 13.5 shows the available standard defined link types.

Table 13.5 Standard Defined Link Types

Forward Name

Reverse Name

Link Type Reference Name














Tested By




Test Case

Shared Steps



Source: MSDN Library (

You can also create custom link types for your own purposes in customized process templates. Following are the different types of link topologies available in Team Foundation Server:

· Network—Link types of this topology have essentially no rules and no directionality. You can have circular relationships, and the link looks the same from both ends. Figure 13.12 shows the network topology.Figure 13.12 Network topologyimage

· Directed Network—Link types of this topology are network links, except that there is directionality. You can specify a name that appears at each link end. In other words, the link looks different depending on which side you view it. Figure 13.13 shows the directed network topology.Figure 13.13 Directed network topologyimage

· Dependency—Link types of this topology are like directed network links in that they have directionality, but they also have an additional constraint to prevent circular relationships. Figure 13.14 shows the dependency topology.Figure 13.14 Dependency topologyimage

· Tree—Link types of this topology are essentially trees that enforce a one-to-many relationship and do not allow circular relationships. Figure 13.15 shows the tree topology.Figure 13.15 Tree topologyimage

Global Lists

Global lists are available at the team project collection level to allow for managing common lists used in the work item tracking system. For example, a company might have a list of departments that it would like to use in multiple work item types across several team projects. The company can specify an ALLOWEDVALUES field rule that includes only the values listed in the global list created for the departments. Anytime the list must be updated, the global list can be edited, and this does not involve deploying new work item type definitions to each of the team projects.

Global Workflows and Fields

Team Foundation Server 2010 Service Pack 1 introduced a new concept to manage global fields and workflows. Global fields and workflows were primarily added to support the Project Server Integration feature released to synchronize changes between Team Foundation Server and Project Server.

You can also take advantage of this new concept natively in Team Foundation Server 2013. Essentially, by defining a global workflow for a team project collection or specific team project, you are defining which fields should exist on all work item types across all of the team projects, or for the specified team project. Additionally, you can define global lists in the global workflow definition.


You can find more information about global workflows in the MSDN documentation article at

Initial Work Items

The process template can also contain a list of work items that will be initialized during the team project creation process. This is useful if each new team project should contain a certain set of startup work items to kickstart the team project. By default, the standard out-of-the-box process templates no longer define any default work items.

Work Item Queries and Folders

Certain work item queries and their organizational folder structure should be defined for a new team project in the process template. The standard work item queries should be included. Additionally, the default security and privileges for the work item query folders can be specified.

Figure 13.16 shows the default work item queries and query folders specified in the MSF for Agile Software Development process template.


Figure 13.16 Default work item queries and query folders

Microsoft Project Column Mappings

The Microsoft Project column mappings file correlates work item fields to fields defined in a Microsoft Project file. Figure 13.17 shows the default Project column mappings defined in the MSF for Agile Software Development process template. This is not the same as the mappings used for fields in a Project Server integration implementation. These mappings are used only if you want to open work items or a work item query directly in the Microsoft Project client when it is not connected to a Project Server.


Figure 13.17 Default Project file column mappings

Each mapping can additionally specify an IfSummaryRefreshOnly optional attribute, which indicates that if a Project task is a summary task it will never publish its value back to Team Foundation Server, but it will allow new values in Team Foundation Server to overwrite the value in the Project file. This is particularly useful for calculated fields in Project that should not be pushed back into Team Foundation Server.


More information about customizing the Microsoft Project field mappings files can be found in the MSDN Library at

Version Control Permissions and Settings

The process template can also include the settings and permissions on the version control repository of the team project created during the team project creation wizard. For example, the “Enable multiple check-out” setting, “Enable get latest version on check-out” setting, and required “Check-in notes” can be provided. Permissions for each group can also be specified.

Figure 13.18 shows the default permissions available to the Contributors security group in the MSF for Agile Software Development process template.


Figure 13.18 Default permissions

SharePoint Project Team Portal Document Library Settings

If a SharePoint team project portal is created during the team project creation wizard, then the initial content for the document libraries in that new SharePoint site can be specified in the process template. Additionally, the process guidance documents for the process template are specified.

Figure 13.19 shows the default document libraries, folder structure, and some of the documents available after a team project is created using the MSF for Agile Software Development process template.


You cannot customize the Microsoft Excel reports and SharePoint dashboards by customizing the process template files. These artifacts are created for a team project depending on the selection you make in the New Team Project Wizard.


Figure 13.19 Default document libraries, folder structure, and some of the available documents

SQL Reporting Services Report Definitions

The initial folder structure and reports in the related Reports site can also be specified in the process template. Figure 13.20 shows the list of each of the folders and SQL Reporting Services report definition files that will be uploaded to the Reports Manager site during the team project creation wizard for the MSF for Agile Software Development process template.


Figure 13.20 Folders and SQL Reporting Services report definition files

Using the Process Template Editor

Instead of editing each XML file by hand, you can use the Process Template Editor included with the latest version of the Team Foundation Server Power Tools. The Process Template Editor comprises a set of tools integrated into Visual Studio Team Explorer that allow you to edit work item type definitions and process template definition files, export/import work item type definitions, and create/modify global lists, and it includes a work item field explorer to view details about the fields included in a team project collection.

Installing the Process Template Editor

The Team Foundation Server Power Tools installer is available from the Visual Studio Gallery and is updated regularly.

The quickest way to find the latest download for the Power Tools installer is to go to your preferred search engine and use the search term “Team Foundation Server Power Tools.” Currently, a list of all the Power Tools for the entire Visual Studio product line is listed at

Before you begin installing the Power Tools, be sure to have all instances of Visual Studio completely closed because the installer will be setting up and configuring several Visual Studio add-ins.


Always be sure that you are using the latest version of the Team Foundation Server Power Tools. The Team Foundation Server product team at Microsoft continually improves the Power Tools with bug fixes and new features. Traditionally, a new version of the Power Tools has been released every three to six months.

Working with a Process Template

Instead of editing work item type definitions directly on the server (which is an option), it is a best practice to download the process template, store it in version control, and then edit it offline. When the changes you have made are ready and tested in a test environment, you can then deploy those updates to your production Team Foundation Server team project collection(s).


Chapter 11 provides more information about storing process templates and managing other Team Foundation Server artifacts in the version control repository.

Whenever you have the process template stored in an offline location, you can open the ProcessTemplate.xml file contained in the root folder for a process template, and the Process Template Editor window will display in Visual Studio. Figure 13.21 shows the root Process Template Editor window when opening the Visual Studio Scrum process template.


Figure 13.21 Process Template Editor window

From the root window, you can edit all of the individual parts of the process template easily. For example, you can edit the work item type definitions by navigating to the Process Template Work Item Tracking Type Definitions node. Then select a work item type and click the Edit button. Many of these different parts were shown in earlier figures for this chapter in each heading that discussed the process template artifact types.


If you are interested in learning more about using the Process Template Editor, you can read through the help documentation included in the Team Foundation Server Power Tools installer. For 64-bit operating systems, the default location for the help documentation is C:\Program Files (x86)\Microsoft Team Foundation Server 2013 Power Tools\Help\ProcessEditor.mht.

Using an XML Editor and WITAdmin

An alternate approach for managing process template and work item type definitions is to edit the XML files with your preferred XML file editor, and then use the command-line tools to export and import the work item type definitions. The XML schema is completely documented in the MSDN Library and is available in the following locations:

· Process Template Schema Reference

· Work Item Type Definition Schema Reference

The command-line tool named witadmin.exe is actually a tool installed whenever you install Visual Studio Team Explorer (or another Visual Studio 2013 product). From a Developer Command Prompt (and with the appropriate server permissions), you can perform several administrative functions to manage the work item tracking system.

Table 13.6 shows a few of the available commands, but you can always discover the full list by executing witadmin.exe /? at a Visual Studio command prompt window.

Table 13.6 Sample Commands for witadmin.exe




Particularly useful when you need a list of all of the fields in a team project collection and their details. Each of the entries will even list all of the work item types and team projects that the field is being used by. When used with the/unused switch, you can also get a list of fields that exist in the team project collection that are completely unused.


Allows you to update certain attributes for an existing field after it has been created. For example, you can update any of the name attributes, but you will notice that not all attributes can be changed. An example of this is the work item type field. You are mostly not able to change the work item type unless it is between HTML and PlainText.


Will completely remove a field once it is unused by any work item type in any team project in the team project collection. It will also remove the field from the warehouse during the next warehouse processing cycle if this was the last team project collection using the specified field to be deleted.


Helpful for listing the work item types available in a team project


Allows you to rename an existing work item type even if there are already work items of that type created in a team project. For example, you may decide to rename the Requirement work item type to User Story or Feature at some point in the future.

destroywi, destroywitd

Allows you to completely destroy a particular work item or a work item type, and all its existing work items, in a team project. The data is not destroyed in the warehouse and will remain until a full rebuild occurs.

exportwitd, importwitd

Allows for exporting and importing work item type definitions from a team project. If a work item type currently exists, it will be replaced with the new work item type definition. Existing work items will use the new definition after it is imported.


Lists the available set of link types in a team project collection

exportlinktype, importlinktype

Allows for exporting and importing new link types for the team project collection. If the link type already exists, it will be updated.

exportcategories, importcategories

Allows for exporting and importing new work item category definitions for a specific team project. If the work item category already exists, it will be updated.

exportgloballist, importgloballist, destroygloballist

Allows for exporting, importing, and destroying global list definitions for a team project collection, respectively. If a global list has the same name, it will be replaced with the newly imported global list definition.

exportprocessconfig, importprocessconfig

Allows you to customize several process configuration elements to meet your Agile planning and Scrum processes. Many of these elements control the interactive tools and visual displays provided in Team Web Access. This can also be useful when using the MSF CMMI and third-party process templates to configure the agile planning tools appropriately.

exportglobalworkflow, importglobalworkflow

Allows you to export or import the global workflow definitions, which allows you to share definitions of fields and list items among multiple types of work items, as previously discussed in this chapter

Deploying Updates to Process Templates

Now that you have a grasp of how to fully customize your process template, you can use that new process template in several ways. You can deploy your process template in one of two scenarios:

· Updating individual components of an existing team project

· Using it in the team project creation wizard for new team projects

Uploading Process Templates in Team Foundation Server

To allow project collection administrators to create a new team project using the customized process template, you must add the process template to the available process templates for the team project collection. You can manage the available process templates by using the Process Template Manager window described earlier in this chapter (and shown in Figures 13.1 and 13.2).

You will notice that an Upload button is available. During the upload process, the process template will be validated for compliance, and any errors encountered during validation will be displayed in a message box. If the upload button is not enabled, you are likely connected to a hosted Visual Studio Online instance. Because Visual Studio Online does not currently support customized process templates, the Upload button will be disabled.

Editing Work Items on an Existing Team Project

The most common way to deploy updates for a process template for an existing team project is updating the work item type definitions. You can use the witadmin.exe importwitd command-line tool option for importing a new definition for an existing work item type definition in a team project.


Updating work item type definitions for existing team projects can be particularly risky. You should always ensure that you are testing your work item type definition updates in a test environment that includes waiting for a successful warehouse processing cycle to occur without any errors from the updates.

Some work item type definition changes have minimal impact, where others might take a little more effort to be fully implemented. For example, adding a new reportable field to an existing work item type definition does not impact the health of the Team Foundation Server, unless it conflicts with a field in another team project collection that has the same name, but different attributes. You will begin seeing a problem whenever the next warehouse processing cycle begins, because the conflicting field definitions will block further warehouse processing.

An additional scenario that has a higher impact would be changing the state name for an existing work item type definition. You must handle all existing work items in the old state name. Also, there may be existing work item queries that have used the particular state name and standard reports that rely on the old state name, all of which must get updated.


One method you might use for changing a state name on existing work items is to create a temporary transition from the old state name to the new state name. You can then update the work item type definition with the temporary transition. Then, move all of the work items in the old state to the new state using that temporary transition. Remove the temporary transition, and then upload the final work item type definition without the old state and the temporary transition to update the team project.

When adding field rules you will want to think about the impact of those changes on the existing work items in a team project. For example, if you were to add a new REQUIRED field rule, or change the values in the ALLOWEDVALUES rule list, you could potentially use a combination of ALLOWEXISTINGVALUE and DEFAULT field rules to ensure that the existing work items are still considered valid work items. You can then update all of the existing work items using a tool such as Microsoft Excel to bulk-edit the field value in all of the existing work items.

Using an Automated Build to Deploy Work Item Type Definition Changes

When you are editing source code for an application, it is helpful to have regular automated builds to compile and deploy the application for testing. Similarly, when making changes to work item type definitions in version control, it is helpful to have an automatic deployment process. You can use a customized build process template that will automatically deploy multiple work item type definitions to multiple team projects. You can create an automatic deployment build for both Production and Test branches that contain the process templates that would deploy to their respective Team Foundation Server environments.

An automated deployment process for work item type definitions should ideally have the following features:

· Specify multiple team projects to update.

· Specify multiple work item types to update.

· Back up each of the existing work item type definitions currently in use.

· Copy the latest version of the work item type definition and backups to a build drop folder.

· Indicate errors during the deployment process in the build log.

Additionally, the following standard build features would be included because it is an automated Team Foundation Server build:

· Build versioning

· Labeling the source code for the process template

· Getting the latest version of the process template

· Associating changesets and work items

· Gated check-in, continuous integration, scheduled, and so on


There is a work item type definition deployment build process template available with instructions for use on Ed Blankenship's blog at This build template was originally created for Team Foundation Server 2010, but has been updated to support Team Foundation Server 2012. At the time of this writing this has not been tested for Team Foundation Server 2013, but it would serve as a great starting point.

See Chapter 18 for more information about automated builds and build process templates.

Customizing Agile Tools

The Agile planning and developer productivity tools that you will learn more about in Chapter 14 provide several customization options for your process templates. This is nice because you can essentially get the tools to work with even customized process templates not based on any Agile methodology.

Here you will review a few of the top customization topics for the new common process configuration and agile process configuration files available in a process template. To read more about these files, visit this MSDN article:

Metastates and Backlogs

Team Foundation Server 2012 introduced a concept called metastates. Metastates are important because these tools need a way of defining what to show in certain situations. For example, the My Work page in Team Explorer has a section that displays available work items that a team member can use to start working on something. However, it only really wants to display “open” work items to team members so they are not inundated with a long list of work items. The problem though is how to limit the work item states that are considered “open.” This is where metastates come in.

In Team Foundation Server 2013, configuration of the metastates and agile project management tools has been combined into a single ProcessConfiguration.xml file. This file contains the defined metastates used for each work item category as well as (if appropriate for that group) the columns that will be displayed, and fields included in the quick addition panel of Team Web Access. The following is an excerpt from the definition of the requirement category:

<RequirementBacklog category=”Microsoft.RequirementCategory”

pluralName=”Backlog items” singularName=”Backlog item”>


<State value=”New” type=”Proposed” />

<State value=”Approved” type=”Proposed” />

<State value=”Committed” type=”InProgress” />

<State value=”Done” type=”Complete” />




You will notice that each of the states defined in the work item type definitions maps to known metastates. There are three categories of metastates in Team Foundation Server. Table 13.7 defines the available metastates for each of these categories.

Table 13.7 Allowed Metastates and Descriptions


Work Item Types




Indicates work items that are new, not yet committed, or not yet being worked on. Work items in this state appear on the product backlog page. Sample states that could fall into this metastate: New, Proposed, Approved, and To Do.



Indicates work items that have been committed or are actively being worked on. Work items in this state are removed from the product backlog page because they have been committed to an iteration or sprint. Sample states that could fall into this metastate: Active, Committed, In Progress, and Resolved.



Indicates work items that have been implemented. The effort represented by backlog items in this metastate is included in calculating the team's velocity. Sample states that could fall into this metastate: Closed and Done.



Indicates bugs that have been resolved but not yet verified



Indicates feedback items that have been requested but have not yet been received or responded to



Indicates feedback items that have been received by the recipient but have not yet been completed



Indicates feedback items that have been received and completed by the recipient



Indicates feedback items that have been received by the recipient, but were declined and not completed

Effort, Remaining Work, and Stack Rank

Two of the most important fields used in the Agile planning tools involve the estimated effort for a product backlog item and the remaining work on tasks. The following is an excerpt from the ProcessConfiguration.xml file that demonstrates the defaults used in the MSF for Agile Software Development 2013 process template. Notice that you can even specify the units used for the values in the remaining work field for the Task work item type. If you want to use something other than hours, such as story points, this would be where you would edit this setting:


<TypeField refname=”System.AreaPath” type=”Team” />

<TypeField refname=”Microsoft.VSTS.Scheduling.RemainingWork”

type=”RemainingWork” format=”{0} h” />

<TypeField refname=”Microsoft.VSTS.Common.StackRank” type=”Order” />

<TypeField refname=”Microsoft.VSTS.Scheduling.StoryPoints” type=”Effort” />

<TypeField refname=”Microsoft.VSTS.Common.Activity” type=”Activity” />

<TypeField refname=”Microsoft.VSTS.Feedback.ApplicationStartInformation”

type=”ApplicationStartInformation” />

<TypeField refname=”Microsoft.VSTS.Feedback.ApplicationLaunchInstructions”

type=”ApplicationLaunchInstructions” />

<TypeField refname=”Microsoft.VSTS.Feedback.ApplicationType”



<TypeFieldValue value=”Web application” type=”WebApp” />

<TypeFieldValue value=”Remote machine” type=”RemoteMachine” />

<TypeFieldValue value=”Client application” type=”ClientApp” />




Additionally, the product backlog prioritization tools will update the “stack rank” of the items automatically as they are reprioritized. The tool uses the field defined for Order and automatically fills in values so that the backlog items are able to be sorted from lowest to highest order.

Defining the Team

By default, teams in Team Foundation Server projects are defined based on the Area Path nodes that the team owns. However, if you don't use Area Path to define your teams, you could use an alternate field. For example, you might have a custom field on all of your work items with the name of Department that defines which work items belong to which team. You can specify that by setting the Team field to use in the process configuration file:


<TypeField refname=”System.AreaPath” type=”Team” />


Other Process Configuration Customizations

Other common types of process configurations are available in the ProcessConfiguration.xml file. The following list includes a few examples of additional customizations:

· Add or remove fields from the “quick add” pane in the product backlog view. For example, in addition to setting a title you might also want to specify an effort estimate with each new item.

· Add or remove columns from the backlog and iteration views.

· Change the list of activities that task work items and team members can be assigned to.

· Change the working days to be used when calculating the iteration's capacity and rendering the live burndown chart. By default, Saturday and Sunday are considered nonworking days, but you can remove or include additional weekdays as nonworking days.

· Configure the types of work items to be used as parents and children in the different tooling options.

· Customize the options available and the work item fields used for the stakeholder feedback tools.

· Change the accent color assigned to a work item of a particular type.

Common Work Item Type Customizations

Certain customizations are commonly made to the existing process template. The following discussions provide an overview of some of those common customizations.

Adding New States

Teams often might not feel that the states provided in the standard process templates fit well with their team's process. They might decide that a new state should be created in the workflow.

If you can avoid adding too many states, you can make it easier for end users to understand and use these new states during normal day-to-day interaction with work items. This will also reduce the amount of effort required to customize reports to take advantage of each of those states. Instead, you can use the combination of states and reasons to help you distinguish between work items in a specific state when querying or reporting on work items.

Adding a state can be done pretty easily. For example, if you wanted to add a Proposed state to a work item type definition, you might add a snippet similar to the following in the work item type's XML file:



<STATE value=”Proposed”>


<STATE value=”Active”>


<FIELD refname=”Microsoft.VSTS.Common.ClosedDate”>



<FIELD refname=”Microsoft.VSTS.Common.ClosedBy”>


You might also want to move around some of the field rules (for example, empty out the Closed Date and Closed By fields), as well as change some of the existing transitions to take advantage of the new state.


A full how-to article about adding a new state to a work item type definition is available in the MSDN Library at

However, adding a state does mean that certain reports will be affected. For example, some of the following reports in the MSF for Agile Software Development process template may be impacted:

· Bug Status Report—This report has a stacked area chart that lists bugs by state and has a particular color assigned to each state. Additionally, it shows the number of bugs in the Resolved and Active state assigned to each team member.

· Stories Overview Report—This report shows how many bugs are open for each user story and displays them in a segmented bar chart by state.

· Status on All Iterations—This report shows how many bugs exist in each iteration path and displays them in a segmented bar chart by state.

Displaying Custom Link Types

The Links control allows for rich interaction with the link types available in Team Foundation Server, including any custom link types you create for your process template. You can take advantage of the Links control to create an additional instantiation of a Linkscontrol on your work item form that filters by work item type, work item link type, and/or external links.

In the MSF for Agile Software Development process template, you will notice a tab named Implementation on a User Story and Task that displays any parent and children tasks and user stories. It also allows for easily creating new links scoped to the particular link type.

One example customization you might make would be to specify a new tab for tracking dependencies between work items. For example, you might add the following XML entry into the form layout for the work item type definition. Notice that theSystem.LinkTypes.Dependency link type is used for filtering for this particular links control instantiation:

<Tab Label=”Dependencies”>

<Control Type=”LinksControl” Name=”Dependencies”>



<LinkColumn RefName=”System.Id” />

<LinkColumn RefName=”System.WorkItemType” />

<LinkColumn RefName=”System.Title” />

<LinkColumn RefName=”System.AssignedTo” />

<LinkColumn RefName=”System.State” />

<LinkColumn RefName=”Microsoft.VSTS.Scheduling.OriginalEstimate” />

<LinkColumn RefName=”Microsoft.VSTS.Scheduling.RemainingWork” />

<LinkColumn RefName=”Microsoft.VSTS.Scheduling.CompletedWork” />

<LinkColumn RefName=”Microsoft.VSTS.Scheduling.StartDate” />

<LinkColumn RefName=”Microsoft.VSTS.Scheduling.FinishDate” />

<LinkColumn LinkAttribute=”System.Links.Comment” />


<WorkItemLinkFilters FilterType=”include”>

<Filter LinkType=”System.LinkTypes.Dependency” />


<ExternalLinkFilters FilterType=”excludeAll” />

<WorkItemTypeFilters FilterType=”includeAll” />




Synchronizing Name Changes

For work item fields that contain names of people, handling name changes can be particularly tricky. The names used for fields such as the Assigned To field are actually the display names for each Active Directory account, and are synchronized from Active Directory if you are using an on-premises edition of Team Foundation Server. If you are using a hosted Visual Studio Online instance, this will be the display name that users have entered in their personal profile details for their account.

You can specify an attribute on work item fields named syncnamechanges and set its value to True to indicate that the particular field should be automatically updated across all existing work items any time the display name changes. This should help the management of work items tremendously, and ensure that work items are not orphaned to users who have experienced name changes.

The following XML excerpt for a field definition demonstrates the use of this attribute:

<FIELD name=”Assigned To” refname=”System.AssignedTo” type=”String”

reportable=”dimension” syncnamechanges=”true”>

<HELPTEXT>The person currently working on this bug</HELPTEXT>




You can also use the witadmin.exe changefield command-line tool option to update an existing field's syncnamechanges value.


Team Foundation Server can actually detect if multiple accounts use the same display name in Active Directory. The display name used in work item fields in this case would be a disambiguated name that is a combination of the Active Directory display name, and the full user name, in the format of DOMAIN\user.

Introducing Custom Work Item Controls

The standard work item controls provide plenty of functionality for editing the work item fields that can be created in Team Foundation Server. However, there may be additional functionality that you would like to add to the work item forms or custom editors for the work item fields. You can do this by creating custom work item controls and deploying them to all of the end users' machines to use while editing work items.

Custom work item controls do not have to edit a work item field at all. Several of the standard work item controls (such as the Webpage control) do not contain any fields and only display information. An example of this would be a custom work item control to pull information from an external system related to the opened work item.

Work Item Clients

A different implementation of the custom work item control must be created based on the client that will be displaying the work item control. The following clients are currently available for displaying custom work item controls:

· Visual Studio Team Explorer—Windows Forms control

· Microsoft Test Manager—Windows Forms control

· Visual Studio Web Access—jQuery-based control

· Visual Studio Team Explorer Everywhere—Java SWT control

Team Web Access Custom Work Item Controls

Because Team Web Access was completely rewritten in Team Foundation Server 2012, the model for creating a custom work item control completely changed and is now fully supported. You will end up creating a jQuery-based control and then deploy it using the Web Access extensions administration experience. This allows you to not worry about deploying anything to the server.

For more information, check out these two blog posts by Serkan Inci for creating and deploying a new Team Web Access custom work item control:



Preferred and Fallback Control

If a particular client does not have an implementation of the custom control, or cannot locate the custom control, you can specify a control in the work item form's layout section of the work item type definition to be used. You can then specify the preferred control to use if it is deployed.

The following work item form layout excerpt demonstrates the use of the preferred control attribute:

<Control Type=”FieldControl” PreferredType=”MyCustomControl”

FieldName=”System.AssignedTo” Label=”Assigned To” LabelPosition=”Left” />

Work Item Control Interfaces

To create a custom work item control for Windows Forms, you must essentially create a new Windows Forms control that implements specific interfaces in the Team Foundation Server SDK. The following sections describe some of the most common interfaces that can be implemented for work item controls.


The IWorkItemControl interface is actually the primary interface to be implemented and is required for custom work item controls. It contains the base functionality for a custom work item control, and its members are used by the work item form in Visual Studio Team Explorer.

Listing 13.1 shows the full signature for the IWorkItemControl interface.


IWorkItemControl interface definition

// C:\Program Files (x86)\Microsoft Visual Studio 12.0



using System;

using System.Collections.Specialized;

namespace Microsoft.TeamFoundation.WorkItemTracking.Controls


public interface IWorkItemControl


StringDictionary Properties { get; set; }

bool ReadOnly { get; set; }

object WorkItemDatasource { get; set; }

string WorkItemFieldName { get; set; }

event EventHandler AfterUpdateDatasource;

event EventHandler BeforeUpdateDatasource;

void Clear();

void FlushToDatasource();

void InvalidateDatasource();

void SetSite(IServiceProvider serviceProvider);



Table 13.8 shows common members used to provide the base functionality for the work item control.

Table 13.8 Common Members Used to Provide Base Functionality




Contains a reference to the actual WorkItem object (and must be cast properly to the Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItem type). It can end up being null during initialization, so be sure to handle the situation gracefully.


Contains the name of the field used by the work item control for editing. This is something defined in the work item type definition's form layout section in the control definition. Not all controls need to edit work item fields, so the value for this property could be empty.


Provides all of the properties defined in the work item type definition's control item. In Team Foundation Server 2013, you can even use a CustomControlOptions type, which contains custom properties to be used by the control.


Specifies whether the control should render itself as read-only to the end user


These events should be implemented and raised before and after data is flushed to the data source (the work item).


May be called by the work item system. It indicates to the control that the control should be cleared.


Called by the work item system to indicate that the value stored by the control should be saved to the work item object immediately. This often occurs when the end user chooses to save the work item.


Called by the work item system to indicate to the control that it should redraw itself. Typically, the control will refresh its display by reading the data from the work item object.


Provides a pointer to the IServiceProvider object that allows you to take advantage of Visual Studio services such as the DocumentService or the IWorkItemControlHost service. You do not have to store this service provider reference if you will not be using any of the services provided by Visual Studio.


The label for the custom control can display a tooltip with information about the work item field or the custom control. You can decide what and how to display the tooltip implemented by the IWorkItemToolTip interface. Listing 13.2 shows the full interface signature for the IWorkItemToolTip interface.


IWorkItemToolTip interface definition

// C:\Program Files (x86)\Microsoft Visual Studio 12.0



using System.Windows.Forms;

namespace Microsoft.TeamFoundation.WorkItemTracking.Controls


public interface IWorkItemToolTip


Label Label { get; set; }

ToolTip ToolTip { get; set; }



Once each member is set, you can then make a call to ToolTip.SetToolTip(string) to provide a meaningful tooltip when the end user hovers over the label.


The IWorkItemUserAction interface is implemented when the control requires some type of user action (such as the control or work item field being in a bad state and you want to prevent the user from saving the work item). Listing 13.3 provides the full interface definition for the IWorkItemUserAction interface.


IWorkItemUserAction interface definition

// C:\Program Files (x86)\Microsoft Visual Studio 12.0



using System;

using System.Drawing;

namespace Microsoft.TeamFoundation.WorkItemTracking.Controls


public interface IWorkItemUserAction


Color HighlightBackColor { get; set; }

Color HighlightForeColor { get; set; }

string RequiredText { get; set; }

bool UserActionRequired { get; }

event EventHandler UserActionRequiredChanged;



Following are some of the interface members:

· RequiredText—This property stores the friendly error message displayed to the end user about what action needs to be taken. It is commonly displayed in an information bar in Visual Studio at the top of the work item form.

· HighlightBackColor/HighlightForeColor—These properties store the background and foreground colors that should be used in your custom control to stay consistent with the theme of the work item form.

· UserActionRequired—This property indicates to the work item form whether the control needs input from the user.

· UserActionRequiredChanged—This event should be raised any time the UserActionRequired property is changed by the control.


The IWorkItemClipboard interface provides functionality to your control for integrating with the clipboard functionality in Visual Studio. Listing 13.4 provides the full interface definition for the IWorkItemClipboard interface.


IWorkItemClipboard interface definition

// C:\Program Files (x86)\Microsoft Visual Studio 12.0



using System;

namespace Microsoft.TeamFoundation.WorkItemTracking.Controls


public interface IWorkItemClipboard


bool CanCopy { get; }

bool CanCut { get; }

bool CanPaste { get; }

event EventHandler ClipboardStatusChanged;

void Copy();

void Cut();

void Paste();



Each of the methods should be implemented and should handle the appropriate user-initiated command. If any of the Boolean properties (such as CanCopy) are changed, the ClipboardStatusChanged event should be raised to indicate to the work item form that the clipboard status for the control has been updated.


A group of developers has teamed together and released a set of commonly requested custom work item controls (including their source code) on a CodePlex project available at

Deploying Custom Controls

Once you have implemented the appropriate interfaces on your work item control, you must compile the .NET project and deploy both the compiled assembly that contains the custom work item control and a work item custom control deployment manifest file. Each of the artifacts should be deployed to one of the following locations for Visual Studio 2013 and Microsoft Test Manager 2013 clients. The clients will search for custom work item controls in the following order:

· Value Name Entries in Registry—If you want to store the artifacts in a custom folder, you can add a custom value list to the following registry key to point to that custom folder. Note that this registry key does not exist unless it is manually created by you or a custom installer.


· \WorkItemTracking\WorkItemTracking\CustomControls\LookInFolders]


· Common Application Data 2013–Specific Location—For example, C:\ProgramData\Microsoft\Team Foundation\Work Item Tracking\Custom Controls\12.0\

· Local Application Data 2013–Specific Location—For example, C:\Users\UserName\AppData\Local\Microsoft\Team Foundation\Work Item Tracking\Custom Controls\12.0\

· Visual Studio Private Assemblies Location—For example, C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\PrivateAssemblies\. Storing custom work item controls in this folder is not recommended.

· Common Application Data Location—For example, C:\ProgramData\Microsoft\Team Foundation\Work Item Tracking\Custom Controls\

· Local Application Data Location—For example, C:\Users\UserName\AppData\Local\Microsoft\Team Foundation\Work Item Tracking\Custom Controls\

One of the first three approaches is recommended when deploying your custom work item controls to a team member's machines.

Work Item Custom Control Deployment Manifest

The work item custom control deployment manifest file has a .wicc extension. It contains the full class name for the custom work item control, as well as the name of the assembly that contains the custom work item control. That is the filename for the file where.wicc is the file's extension, as in MyCustomControl.wicc. The contents of the custom control deployment manifest would contain something similar to Listing 13.5.


Work item custom control deployment file

<?xml version=”1.0”?>

<CustomControl xmlns:xsi=”

/XMLSchema-instance” xmlns:xsd=””>




Using the Custom Control in the Work Item Type Definition

Once the work item custom control artifacts have been deployed to each of the client machines, you can then configure the control definition in the work item type definition's form layout section by setting the Type attribute as shown here. The value for this attribute is the filename of the custom work item control deployment manifest, without the .wicc extension.

<Control Type=”MyCustomControl” FieldName=”System.AssignedTo”

Label=”Assigned To:” LabelPosition=”Left” />

Remember that you can now use the preferred and fallback controls mechanism discussed earlier in the chapter to make a better experience for your team members.


Process templates are the most customized part of Team Foundation Server. They allow teams to easily modify their process and have the tool help them with day-to-day activities for managing their process. In this chapter, you learned about the different artifacts that make up a process template, how to deploy changes to the work item type definitions, and how to edit work item type definitions to include common customizations.

You also learned about custom work item controls and the specific Team Foundation Server SDK interfaces that should be implemented when creating the custom work item control. Deployment of those work item controls to each of the client machines was also covered.

In Chapter 14, you will learn how to manage your teams using the new Agile-based planning tools in Team Web Access.