Add or modify a work item type
TFS 2017 | TFS 2015 | TFS 2013
You can modify an existing work item type or add a custom work item type based on your team's tracking requirements or workflow processes. The most common reasons to modify a work item type are to add or modify the set of fields or field rules, change the workflow, or customize the work item form.
See Add or modify a field if you want to add a custom field or modify the field rules or attributes of an existing field.
Most work item type customizations are made to the work item type XML definition, however, other customization are made through the Process Configuration definition or through the witadmin command line tool.
For Azure DevOps Services or for collections that use the Inherited process model, see Add and manage work item types.
Work item type definition
- Add or modify a field to an existing work item type
- Add a custom work item type, modify a work item type
- Change the workflow (states, reasons, transitions)
- Modify the work item form
- Specify the work item type color
- Specify the work item type icon (TFS 2017.2 and later versions)
- Specify the workflow state color
- Add or remove a work item type from the backlog or task board
- Add a custom work item type to a backlog or board
- Add a portfolio backlog
Command line change
- List work item types
- Deactivate or disable a work item type
- Rename a work item type
- Delete a work item type
To get added as an administrator, see Change project collection-level permissions.
How do modifications to work item types affect existing work items?
The following table summarizes the effect on existing work items when you modify fields or work item type definitions.
|Action||Effect on existing work items|
|Remove fields from a work item type||Data for the removed fields remains in the data store. However, no new data can be added, because you've removed them from the work item type definition.|
|Rename a field||Data for the renamed fields remains in the data store under the new friendly name.|
|Delete fields||Data for the deleted fields is removed from the data store.|
|Rename a work item type||All data remains intact under the new name.|
|Delete a work item type||All data for work items created as the deleted work item type is permanently removed with no chance for recovery.|
If you want to completely remove the fields from the data store, use
witadmin deletefield command line tool.
Import and export work item type definition files
If you use the Hosted XML process model, you need to import and export the process template used by your project. For details, see Customize the work item tracking web form.
If you don't have administration permissions for your project, get them.
- Open a Command Prompt window according to the instructions provided in witAdmin: Customize and manage objects for tracking work. For example:
Export the work item type definition file where you want to modify or add a field. Specify the name of the work item type and a name for the file.
witadmin exportwitd /collection:CollectionURL /p:ProjectName /n:TypeName /f:"DirectoryPath/FileName.xml"
An example of a CollectionURL is
Edit the file. For details, see Index to XML element definitions.
Import the definition file.
witadmin importwitd /collection:CollectionURL /p:ProjectName /f:"DirectoryPath/FileName.xml"
Open the web portal or refresh the page to view the changes.
For more information about using
witadmin, see Import, export, and manage work item types.
Add or modify a work item type
To add a custom work item type or modify an existing work item type, you define or modify the XML definition file and then import it to your project based on the process model you use. You modify a work item type by specifying the elements defined within the three main sections of the definition file: FIELDS, WORKFLOW, and FORM.
The easiest way to add a new work item type is to copy an existing work item type and then modify the definition file.
Add or modify a field, field rule, label, or empty text
Any field that you want to use to track data must be added to the definition file. This is true for all but system fields (fields whose reference name start with System.). All System fields are defined for all work item types, whether or not you include them in the work item type definition. To learn more about each field, see Work item field index.
You add fields and field rules to the FIELDS section. For the field to appear on the work item form, you must also add it to the FORM section of the definition.
For example, to add the work item ID to a form, specify the following XML syntax within the
<Control FieldName="System.ID" Type="FieldControl" Label="ID" LabelPosition="Left" />
To learn more about defining fields, see Add or modify a field.
Modify the workflow
STATES and REASONS sections within the WORKFLOW specify the pick list values in the State and Reason fields. They track the status of work items. The TRANSITIONS section specifies the valid transitions between states, as shown in the following illustration. You specify both forward and regressive transitions.
You change the workflow to accomplish the following objectives:
- Add or remove a state, reason, or transition
- Specify a value for field to be applied during a change in state, reason, or transition
- Specify a custom ACTION to automate field assignments based on a change in state, reason, or transition.
When you customize the workflow, follow these two steps:
This second step is required when you change the workflow for a work item type that appears on an Agile tool page. These work item types belong to either the Requirement or Task categories.
Workflow field rules
You can apply field rules when you change state, specify a reason, or during a workflow transition.
For example, by adding the EMPTY rule when the state is set to Active, you can automatically nullify the Closed Date and Closed By fields and make them read-only. This is useful when reactivating a work item from a closed state.
<STATE value="Active"> <FIELDS> . . . <FIELD refname="Microsoft.VSTS.Common.ClosedDate"><EMPTY/></FIELD> <FIELD refname="Microsoft.VSTS.Common.ClosedBy"><EMPTY/></FIELD> </FIELDS> </STATE>
Apply workflow field rules to accomplish the following actions:
- Qualify the value a field can have by specifying CANNOTLOSEVALUE, EMPTY, FROZEN, NOTSAMEAS, READONLY, and REQUIRED
- Copy a value into a field by using COPY, DEFAULT, and SERVERDEFAULT
- Restrict who can modify a field
- Enforce pattern matching on a string field by using MATCH
- Conditionally apply rules based on values in other fields using WHEN, WHENNOT, WHENCHANGED, and WHENNOTCHANGED
- Limit rules to apply to specific users or groups. Most rules support the for or not attributes to focus who the rule does and doesn't apply to.
Customize the work item form
The following illustrations highlight the most common elements on work item forms. You can customize all of them except the title area and form controls. The elements you use to customize the form depend on whether or not the new form has been enabled by your admin.
Web form with the new form enabled (VSTS, TFS 2017)
Old web form in use (TFS 2015, TFS 2013)
You can customize the form to accomplish the following objectives:
Add or remove a work item type from the backlog or task board
The Agile planning tools—product backlog, sprint backlog, and task board pages—display specific work item types based on the process template used to create your project. You can add or remove work item types to appear on these pages. For example, if your project uses Scrum work item types, both product backlog items and bugs appear on the backlog pages. However, if your project was created using the Agile, CMMI, or other process template, bugs don't appear on your backlog or task board.
For example, you can add bugs from the product backlog page.
The images you see from your web portal may differ from the images you see in this article. These differences result from updates made to Azure DevOps Services or your on-premises deployment. However, the basic functionality available to you remains the same unless explicitly mentioned.
To learn how to add or remove work item types from the backlog or task board, see Add a work item type to a backlog and board. To add a new work item type to support a portfolio backlog, see Add a portfolio backlog level.
Change the type of an existing work item
See Move, change, or delete work items for the features available to you based on your platform.
When you connect to TFS, you can't change the work item type for an existing work item, but you can copy the work item and specify a new type. For instance, you can copy an existing product backlog item and change the type to bug, as shown in the following illustration.
Also, if you have several work items with type changes you want to make, you might want to export them using Excel, and then re-add them as a new type.
Deactivate or disable a work item type
If you want to restrict creation of a specific work item type to a group of users, add the work item type to the Hidden Categories group to prevent the majority of contributors from creating them. If you want to allow a group of users access, you can create a hyperlink to a template that opens the work item form and share that link with those team members who you do want to create them.
You can't add field rules to restrict the workflow as you can't apply rules to system fields.
Delete a work item type
To prevent team members from using a specific work item type to create a work item, you can remove it from the project. When you use
witadmin destroywitd*, you permanently remove all work items that were created using that work item type as well as the work item type itself. For example, if your team doesn't use "Impediment", you can delete the work item type labeled "Impediment" from the Fabrikam Web Site project.
witadmin destroywitd /collection:"http://FabrikamPrime:8080/tfs/DefaultCollection" /p:"Fabrikam Web Site" /n:"Impediment"
When you delete a work item type that belongs to a category, you must update the categories definition for the project to reflect the new name. For more information, see Import, export, and manage work item types and Import and export categories.
Rename a work item type
To rename an existing work item type use
witadmin renamewitd. For example, you can rename a work item type labeled "QoS Item" to "Service Agreement."
witadmin renamewitd /collection:"http://FabrikamPrime:8080/tfs/DefaultCollection" /p:"Fabrikam Web Site" /n:"QoS Item" /new:"Service Agreement"
When you rename a work item type that belongs to a category, you have to update the categories definition for the project to reflect the new name. In particular, the backlogs and boards will not work until you update the categories definition.
This article addressed how to add and customize work item types for Hosted XML and On-premises XML process models. For information on adding and customizing work item types for the Inherited process model, see Customize a process.
Other related topics or resources: