Understanding TFS Process Customization in Details- Series

Update Feburay 22, 2015
TFS 2015 with udpate 1, WorkItemChanges table is renamed tbl_WorkItemCoreWere and Fields is renamed tbl_Field

 End of update

*****************************************

3 years ago I wrote a blog post about Customizing TFS Process 2010, this was a basic customization, today I will deep dive with more details about TFS Customization Process.

In this blog series I will explain TFS Process Customization in details, I will try to explain what happen behind the scene, show common errors that happen when we perform customization and answer many questions that could come for anyone perform TFS Process Customization, this series consist of following parts:

Each part consist of one or many sections as needed.

=================================================================================

Part 1 – Working with Fields

I will start by introducing working with fields, there are many questions come in our mind when we start working with fields like:

  • Why we need to create a filed?
  • What is happening when we create a new field?
  • Is the field exist per project or collection?
  • Can we using field multiple times for different work items?
  • Can we have 2 fields with same name? Or with the same reference name?
  • Can we change the data type of an existing field?
  • Can we know which fields are not used anymore?
  • If we delete a filed from WID (Work Item Definition) or Global Workflow is it deleted from our DB?
  • Can we delete fields?
  • If I remove a field from WID and it has data in DB and return it back did I get the data back?
  • Can we enhance queries speed using our new fields?

So first, here is the existing reference for all fields that come with TFS, Work item field reference for Visual Studio ALM

  • Why we need to create a filed?

This is very important question because some people think that we create a field so we can add that field to the Work-Item form so user can enter data for it, yes that’s true but also sometimes we create filed without needing to show it on the form, maybe we will track some values in that filed during the workflow or maybe during the form data changes, so not every fields added will be added to the form.

  • What is happening when we create a new field?

We simply create a new field by open TFPT (Microsoft Visual Studio Team Foundation Server 2013 Power Tools ) Process Editor from Visual Studio and open a Work Item from file or from server and go to Fields and click New, we will need to provide Name and Reference Name,  also we will need to choose a Data Type as well.

2-12-2014 3-34-53 PM

We can also create fields by export WID (Work Item Definition) add new field and then import WID to the desired project, or by using Global Workflow Definition, or the GUI using Process Editor and click save.

As we can see in the follwing  WID (Work Item Definition), it has 3 sections FIEDLS, WORKFLOW and FORM, adding field will add this field to the FIELDS section with FIELD element and all rules will be inside that element

[code language=”xml”]
<WORKITEMTYPE name="Product Backlog Item">
<FIELDS>
<FIELD name="Radwan Value3" refname="Radwan.Value3" type="String">
<Rule1></Rule1>
<Rule2></Rule2>
</FIELD>
</FIELDS>
<WORKFLOW>…..</WORKFLOW>

<FORM>…..</FORM>

</WORKITEMTYPE>
[/code]

TFS will create that field inside 11 views to track Work Items changes and updates for that field and of course other fields as well but this only happen for all data type expect PlainText and HTML because they are not a physical columns in the DB like the other fields and this is why we only be able to change data types between PlainText and HTML as we will see later on this post.

2-12-2014 3-57-35 PM

These are the views  affected by creating 2 fields

2-12-2014 1-55-56 PM

 So let’s see some of that views in more details

View  WorkItemChanges
It keeps all the recodes of the WI changes except (without) the last update and it shows under each field the last value if the field changed or NULL if the field not changed, in other word it only shows values if this field changed in the last update, see the following image. 

2-12-2014 1-52-02 PM

View  WorkItemsUpdate

It keeps the last record of the WI changes, see the following image.
2-12-2014 2-11-05 PM-2

 View  WorkItemsLatestUsed

It keeps the last record of the WI changes

View  
WorkItemsAreUsed

It keeps the last record of the WI changes

View  WorkItemsQueryEverable

It keeps all the recodes of the WI changes including the last one.
2-12-2014 1-47-29 PM-3

  • Is the field exist per project or collection?

Fields are created per DB or TFS Collection, see the following image that illustrate the scope of different object across TP and TP Collection.

IC548825
2-12-2014 2-06-30 PM

So let’s see some rules that you need to consider while creating a new field in TFS Work Item

  • Can we using field multiple times for different work items?
  • Can we have 2 fields with same name? Or with the same reference name?

You can add the same field for different Work Items as long as needed but you need to use the same Reference Name and Name that you used in the first time create that field, TFS will understand that it’s the same field you created earlier and will not create a new field, you can have different values for the following attributes for the same filed inside different Work Item like:

  • Label or the name that displays on the work item form
  • The help text
  • The allowed values within a drop-down menu

You can’t have 2 fields with the same Reference Name per collection, and if you try to save a field that already exists with the same Reference Name but you try that with different Name, TFS will worrying you that you are trying to rename an existing field, you will see the following error.
2-12-2014 3-06-26 PM

Also you can’t have 2 fields with the same Name per collection, and if you try to save a field that already exists with the same Name but you try that with different Reference Name, TFS will worrying you that this Name already used with an existing field or Reference Name, you will see the following error.
2-12-2014 3-20-52 PM

  • Can we change the data type of an existing field?

If you add a field with certain data type and saved that field, you can’t change its data type and if you try to do that you will see the following error message.

2-13-2014 11-34-45 AM

You can only change data type from HTML to PlainText or PlainText to HTML and you can’t even use Process Editor (GUI) to do that, it’s only available from the command line tool (witadmin changefield) we can use also that command for make the field synchronizing with Active Directory in case that filed store names like created by, approved by so instead of just using static text the text will be sync with AD.

[code language=”powershell”]
witadmin changefield /collection:http://vsalm:8080/tfs/MyCollection
/n:Radwan.Value1 /type:PlainText

[/code]

  • Can we know which fields are not used anymore?

We can use (witadmin listfields) to list all fields and this will show if the filed are used or not and also we can use the option of (/unused) to only display fields that are not used

  • If we delete a filed from WID (Work Item Definition) or Global Workflow is it deleted from our DB?
  • Can we delete fields?
  • If I remove a field from WID and it has data in DB and return it back did I get the data back?

Removing a field from WID or Global workflow will not delete the field form the DB even if it has not any data.

We use (witadmin deletefiled) to delete fields from the DB but first we need to make sure that this field are not used, we using  (Witadmin listfields) to know that and then remove that filed from the form (Layout) if it exist and then remove it from the field list in the WID.

If we remove the filed form WID without deleting it using  (witadmin deletefiled) then we can return it back as all data are still there in the DB and linked to WI by ID

Remember if you delete a field, you will need to rebuild TFS Data warehouse to update the reports by removing its value

  • Can we enhance queries speed using our new fields?

We have a command (witadmin indexfiled) we can use to index our field so it can increase quires speed using this field.

Links:

Work Item Field Attributes – What You Can and Can’t Change

Everything about TFS2013 customization

Share This: