Customize Work Item’s fields with Rules


1 – Customize Tfs Process Template
2 – Basic of TFS Process Template Customization
3 – Adding Field to a Work Item Definition

In the third part of this tutorial I showed how to add a field to a Work Item Definition, in this post I’ll show how you can customize field’s behavior with the addition of Rules.

If I select the new field I just created (called Note di revisione), I can press edit to modify its definition and in the “Field Definition” form I can manage all the Rules applied to the field. (Figure 1).


Figure 1: Adding a rule to a field is really simple

Each rule has a different meaning, but all of them shares some common behavior. Let’s take the first rule of the list as example, it is called ALLOWEDVALUES and is used to specify a list of allowed values for the field.

In our example the field admit only the value “non effettuate” (not present), “in lavorazione” (working), “approvata” (approved), because these are the only three state that are allowed for this field in our customized process. After we choose the ALLOWEDVALUES rule in Figure 1 and press OK a new window appears to customize this specific rule. (Figure 2)


Figure 2: This specific rule has a list of allowed values, you can: add, edit and delete values.

Each rule can have its parameters, the upper part is common (we will see shortly how it is used), and the bottom part contains the configuration parameter for the specific rule we choose. After I added the three allowed value in the list of valid values, I can simply confirm (OK Button), then save the definition to the Team Process and finally I try to create a new bug to verify if the rules configuration is ok. You can see from Figure 3, that the rules is now applied to your custom field, because the interface looks different from before.



Figure 3: Since the ALLOWEDVALUES permits only a predefinite range of values, TFS changes the UI and uses a combo to edit the value of the field.

The most interesting aspect is that the UI checks all the rules of the WorkItem and modify the layout accordingly; since we have an ALLOWEDVALUES the field is edited with a ComboBox that contains only the three values I inserted in the rule configuration. Another interesting feature is that a rule can be applied only to certain role, suppose that in our process the value “Approvate” (Approved) can be used only by the administrator of the project, because standard developers could not approve revision note.

To obtain this result we need to add the ALLOWEDVALUES rule two times, as shown in Figure 4.


Figure 4: We can apply the same rule, with different configuration, to different securable objects.

As shown in Figure 4, the solution to the problem is simple, just add the same rule two times with different configuration and use the For rule parameter to restrict the application of the two different configuration. When you edit a WI the only rules that are applied are those one that are not assigned to any specific group (the For parameter is left empty) or that are assigned to a group that comprehend the editing user. In the previous example the For field was left empty (the rule apply to all users), now I have two rules, each one applied to a different group.

You can notice that the For parameter can be changed by a combo in the Rule editor, but it contains only the [global] groups of Tfs, that are common to the entire Project Collection. This does not mean that you can choose only among the listed value, because you can select any securable object you like. In this example I choose to specify Tfs group specific to the project, that has the form [project]\groupname. You can simply click in the combo and write whatever user or TFS group you want.

Now login as an administrator and you should see all three allowed values in the combo as shown in Figure 3, but if you log to TFS with a user that belong to the contributors group you should only see the two values “Non effettuate” and “In Lavorazione”.

There are a lot of useful rules in TFS and in subsequent posts I’ll show the most common ones, as well as some other interesting customization you can do to a Work Item Definition.

Stay Tuned.



Customization of TFS process template – adding field to a Work Item Definition

1 – Customize Tfs Process Template
2 – Basic of TFS Process Template Customization

In this third part it is time to configure the definition of a Work Item. This is the most complex and more useful section of the process template that you can modify to adapt to your needs. We can modify a WI definition in two distinct way: on a local process template as explained in the previous articles and directly on a Team Process that exists on the server.

This second opportunity is useful if you need to modify the definition of a WI (Bug, Task, User Story) only for a specific Team Project and not for every Team Projects of your organization. Suppose you have a single TP for a software that interact with various types of RFID readers and you want to trace the code of the reader used when someone signal a bug. This is a very specific customization that you need to apply only to that Team Project so you do not create another Process Template, but change the WI definition in place.


