Customize process template experience in TFS 2013

Customizing process template is a real cool part of Team Foundation Server, because it permits you to follow the “do not adapt your process to the tool but adapt the tool to your process” scenario. There are a lot of best practices and a really good guide published by TFS Rangers, in this post I want to show how you can use a PowerShell script in a Tfs2013 Build to automatically update your Template at each push of a new definition.

First of all, whenever you customize a process template you should always store your modified process in source control, because this is the only way to track down exactly what you have changed and gives you the whole history of the customization. This is especially useful if, upgrading to a new version to TFS, the automatic process upgrade does not work and you need to reapply all your customization to the new process.

To create this demo I created a Team Project called PtCustomization based on Git repository (support for git is new in TFS 2013). The process template of the Team Project is Scrum and the first step is downloading the actual process template in a folder where I’ve cloned the repository. After the first download I immediately commit everything, so I have the original version of the template as the first commit. The next step is creating a couple of helper files

  • A powershell script that will upload all Work Item Definition to a specific Team Project
  • A personalized build to simply run a Script during a TFS build

The first file is a powershell script that will upload process template customization to the PtCustomization Team Project. Having such a script makes customization really simpler: modify the process template, run the script and the Team Project immediately reflects the modifications. Here is the script

$TeamProjectName = "PtCustomization"
$baseLocation = Split-Path -parent $PSCommandPath
$witdLocation = $baseLocation + "\scrum\WorkItem Tracking\TypeDefinitions"

$CollectionUrl = "http://tfs2013preview:8080/tfs/ExperimentalCollection"
$WitAdmin = "${env:ProgramFiles(x86)}\Microsoft Visual Studio 12.0\Common7\IDE\witadmin.exe"

$items = Get-ChildItem -Path $witdLocation 
foreach ($item in $items)
    $witd = $item.FullName
    & $WitAdmin importwitd /collection:$CollectionUrl /p:$TeamProjectName /f:"$witd"
& $WitAdmin importcategories /collection:$CollectionUrl /p:$TeamProjectName /f:"$baseLocation\scrum\WorkItem Tracking\categories.xml"
& $WitAdmin importprocessconfig /collection:$CollectionUrl /p:$TeamProjectName /f:"$baseLocation\scrum\WorkItem Tracking\Process\ProcessConfiguration.xml"

The script is really simple, it just define location of the Project Collection and the name of the Team Project, then enumerate all Work Item Definition and call Witadmin importwitd for every definition, then it imports also categories and process config.

To test the process I’ve modified definition of Task Work Item, adding another field called Original Estimate (I know that is really not Scrum like, but many people likes to have this kind of information) and modify the layout of the Work Item to actually show this new Field.


Figure 1: Adding a new Field Definition to store Original Estimate


Figure 2: Adding the new field in the Ui layout

Then I’ve created a custom build definition to run powershell uploader script during a Team Project Build. The script was created simply using the Default.xaml template for Git Project, removing all the compile and test part, leaving only the Clone part and adding a Run Script task. Basically this build does nothing that getting source and running a script. To use a custom script, you can simply commit in git source, push to the server and choose it pressing New in the Process Section of the build.


Figure 3: Change the template used for the build to use your customized process


Figure 4: You should simply browse your local repository and choose the file after you’ve pushed it to the server

Now you should be sure that the account used to run the build server has enough right to customize a process template, or you will get an error

TF237113: You don’t have enough permissions to complete the import operation.

during the build. To accomplish this you should open TFS Administration console, choose the Project Collection that contains your project and be sure that the account you are using or the Right Group has the Manage Process Template right


Figure 5: Give Manage Process Template Rights to the right group or to the user that runs the build agent

Now everything you need to do is configuring a build, choose the Script to run and the game is done, just push modification to the server and the Process Template will be automatically uploaded for you.


Figure 6: Final configuration of the process.


Figure 7: Full log of the build, output of witadmin importwitd are visible into the log.


Figure 8: Once the build is complete Process Template is automatically updated

The advantage of using Git as source control comes in hand when it is time to manage updating production Team Projects. In this scenario the PtCustomization Team Project has the main purpose to testing Process Template customization and is not used for anything else than managing this customization. Thanks to the continuous integration each push will upgrade the Template to immediately being able to test new customization, but at a certain point you should start to manage deploying those customization to real production Team Projects.

Thanks to git builds this process is really simple, suppose you have a Team Project called ProductionProjectA and you want to apply the new modified process to it. The first step is creating a Branch of the customization you’ve done.


Figure 9: Create a branch of the PtCustomization repository, and give it the same name of the Team Project you want to upgrade

Then you switch to that branch and edit the powershell script changing the name of the Team Project that will be updated. Then commit and push everything to the server.


Figure 10: Change the powershell script of the branch to point to the Team Project you want to upgrade

Finally change the build definition to monitor the new branch for continuous integration.


Figure 11: Configure the build so it will trigger an automatic build whenever there is a push on master or ProductionProjectA branch

Now if you issue another push into the ProductionProjectA branch, the process template of corresponding Team Project will be upgraded atuomatically. This is a great way to proceed, because you can try customization on Master branch, and once the customization is stable, you can automatically updates other Team Project doing a simple merge and push of the modification to the corresponding branch.

In this example I’ve created a new branch to manage updating of a single Team Project, but noone prevents you to change the script to run for multiple Team Projects. You can create a branch called Production, and change the script to upgrade all of your production Team Project. In this scenario whenever you will push into the Production branch multiple Team Project will be updated.

You can finally use TFS API to enumerate Team Projects of an entire collection, and you can create a branch of the customization for each Project Collection, so whenever you push on it, all Team Project of an entire Project Collection will be updated. This scenario is much more risky, because you should be sure that all Team Project of the collection are using the same base template.

You can download Powershell script and the customized build here.

Gian Maria.

Deep dive in Process template’s states and transitions

1 – Customize Tfs Process Template
2 – Basic of TFS Process Template Customization
3 – Adding Field to a Work Item Definition
4 – Customize Work Item Fields with Rules
5 – Interesting rules to customize work items.
6 – Customize States and Transitions of a Work Item

In previous post I did a brief introduction to the concept of States and Transitions of Work Items and it is time to do a little deep dive to understand how you can configure complex rules on transition between states. Lets introduce a new rule for our bug definition: we want to be able to move from the Triage state to Closed, only if the user is an administrator of the team project. This is a quite standard requirement because going from Triage to Closed basically means: “ignore that bug” and only an administrators should be able to take such a decision.



Figura 1: Transition from Triage to Closed is available only for Project administrators

This requirements can be achieved with little work, as you can see from Figure 1 because the transition is a securable object you can restrict the roles that can use that object. If a role has no rights to use the transition, he/she cannot do the transition between the start and destination state of the transition.

Now we want to add more complexity, we need to add another field called “rejected Reason” where we want to insert a detailed description of the reason why this bug was rejected (moved from triage do Closed). First of all we add the field and update the UI Accordingly (as seen in previous posts), The result is shown in Figure 2.



Figura 2: A field called RejectedReason was added to the Work Item Definition

We are still really far from an optimal situation, first of all the Rejected Reason field is always editable, so we can add a requirement that stats that Rejected Reason should be editable only when the bug pass from state triage to closed, because there is no meaning to have a Rejected Reason for bugs that were not rejected.

Solving this problem is really easy in TFS2010 thanks to the incredible flexibility in Wok Item configuration. We can double-click in the Triage status and open the edit details interface where we can add a series of RULES, in the same way we added RULES to single Work Item Field. RULES specified in a definition of a State are valid only when the Work Item is in that specific state.



Figura 3: Tiage state has a rule on the Rejected Reason field, in this situation I simply put the READONLY rule to make Rejected Reason not editable.

To obtain desired result, we can insert the READONLY rule to Rejected Reason field in all states, excepts for the Closed state, with this configuration the Revision Note field will be editable only when the state is Closed.



Figura 4: When I’m in Triage state the field Revision Note is Readonly, but when I move to Closed State it is editable.

This is still not perfect, because now you can add a Rejected Reason when the bug has a transition from Fixed to Closed, because the Closed state has no READONLY RULE. To obtain our goal, we need to use another cool capability of Work Item state management, adding a rule to a transition. A RULE added to a transition is applied only when the state changes using that transition. In our scenario we can simply add a READONLY rule for the Rejected Reason field to the transition that bring the Bug from Fixed to Closed, now we can edit Rejected Reason only when the state pass from Triage to Closed.



Figura 5: The Rejected Reason field has the READONLY rule applied when the state pass from fixed to closed.

As last requisite we add: when the bug moves from Triage to Closed, we want to insert automatically the value rejected into the field Resolved Reason and also we want the field Rejected Reason is mandatory when the Reason field is different from Duplicate. The reason behind this requirement is: a value of Duplicate in the Reason field already gives me information about “why” the bug was rejected, but for any other reason I want a detailed specification in the Rejected Reason on why the bug was rejected.

We can satisfy this requirement with the following steps: first of all you need to edit the Closed status, adding a REQUIRED RULE for the Resolved Reason field, then the Resolved Reason field is put in readonly in the UI (figure 6) and finally we add the Rejected value to the list of ALLOWEDVALUES.


