Add a Field and Change the Layout of an Existing Work Item Type

Article
12/03/2012

To track additional data for a work item, you can add a field to a work item type, display it on the work item form, and make it reportable. You can also change the layout of a work item form to best suit your team's needs. In this topic, Julia and Peter, members of the Fabrikam Fiber team, customize two different types of work items to support their tracking goals.

To track where requests for new features originate, Julia adds a custom field with a drop-down menu of options and changes the layout of the work item form for the product backlog item. Julia performs five tasks to add a custom field with a drop-down list of options and to change the layout of the work item form for the product backlog item.
To better track work and improve on his and the team’s ability to estimate work, Peter adds a field to the task work item type.

As the following illustration shows, Julia and Peter perform their tasks independently, but in a prescribed sequence.

Change the layout of a work item form

Sequence to add a field to a work item type

Add a field to a work item form

Add a field to a work item type

To review work item fields and fields assigned as reportable in the default process templates for Team Foundation Server, see Work Item Field Reference for Visual Studio ALM and Reportable Fields Reference for Visual Studio ALM.

Requirements

To perform this procedure, you must be a member of the Team Foundation Administrators group or a member of the Project Administrators group for the project. For more information, see Team Foundation Server Permissions.

Note

If you are running Windows Vista you might not have permissions set for certain folders. If you try to export the work item type to a location where you do not have permissions set, the registry virtualization technology automatically redirects the exported file and saves it to the virtual store. To avoid this redirection, you can export the file to a location where you have permissions set. For more information about registry virtualization, see the following pages on the Microsoft website: Registry Virtualization and Common file and registry virtualization issues in Windows Vista.

1. Export a work item type definition

When you download the type definition from your team project, you ensure that you're working with the latest version.

Note

If you have minor changes and are comfortable working with the XML format, you can modify files by using Notepad or another text editor. Or, you can use the Process Editor, which is a power tool that is installed as an add-in to Visual Studio. Using this tool, you don’t have to import or export the type definitions. Instead, you can open them using the Process Editor and modify them through the editor interface.

You can download the power tool from the following page on the Microsoft Web site: Team Foundation Server Power Tools.

For information about how to download the schema files for process templates, see Index to XML Element Definitions for Process Template Plug-ins.

To export a work item type definition file from an existing team project

To run the witadmin command-line tool, open a Command Prompt window where either Visual Studio or Team Explorer is installed and enter:
```
cd %programfiles%\Microsoft Visual Studio 11.0\Common7\IDE
```
On a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%.
Enter the following command, substituting your data for the arguments that are shown here, where CollectionURL specifies the URL of a team project collection, ProjectName specifies the name of a team project defined within the collection, WorkItemTypeName specifies the name of the work item to export, and FileName specifies the name and location for the exported file to export. Then choose the Enter key.
```
witadmin exportwitd /collection:CollectionURL /p:ProjectName /n:WorkItemTypeName /f:FileName
```
Example: Export the Definition for the Product Backlog Item

For example, Julia uses the following command to export the type definition for her FabrikamFiber team project for the product backlog item to FF_ProductBItem.xml.
```
witadmin exportwitd /collection:http://julia-fabrikam:8080/tfs/Collection1 /p:"FabrikamFiber" /n:"Product Backlog Item" /f:FF_ProductBItem.xml
```
Example: Export the Definition for Task

And Peter uses the following command to export the type definition for the task and save it to the file labeled FF_Task.xml.
```
witadmin exportwitd /collection:http://julia-fabrikam:8080/tfs/Collection1 /p:"FabrikamFiber" /n:Task /f:FF_Task.xml
```
Upon successful completion, the following message appears:

Operation complete.

2. Add a field to a type definition

To add a field to a type definition, you must add a FIELD element within the FIELDS section and a Control element within the FORM section. Also, we recommend that you adhere to the naming conventions established for fields.

To add a field to a work item type

Locate the section of the XML file that defines the fields for the type and that begins with FIELDS.
Add the FIELD element that specifies the name of the custom field to add. You must specify the following required attributes: friendly name, refname (reference name), and type. For more information, see FIELD (Definition) Element.

Note

The Reference Name, or refname, is the programmatic name for the field. All other rules should refer to this refname. For more information, see Naming Conventions for Work Item Tracking Objects.

Example: Add a Custom Field with a Menu List

For example, Julia enters the following text to add the custom field, Requestor, with a reference name of FabrikamFiber.MyTeam.Requestor, to the type definition for the product backlog item. She also specifies the pick list of allowed values for this field as well as the default value of Customer for the list.
```
<FIELD name="Requestor" refname="FabrikamFiber.MyTeam.Requestor" type="String" reportable="Dimension">
   <ALLOWEDVALUES>
      <LISTITEM value="Customer" />
      <LISTITEM value="Executive Management" />
      <LISTITEM value="Other" />
      <LISTITEM value="Support" />
      <LISTITEM value="Team" />
      <LISTITEM value="Technicians" />
      <DEFAULTVALUE value="Customer" />
    </ALLOWEDVALUES>
</FIELD>
```
For more information about pick lists, see Define Pick Lists.

Example: Add a Predefined Field

For the type definition for task, Peter adds the predefined field, Completed Work, with a reference name of Microsoft.VSTS.Scheduling.CompletedWork.
```
<FIELD name="Completed Work" refname="Microsoft.VSTS.Scheduling.CompletedWork" type="Double" reportable="measure" formula="sum" />
```
For a list of all predefined fields, see Work Item Field Reference for Visual Studio ALM.

Add the CONTROL element within the FORM section so that the custom field appears on the work item form within the group of elements where you want it to appear. You must specify the control type attribute. For more information, see Control XML Element Reference.

Example: Add the Custom Field to the Form for the Product Backlog Item

Example: Add the Control Element for a Field

For example, Julia adds the Control element for the Requestor field to appear below the Reason field on the work item form, as shown in the following code sample.

<Column PercentWidth="50">
   <Group Label="Status">
      <Column PercentWidth="100">
         <Control FieldName="System.AssignedTo" Type="FieldControl" Label="Assi&amp;gned To:" LabelPosition="Left" />
         <Control FieldName="System.State" Type="FieldControl" Label="&amp;State:" LabelPosition="Left" />
         <Control FieldName="System.Reason" Type="FieldControl" Label="Reason:" LabelPosition="Left" ReadOnly="True" />
         <Control FieldName="FabrikamFiber.MyTeam.Requestor" Type="FieldControl" Label="Requestor:" LabelPosition="Left" ReadOnly="True" />
      </Column>
   </Group>
</Column>

Tip

The schema definition for work item tracking defines all child elements of the FORM element as camel case and all other elements as all capitalized. If you encounter errors when validating your type definition files, check the case structure of your elements. Also, the case structure of opening and closing tags must match according to the rules for XML syntax.

The following illustration shows that the work item form for the product backlog item now contains the new field.

Custom field added to type definition and form

Example: Add the Predefined Field to the Form for Task

For the task work item, Peter adds the Control field to appear above the Remaining Work field as shown in the following code sample:

<Column PercentWidth="50">
   <Group Label="Details">
      <Column PercentWidth="100">
         <Control FieldName="Microsoft.VSTS.Scheduling.CompletedWork" Type="FieldControl" Label="Completed Work:" LabelPosition="Left" />
         <Control FieldName="Microsoft.VSTS.Scheduling.RemainingWork" Type="FieldControl" Label="Remaining Work:" LabelPosition="Left" />
         <Control FieldName="Microsoft.VSTS.Common.BacklogPriority" Type="FieldControl" Label="Backlog Priority:" LabelPosition="Left" />
         <Control FieldName="Microsoft.VSTS.Common.Activity" Type="FieldControl" Label="Activity:" LabelPosition="Left" />
         <Control FieldName="System.AreaPath" Type="WorkItemClassificationControl" Label="Area:" LabelPosition="Left" />
      </Column>
   </Group>
</Column>

The following illustration shows that the work item form for task now contains the Completed Work field.

Add Completed Work to Task type and form

Save your changes to the XML file.

To learn more about adding work item fields to type definitions

3. Change the form layout for tab groups from two columns to a single column

Julia wants to change the form layout for the product backlog item so that the Description field spans the width of the form. As the following illustration shows, the default layout displays two sets of tab groups. To change the layout to a single set of tab groups, Jill needs to change the first Column element to 100 percent width, and remove the extraneous Column and TabGroup elements from the FORM section.

Two-colum tab group layout

To change the form layout from two-column tab groups to a single column of tab groups

Find the TabGroup section of the XML file. Notice that there are Tab elements for items such as Description, Tasks, Acceptance Criteria, and History in which each Tab element contains a Control element that renders the respective control.

<Group>
   <Column PercentWidth="50">
      <TabGroup>
      . . .
      </TabGroup>
   </Column>
   <Column PercentWidth="50">
      <TabGroup>
      . . .
      </TabGroup>
   </Column>
</Group>

Consolidate all of the <Tab> . . . </Tab> elements under one TabGroup. Remove the Group, Column, and extraneous TabGroup elements. The following example shows the new XML syntax structure.
```
<Group>
   <Column PercentWidth="100">
      <TabGroup>
      . . .
      </TabGroup>
   </Column>
</Group>
```
Note

For best results, every control or group should display in a column even if the column spans the full width of the form. In turn, every column should display in a group even if the group has no visible label or boundary. For more information, see Design and Customize a Work Item Form.

The following illustration shows the single-column tab groups.
Save the changes to the XML file.

4. Import a work item type definition

After you’ve customized the type definition, you must import it to your team project to verify your changes and make it available for use. The XML file that you import will overwrite the contents of the current type definition. The import process validates the XML syntax prior to upload.

To import a work item type to an existing team project

From the command prompt window and directory specified in step 1, Export a Work Item Type Definition, described previously in this topic, enter the following command, and then choose the Enter key.
```
witadmin importwitd /collection:CollectionURL /p:ProjectName /n:WorkItemTypeName /f:FileName
```
Example: Import the Definition for the Product Backlog Item

For example, Jill uses the following command to import the type definition for the product backlog item she exported to FF_ProductBItem.xml to the FabrikamFiber team project.
```
witadmin importwitd /collection:http://julia-fabrikam:8080/tfs/Collection1 /p:"FabrikamFiber" /f:FF_ProductBItem.xml
```
Example: Import the Definition for Task

And Peter uses the following command to import the type definition for the task that he saved to FF_Task.xml.
```
witadmin importwitd /collection:http://julia-fabrikam:8080/tfs/Collection1 /p:"FabrikamFiber" /f:FF_Task.xml
```
Upon successful completion, the following message appears:

The work item type import has been completed.

5. Refresh the team project and verify changes made to a type definition

After importing a type definition, you must refresh your cache in Team Explorer for the changes to be available. You must refresh the cache only if you have had Visual Studio open and connected to Team Foundation Server when you imported the type definitions.

Refresh Team Explorer and create a product backlog item

Refresh team project and verify changes

To refresh your cache

In Team Explorer, choose the Refresh button.

The latest updates are downloaded from the server, including the changes that you just imported.

Wait several seconds until the refresh completes.
Choose Work Items.
Choose New Work Item, and then choose the work item type that you modified, such as Product Backlog Item or Task.
Verify that the changes you made appear in the work item form.
Choose the Close button to close the new work item. Choose the No button when you are prompted to save the work item.