You can also use this technique to validate your customization immediately: open the WI definition, modify it, press save and you can immediately test all the modifications in the Team Project. Compare it to the time needed to: modify the local version, upload the new process template, create a new Team Project based on that template and finally verify that the customization is correct.

To make all my examples on customization of Work Items I created a Team Project called WICustomization that will be used only as WI customization test. Once everything works as expected, if you want to use it in your new Team Process Template, you can download the definition as XML from WICustomization Team Process and copy to your local folder where the new Process Template resides.

To download the definition of a specific Work Item from a Team Project you use the command line tool witadmin

witadmin exportwitd /collection:http://localhost:8080/tfs/defaultCollection /p:TestAgile /n:Bug /f:bug.xml

To edit a WI with the graphical editor you should open the Process Template Editor from the menu Tools->Process Editor –> WorkItemTypes->Open WIT from server (Figure 1).


Figure 1: Open a Work Item Definition directly on a live Team Project

You should choose the project collection, then the Team Project and finally the type of WI that you want to change.


Figure 2: Simply choose the Team Project and the WI type you want to customize.

Now I want to add a field to Bug WI type called “Note di revisione” (revision note) that will be used to add note to a bug during the bug revision process. I can simply select the tab Fields and press the New button.


Figure 3: The form to create a new Work Item field

We need to specify a descriptive name, a type and a reference name, that should be unique. The reference name will be used by TFS to reference the field. You can also add an Help Text that will be used as tooltip to help the user understand the purpose of that field. The last two parameters are used to make the field reportable; basically you can instruct TFS to move values of this field into the cube to be available for reporting.

Now that I defined a new field, I need to change the interface of the WI to make it editable. In the Layout field we have a tree that represents the layout of the WI editing interface and the good part is that you can easily configure it to make your new field editable only with few clicks.

Suppose you want to insert a textbox to edit your new field in the red area of Figure 4:


Figure 4: Correspondence between the tree representation of the layout and the graphic element in the WI edit interface.

To obtain desired result we need to add another Group with a single Column and inside that Column a control to edit the new Field. With a Right-Click we can add another Group, place a control inside the Single column.


Figure 5: You can easily add another Group with a Control that reference the new field. As you can see the UI now has another textbox.

To allow editing you should simply specify the unique field name (Custom.RevisionNote), then the label you want for the textbox and the game is done. Now you can save the configuration, this will immediately update the definition on the team project, so you can refresh the team explorer and try to create a new Bug to verify that the field is present.


Figure 6: My new field is now editable in the Work Item Definition

As you can see the Help Text of the Field is shown as tooltip and the whole procedure is matter of few click of the mouse.



Basic of TFS Process Template customization

1 – Customize Tfs Process Template

In the first post I showed how to download the definition of a process template into a local folder and how to open it with the Process Template Editor; in this post I’ll show you some of the very basic customizations that you can do with the PTE.

In the Methodology section you can simply change the name of the Process Template as well as including a textual description. Remember that if you do not change the name, when you upload the modified version you will overwrite the original PT, so if you are planning to create a modified version of some basic template, you need to change the name first.


Figure 1: How to change name and description of the Template

The WorkItem section needs a more accurate series of post, so we can move on the “area and Iterations” where you can setup the default areas and iterations that will be created when you create a Team Project based on this Template.


Figura 2: In the Areas and Iterations part you define default areas and iterations

The MS Project Mapping tab permits you to define how Microsoft Project will map the various fields of the Work Items when connected to a Team Project. Configuration of this area is quite complex and you can find all the details in MSDN. In Figure 3 you can see a snapshot of the configuration of the MSF for Agile..


Figura 3: Microsoft Project Work Item mapping for MSF for Agile 5.0

Here is a brief explanation. The first column contains the reference name of a Work Item field, it is the unique name of that specific field inside TFS. The second column contains a reference to a Microsoft Project Field, with the convention that all custom field are named pjTaskText followed by a unique number. As you can see in Figure 3, the System.Id is mapped to a custom field named pjTaskText10, while the System.Title is mapped to a well known project field called pjTaskName that represent the name of the WorkItem. The third column represent an header to visualize and the last column contains a unit of measure.