Figura 6: Resolved Reason should be put as readonly in the UI because it will be filled automatically

We should now open the definition of the transition, select the “Fields” tab and add a COPY RULE to the field Resolved Reason to automatically change the value of Resolved Reason field during that transition.


Figura 7: Steps needed to automatically fill the value of the ResolvedReason field during the transition from Trieage to Closed.

What we did is specifying that when we apply the transition from Triage to Closed, the COPY RULE will be applied assigning the value Rejected in the Resolved Reason field and the user could not change its value because it is not editable. The COPY rule in a transition is the perfect way to automatically assign a predetermined value to some field during a transition.

Finally we need to make Rejected Reason a required field only when the value of the field Reason is different from Duplicate. This is really simple because we can simply add another RULE to the transition from Triage to Closed called WHEN NOT. This specific RULE permits to apply a series of other RULES when a condition is false and perfectly satisfies our need, because we can simply add a WHEN NOT System.Reason is equal to Duplicate to apply the REQUIRED RULE to the Rejected Reason.



Figura 8: Adding the REQUIRED RULE to the Rejected Reason field only when the System.Reason field is different from Duplicate

As you see in Figure 8, the first tab is used to specify the condition, in this example, since the rule is WHENNOT, the condition was read as "When the System.Reason is different from duplicate”; in the second tab (rules) you specify the set of RULES you want to apply then the previous condition is satisfied, in this example we specify REQUIRED rule.

Now you can create a new bug in triage status, save it and change the status in closed; now you can verify that if the Reason field is different from Duplicate, the Rejected Reason field become required.


Figura 9: The Reason is Duplicate, so the Work Item is valid, immediately after you change the Reason to Not Reproductble, the Work Item is not valid anymore because the Rejected Reason field is now REQUIRED.

You can test this rule leaving the Rejected Reason blank and noticing that as soon you change the Reason field to a value different from Duplicate the Work Item is not valid anymore and in upper part a yellow bar tells you that the field Rejected Reason could not be left blank, because it is REQUIRED.

This article can be a little complex, but it shows you the extreme flexibility you have in configuring your Work Item template to pefectly fits your process. The ability to insert RULES valid only for specific States or Transition and the special RULES WHEN and WHEN NOT permits you to create complex logic for your Work Item definition, like default values for specific transition and putting field REQUIRED or READONLY during certain transition or when the value of another field changes to a specific value.

Gian Maria.

Customize State and Transitions of a Work Item

1 – Customize Tfs Process Template
2 – Basic of TFS Process Template Customization
3 – Adding Field to a Work Item Definition
4 – Customize Work Item Fields with Rules
5 – Interesting rules to customize work items.

Now that we know how to add information to a Work Item definition, it is time to deal with “state” management. Each Work Item has a field called Status that is completely different from any other field, because has an associated workflow that manages transactions from various allowed status values. Having a workflow to manage State of a Work Item is a really powerful concept, because permits a more accurate modeling of your process. As an example suppose that in your process each bug enter the system in a status called Triage, because is new and need to be examined by someone before a developer could actually work to its resolution.

This concept comes from Emergency Room in hospitals, all people that comes in ER are set to a Triage status and someone determines priority code, do understand witch of the patients need to be examined first by a doctor. For bugs the situation is the very same, usually the bug moves from Triage to Active (Someone should fix it) but we can also choose not to fix for various reason; as an example we are not able to reproduce the bug, or simply it is too complex to fix and it is really not so important that we can postpone the fix in the next release. We can have tons of reason to immediately close the bug bypassing the Active state and surely one of the most important is The bug is duplicated. Having a duplicate bug is cause of a lot of problem so it is perfectly legal that a bug never reach the Active status. If our bug definition has no Triage concept we can customize the process template to adapt it to our way to work, thanks to concept of State and Transitions.

States represent logical states of a Work Item and is simply a list of various status string, each one identifying a valid state for the Workflow. A Transition permits to move from one state to another and we can change status only if there is a valid transition in the workflow definition. All these information can be edited with the Process Template Editor that has a good graphical editor to give us a visual image of States and Transitions.

In Figure 1 we can see the graph related to the Msf For Agile bug definition


Figure 1: State and transition of Bug definition of the MSF For agile process.

To add a new valid state we need to drag and drop a new state from the toolbox to the diagram, in Figure 2 I simply dragged a new state and changed its name in Triage.


Figure 2: A new state called Triage was added to the workflow.

Since this will be our new initial status, you should change the default transition. To do this simply right click on the transition, choose the “Open Details” menu item and you will see the Transition editor form (Figure 3), now you should simply change the To field that identify the destination of the transition.


