Development and Related Work missing on new UI form after upgrade to TFS 2017

I’ve dealt on How to enable the new work Item in TFS 2017, and you could have noticed some differences from Visual Studio Team Service Work Item layout, or even with new Team Projects created after the upgrade. In Figure 1 you can see in the left the detail of a PBI on a Team Project that exists before the upgrade to TFS 2017, in the right the PBI on a Team Project created after the upgrade.


Figure 1: Differencies of Work Item Form between Team Projects

This difference happens because the script that upgrade the Process Template to use the new form, does not add some part that are indeed present in newer Process Template. In the end you can be annoyed because new Team Project have different layout than existing ones. The solution is quite simple.

First of all install the Team Process Template Editor Extension for Visual Studio 2017, this will easy the process because will avoid resorting to command line. Now, as you can see in Figure 2, you should be able to use the menu Tools –> Process Editor –> Work Item Types that contains two commands: Import WIT and Export WIT.


Figure 2: Commands to import and export Work Item Definition of a Team Project directly inside VS

Process Template Editor will save you some command line details

With these two command you can export the definition of Work Items from a Team Project to your local disk (Export), then you can modify the definition and upload modified version to Team Project again (Import). If you choose Export, it will made you connect to a Project Collection, then choose the Team Project you want to use, and finally choose the Work Item Type, in my situation I’ve choose User Story Work Item Type and saved it to disk. When the export asks you to include the Global Definition List, please answer no.

It will be a good idea to save everything to a source controlled folder, so you can verify how you modified the Work Item Definition during the time.

After you downloaded the Work Item Definition of the Team Project you want to fix, Export the very same Work Item Definition, from a Team Project that was created after the upgrade to TFS 2017. It could be simpler instead to download the entire process template definition from the server and look for the Work Item Definition you need. Since I need to modify several Work Item Type definition, not only User Story, I decided to download the entire Process Template for the Agile definition


Figure 3: How to download an entire process template directly from Visual Studio.

The menu Team –> Team Project Collection Settings – > Process Template Manager will do the trick; this command will open a dialog with all the Process Template Definition and I simply grab the Agile (default) and download to a source controlled folder.

Now you should have two file User Story.xml, the first one of the TP that was upgraded (the one that missing the Development and Related Work UI Section) and the other is the one of the Process Template Definition, that contains the sections you miss.

You can just compare them with whatever tool you prefer. The result is that the two files usually are really different, but we do not care for now about all the differences, we can just scroll to the bottom to find the definition of the layout of the new UI as you can see in Figure 4.


Figure 4: Different UI definition section between existing and new Team Project

In the left we have Status and Planning section, while on the right we have planning and development, the two missing parts we want to see in our new Work Item Form Layout are instead on the new definition. Now you only need to adjust the layout on the left to make it include the missing two section. In Figure 5 is shown how I modified the file.


Figure 5: Modified Process template

You can rearrange the form as you like, as you can see I’ve made it equal to the one of the latest version of the Process Template, except that I left the Story Point in the Planning section.

Once you are done, you can use the Import WIT function from Visual Studio 2017 to upload the new definition to the Team Project you want to modify. If you made errors the Work Item Definition will not be imported, so you do not risk to damage anything.

If the import went OK, just refresh the page in the browser and you should immediately see the new layout in action, Development and Related Work section are now visible. You can also rearrange the UI if you like to move information in a way that are more suitable to your needs.

Now repeat the very same procedure for Features, Epics, Task and whatever Work Item Type that miss some section respect a newly created process template.

If you need to do this procedure for more than one Team Project, you need to repeat all the steps if the other Team Project is based on a different template (Agile, SCRUM, CMMI) or it contains different customization.

It is always a good procedure to always export the actual definition of a Work Item before starting to modify it, to avoid messing up the template.

If you did a good work and stored all customization into source control, you still need to export the definition from the template, to verify if the definition was changed from the latest time you modified it. Even if you are sure that the latest customizations are in source control, remember that when you upgrade TFS it could be possible that Process Template Definition was upgraded to enable new features (as for the new Work Item Layout Form).

Gian Maria Ricci

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..