Figure 4: Unit of measure of some standard Work Item field regarding task estimation

You can see from Figure 4 that all three fields related to Work Item estimation have the value pjHour to instruct project that the value contained in those field represent hours. In you select a row and press the Edit button you can edit the row and you have an additional checkbox to set the field in Publish Only mode; this will make Project never update the value from TFS.

The Groups & Permissions section permits to setup the initial security groups for Team Projects. You can create how many groups you need, and for each one you can define the access right. Each groups has a series of “allow” or “deny” related to various area of a Team Project. This section is really important, because quite often you need to adjust security based on already established rules or names in your organization. It is highly probable that you want custom groups like “developers”, “External Consultant” and so on and doing customization for each Team Project is really annoying, it is really better to configure once for all in your customized process template.


Figure 5: Management of default Security Groups for Team Project

The Lab and Build sections permit to include in Process Template custom workflow for the standard builds and for Lab Management’s build. Build customization is a really cool process, you can create build specific for a Team Project, or you can use generic template to satisfy specific requirements.

To include a new workflow you should copy the file in the appropriate sub folder of the project template called Build\Templates or Lab\Templates, once you added a file in one of the aforementioned folders, you can simply press the add button, navigate to those folder and add the default template to the process. (Figure 6)


Figure 6: How to add default custom build file to Lab or Builds section.

The Source Control section is used to choose the initial setup of the source control, like the exclusive check-out or the automatic get latest during check-out. As an example, if you have project based on VB6 and uses MSSCCI provider, you can choose to mimic the default setting of source safe. (I strongly discouraged the use of exclusive check-out and get latest on check-out on standard project).

You can also add Check-in notes as shown in Figure 7, or setup source control related permissions in the Permissions tab.


Figure 7: Modify default check-in note.

Finally the Portal and Reports sections include all documents and reports that will be create in Sharepoint and Reporting Server upon Team Project creation. As shown in Figure 8, you should insert documents in the appropriate folder on the local copy of process template


Fgiure 8: I All the base document of Sharepoint site are simply included in the process template appropriate folder and referenced in the process template definition.


Customize TFS Process Template

One of the best aspect of TFS is that it is customizable: we can interact with API, customize builds, handle events and many other interaction, but one of the most important is the ability to customize the process template.

This capability is fundamental, because permit to adapt TFS to own process, the mantra is “do not adapt your process to the tool, but adapt the tool to your process”. The purpose of an ALM tool is to support your own process, not to force the team to shape itself just to conform to the tool. The ability of a tool to adapt itself to the scenario is the key factor in choosing between various alternative. If you need a wrench you can buy the left one, that works only for a couple of bolt dimension, or you can buy the right one that is adaptable to various bolt’s dimension.

When you start using TFS you can surely start from one of the available Process Template, but usually you should do an assessment phase to understand “where you are” then decide “where you want to go”. The most common error is choosing a process template, like MSF for agile and change the way the team work to follow the template. I do not want to say that MSF for Agile is a bad process, but usually your team already has established procedures and processes and it is an error to throw everything away just because a TFS process tell us how we should work.

The good news is that you can take a process template and adapt to your need, or you can create an entire template from scratch. The first step is installing power tools, because they have a graphical Process Template editor that can give you a better editing experience.

The very first step is choosing “process Template Manager” from the Team Project Collection context menu.


Figure 1: Right click on project collection, then select Team Project Collection Settings –> Process Template manager.

Now you have the ability to choose one of the installed process templates and download its definition to local machine.


Figure 2: You can choose a process template, and download its definition to a local directory.

If you look in download directory, you will see a bunch of XML files that you can edit directly with a XML editor to change the template; if you prefer a graphical editor, power tools has a better editing experience. Just open the Tools –> process Editor –> Process Templates –> Open Process Template to open the “process Template Editor”.


Figura 3: Aprire il PTE per poter editare il processo scaricato nel passo 2.

You need to navigate to the folder where you downloaded the process template, open the processTemplate.xml file and you can start editing with a GUI tool. I’ll explain in future post how you use this editor to customize the various part of the template, stay tuned.