Figure 3: The form to edit a transition, as you can see you can simply choose from and to state with a combo.

As you can see the From value is null, to identify this as the default transition so Triage will be the new default initial status of a Bug. The second tab called Reason contains the reasons that could move the bug from the original status to the destination status and contains also the list of valid reasons (enlisted in the reasons tab of the editor). This is a powerful concept, because you can always look at the Reason field an have a clue of the reason why the Work Item is in this status. In Figure 4 you can see the list of reasons associated to Bug insertion in the system.


Figure 4: Reasons associated to this transition.

For the initial status the reason represents why the bug is in the system, I decided to have three reason, the default one is signaled by tester and identify the standard bug source, a tester found a bug and inserts it into the system. But we can have bug signaled by the build system when a build fails and finally we can have bug signaled by customers (usually they have higher priority for triaging).

Now I can close the Transition editor form, right-click on the editor and choose “validate” to validate my new workflow. Actually it is not valid, and the error is:

State Active cannot be reached from the start Transition.

This happens because the default transition now points to Triage and the Active state is unreachable. You should now drag Transition objects from the toolbox to the workflow to add transition between Triage to the Active and Closed state, finally you should reach the situation of Figure 5.


Figure 5: I’ve added transition from Triage to other status, now the workflow is valid again.

After this new workflow is saved, when we create a new bug we can only specify the Triage state and one of the Three allowed reason for the default Transition (Figure 6). As you can verify the default reason is “signaled by tester”


Figure 6: The new workflow permits only the Triage status on inserting.

When you save the bug, the field Reason become Read-Only, because this field can be changed only during a change of state. Since the bug is now in the Triage status, we can change status to Active or Closed; if you choose Closed as a new status, the Reason combo become active again and shows the available reasons associated to this transition. (Figure 4 and Figure 7). If you change the new status to Active the Reason combo immediately changes to enlist the valid reason of the transition from Triage to Active.


Figure 7: Changing the status to Closed activate again the Reason field that shows only the reasons associated to the transition from the current status (Active) to the new status (Closed).

State and transition are powerful concepts that permit to implement complex workflow to model the lifecycle of various types of Work Items. I strongly suggest you to adapt the definition of your template of choice to your current process, especially for Bug and Requirement types of Work Item.



Interesting rules to customize Work Items

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

In fourth chapter we familiarized with Rules and how you can customize a Work Items adding rules to it. You can find a complete list of Rules at this link, but I want to show you the most useful ones (at least in my opinion).

Since you already know the ALLOWEDVALUES you should know the ALLOWEXISTINGVALUE a rule without parameter and is used to specify that we want to maintain a value even if it is not in the list of allowed values. This rule is useful if you change the list of available values (called PickingList) but you want to maintain old values, even if they are no more in the picking list. If you change the PickingList and you edit a work item that has an invalid value in a field, you are forced to specify a valid value to save again the element.

Another rule related to the PickingList is the PROHIBITEDVALUE that lists a series of values that are not allowed to be used in a field. As you see in Figure 1 the field is edited with a normal textbox, but if “blabla” is a prohibited value an error is shown.


Figure 1: Error value for a field that contains a prohibited value.

A third rule related to PickingList is the SUGGESTEDVALUES that contains a series of suggested values, but you can insert any value you want. When you apply this rules the editing field of the Work Item is a combo that contains all suggested values, but you can type any value you want.

The rule CANNOTLOSEVALUE states that a field once you set a valid value, could not be set to null anymore.

Another really interesting rule is called DEFAULT that permits to specify the default value of a field and it is really flexible  .


Figure 2: Specify a value taken from another field as DEFAULT.

In Figure 2 I showed a very specific situation, I choosed field in the from combo, this specify to TFS that I want to use the value of another field as DEFAULT for the field this rule is applied to. Then I choosed the System.ChangedBy field and saved the rule. Now I create another Bug based on this template, did not write anything in the new field ("Revision note”) and simply press save to save the WI. Since the Revision Note contains the rule DEFAULT that states that the default value is taken from the field ChangedBy the value is updated accordingly as shown in Figure 3.


Figure 3: The content of Revision Note was automatically filled with DEFAULT value, taken from the ChangedBy

Clearly you can specify a constant for DEFAULT, you should choose value for the field combo, and simply specify a constant value in the value textbox (Figure 4)


Figure 4: This is a “classic” default value, when the user creates another WI based on this template, the field contains this constant value.

You can use currentuser and clock as source of the default value.

Very similar to DEFAULT is the rule COPY, it is used to copy a value from a field to another during transition (I’ll speak about transition in subsequent posts).

Finally another useful rule is the MATCH, used to specify a pattern to check the validity of the content of the field..



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.