Change a TFS Work Item Definition

December 19, 2016

Let’s assume that the built-in TFS standard templates are not sufficient for you. You’re in luck: TFS allows you to create your own custom work item. Let’s imagine that, for some reason, you want a work item type called “Defect”, rather than “Bug”. Here’s the process, based on the “Bug” work item type.

First thing is to open the command prompt in administrator mode, and navigate to a work directory; for example, the “Documents” folder . Then export the template work item type, like so (you can export the entire definition of all work items, but it becomes unmanageable):

[code lang=“DOS”] witadmin exportwitd /collection:http://tlaptop:8080/tfs/DefaultCollection /p:“TFSSandbox” /n:Bug /f:Defect.xml




![customwi1](images/CustomWI1.png)

Check your working directory:

![customwi2](images/CustomWI2.png)

Now, open the XML file.  I used Notepad++, but you can use Notepad or vi, or whatever.  To change the work item, change the name attribute; once you've done this, you have a new work item type:

![customwi3](images/CustomWI3.png)

Now, you can add the fields that you want.  I'm adding a field called "pcm.CustomField":
```xml
<?xml version="1.0" encoding="utf-8"?>
<witd:WITD application="Work item type editor" version="1.0" xmlns:witd="http://schemas.microsoft.com/VisualStudio/2008/workitemtracking/typedef">
  <WORKITEMTYPE name="Defect">
    <DESCRIPTION>Customised defect</DESCRIPTION>
    <FIELDS>
      <FIELD name="Iteration Path" refname="System.IterationPath" type="TreePath" reportable="dimension">
        <HELPTEXT>The iteration within which this bug will be fixed</HELPTEXT>
      </FIELD>
	  <FIELD name="New Field" refname="pcm.CustomField" type="Integer" />
      <FIELD name="Iteration ID" refname="System.IterationId" type="Integer" />

The field name attribute (“New Field” in this case) tells TFS how to refer to this field to the user. This is important, because if you forget that you’ve called it “New Field”, you might assume this hasn’t worked and start googling to find out why.

Now you’ve told TFS that you have a field to store; the next step is to add that field to the layout:

    <FORM>
      <Layout HideReadOnlyEmptyFields="true" HideControlBorders="true">
        <Group Margin="(4,0,0,0)">
          <Column PercentWidth="90">
            <Control FieldName="System.Title" Type="FieldControl" ControlFontSize="large" EmptyText="&lt;Enter title here&gt;" />
          </Column>
          <Column PercentWidth="10">
            <Control FieldName="System.ID" Type="FieldControl" ControlFontSize="large" />
          </Column>
        </Group>
     <Group Margin="(10,0,0,0)">
          <Column PercentWidth="60">
            <Control FieldName="pcm.CustomField" Type="FieldControl" Label="Custom Field Here" ControlFontSize="large" EmptyText="&lt;Custom field here&gt;" />
          </Column>		
    </Group>
        <Group Margin="(10,0,0,0)">

As you can see, we can move this about and pretty much show anything we want here. Next, re-import:

[code lang=“DOS”] witadmin importwitd /collection:http://tlaptop:8080/tfs/DefaultCollection /p:TFSSandbox /f:Defect.xml




![customwi5](images/CustomWI5.png)

**Using the new Work Item Type**

And now we have a new work item type:

![customwi6](images/CustomWI6.png)

And the new field is available:

![customwi7](images/CustomWI7.png)

**Using The Field in a Query**

![customwi8](images/CustomWI8.png)

References

[Tutorial on modifying Work Item States](https://visualstudiomagazine.com/articles/2011/09/23/modifying-work-item-states.aspx)

[Tutorial on customising TFS 2013](https://www.simple-talk.com/dotnet/visual-studio/customizing-team-foundation-server-2013/)

[Detailed definition of the FIELD tag](https://msdn.microsoft.com/Library/aa337627.aspx?f=255&MSPPError=-2147217396)

[Turotial on modifying the FIELD tag](https://www.visualstudio.com/en-us/docs/work/customize/add-modify-field)