Add a Field to or Remove a Field from a Work Item Type

To add or remove a data field from a work item type, you modify the work item type definition file. You must add or remove FIELD elements from the FIELDS section as well as the layout and controls defined in the FORM section. After you have modified the work item type, you can import the XML file and begin using the updated work item type.

Important

Work item type fields are managed for a team project collection. For more information, see Managing Work Item Fields [witadmin].

In this topic

• Export and Open the Work Item Type Definition File

• Add a Field

• Remove a Field

• Import the Work Item Type Definition File

• Verify that Your Changes Appear in the Work Item Form

Required Permissions

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.

Export and Open the Work Item Type Definition File

To export and open the work item type definition file

• Perform one of the following steps based on the scope of the customization that you want to perform:

  If you are modifying a work item type for a single project:

  1. Run witadmin exportwitd to export the XML file for the work item type that you want to modify. Type the following command, substituting your data with the arguments shown:

     witadmin exportwitd /collection:http://ServerName:Port/VirtualDirectoryName/CollectionName /p:project /n:typename /f:filename
     

     For more information, see Export and Import Work Item Types from an Existing Project.

  2. In Visual Studio, click File, click Open, and then click File.

     The Open File dialog box appears.

  3. Under Look in, move to the location where you exported the file.

  If you are modifying a work item type to customize a process template:

  1. Find the location where you downloaded the process template.

  2. Select the work item type XML file that you want to update, and then click Open. When you are prompted about line endings, click No.

Add a Field

To add a field to a work item type

1. Find the following section of the XML file:

   <FIELDS>
   

2. Create a string field by typing the following XML, shown as highlighted in the following example:

   <FIELDS>
   <FIELD name="Issue Level" refname="MyCompany.MyProcess.IssueLevel" type="String" reportable="Dimension">
   </FIELD>
   

   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.

3. Find the section of the XML file that describes the work item form:

   <FORM>
   

4. Find the following lines in the <FORM> section:

   <Group Label="Classification">
     <Column PercentWidth="100">
       <Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="Area" LabelPosition="Left" />
       <Control Type="WorkItemClassificationControl" FieldName="System.IterationPath" Label="Iteration" LabelPosition="Left" />
     </Column>
   </Group>
   

5. Insert a control to display your field by typing the following XML, shown as highlighted in the following example:

   <Group Label="Classification">
     <Column PercentWidth="100">
       <Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="Area" LabelPosition="Left" />
       <Control Type="WorkItemClassificationControl" FieldName="System.IterationPath" Label="Iteration" LabelPosition="Left" />
       <Control Type="FieldControl" FieldName="MyCompany.MyProcess.IssueLevel" Label="Issue Level" LabelPosition="Left" />
     </Column>
   </Group>
   

6. On the File menu, click Save <file name>.xml to save your changes to the XML file.

7. To import the new work item type to a single project,see Import the Work Item Type Definition File. To add the work item type to your process template, see Add Type Definitions for Work Items to a Process Template.

Remove a Field

To remove a field from a work item form

1. Find and delete the definition of the field that you want removed from the work item type. The following example shows a field named "Issue Level". To remove this field, you delete the following field section:

   Note

   The field section in your XML file may not contain all the elements in the following code. However, if you have customized the work item type field to include these elements, they must be also deleted.

   <FIELDS>
   . . .
   <FIELD name="Issue Level" refname="MyCompany.MyProcess.IssueLevel" type="String" reportable="dimension">
   <HELPTEXT>Describes the issue level to which this special task belongs.</HELPTEXT>
     <WHEN field="Microsoft.VSTS.Common.Discipline" value="Business Analyst">
       <ALLOWEDVALUES>
         <LISTITEM value="Planning" />
         <LISTITEM value="Review" />
       </ALLOWEDVALUES>
     </WHEN>
     <WHENNOT field="Microsoft.VSTS.Common.Discipline" value="Business Analyst">
       <ALLOWEDVALUES>
         <LISTITEM value="Process Management" />
         <LISTITEM value="Planning" />
         <LISTITEM value="Execution" />
         <LISTITEM value="Review" />
       </ALLOWEDVALUES>
     </WHENNOT>
   </FIELD>
   …
   </FIELDS>
   

2. Find the <Layout> section where the control for the work item field is defined, and delete the appropriate sections to remove the field. The following highlighted sections are examples of what you should look for.

   <Group Label="Classification">
     <Column PercentWidth="50">
       <Group>
         <Column PercentWidth="100">
           <Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="Area" LabelPosition="Left" />
           <Control Type="WorkItemClassificationControl" FieldName="System.IterationPath" Label="Iteration" LabelPosition="Left" />
         </Column>
       </Group>
     </Column>
     <Column PercentWidth="50">
       <Group>
         <Column PercentWidth="100">
           <Control Type="FieldControl" FieldName="MyCompany.MyProcess.IssueLevel" Label="IssueLevel" LabelPosition="Left" />
         </Column>
       </Group>
     </Column>
   </Group>
   

3. On the File menu, click Save <file name> to save changes to the XML file.

Import the Work Item Type Definition File

To import the work item type definition file

• Run witadmin importwitd to import the XML file for the work item type that you modified. Type the following command, substituting your data with the arguments shown:

  witadmin importwitd /collection:http://ServerName:Port/VirtualDirectoryName/CollectionName /p:project /n:typename /f:filename
  

  For more information, see Export and Import Work Item Types from an Existing Project.

Verify that Your Changes Appear in the Work Item Form

To verify changes imported to a single project

1. In Team Explorer, right-click the node of the team project that contains the work item type definition that you modified, and click Refresh.

   The latest updates are downloaded from the server, including the changes that you just imported. Wait several seconds until the Work Items node is refreshed. Nodes that are still loading display the word working.

2. Create a work item using the work item type that you modified by right-clicking the Work Items node, pointing to Add Work Item, and then clicking the work item type.

   The work item is created from the work item type that you changed.

3. Verify that the changes you made appears in the work item form.

4. Click Close to close the new work item. Click No when you are prompted to save the work item.

See Also

Reference

Customizing and Managing Work Item Types [witadmin]

FIELD (Definition) Element

Control XML Element Reference

Concepts

Working with Work Item Fields

Other Resources

Defining Work Item Fields