Modify or add a custom work item type (WIT)

Article
04/21/2015

As a project administrator, you might want to modify an existing work item type (WIT) to support additional tracking requirements or workflow processes. The most common reasons to modify a WIT are to add or modify the set of fields or field rules, change the workflow, or customize the work item form. These three reasons correspond to the three main sections of the WIT XML definition file: FIELDS, WORKFLOW, and FORM.

All of these modifications require you to edit the WIT definition, which you can only do for TFS on-premises deployments. This topic provides an overview of what you can customize and pointers to content that shows you how.

Work item types, customize

Add or modify a field, field rule, label, or empty text

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 WIT definition.

For example, to add the work item ID to a form, specify the following XML syntax within the FORM section.

<Control FieldName="System.ID" Type="FieldControl" Label="ID" LabelPosition="Left" />

To learn more about defining fields, , see Add or modify a field to support queries, reports, and workflow.

Change the workflow states, reasons, transitions, or add workflow field rules

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.

Example workflow state diagram

User Story workflow states, Agile process template

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:

Modify the WORKFLOW of the WIT definition.
Modify the process configuration to map new workflow states to metastates.

This second step is required under the following circumstances:
- When you change the workflow for a WIT that appears on an Agile planning tool page. These WITs belong to either the Requirement or Task categories. To learn more about configuring these tools, see Configure and customize Agile planning tools for a team project.
- When you change the workflow for the test plan or test suite and you work from a Test Manager client provided with Visual Studio 2013.2 or earlier versions. These WITs became available when you updated your application-tier server to TFS 2013.3. that appears on an Agile planning tool page.
  
  If you encounter an Application detected an unexpected fault error when you connect to your team project after you changed the workflow, you can resolve it by mapping the new workflow states to metastates. To resolve this error, see Import and export process configuration [witadmin].

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.

For more information about applying workflow field rules, see FIELD (Workflow) element.

Customize the work item form

The following illustration highlights the most common elements on work item forms. You can customize all of them except the title area and form controls.

Work item form elements and controls

You can customize a WIT form to accomplish the following objectives:

Add or remove a field, change a field label or change the placement of a field on the form. For more information, see Specify work item form controls.
Add new tabs or columns, or move groups of fields from one tab to another. See Design the work item form.
Add informational text to support filling out the form, hyperlinks to detailed process guidance, or embed html text or display dynamic reports within the form. See Provide help text, hyperlinks, or web content on a work item form.
Specify tabs that restrict the link types or WITs that can be linked to a work item. See Define link controls to restrict link relationships.
Add an attachment control to support attaching files. See Add the Attachments control.

Edit the WIT definition

To edit the WIT definition, you export, modify, and then import the WIT definition file.

Process for customizing a WIT object

With witadmin, you can import and export definition files. Other tools you can use to modify the XML syntax for an object include the Process Editor, available with the download of TFS Power Tools, or TFS Team Project Manager, a community resource project available on CodePlex.

If you don't have administration permissions for your team project, get them.
Open a Command Prompt window where either Visual Studio or Team Explorer is installed and enter:
```
cd %programfiles%\Microsoft Visual Studio 12.0\Common7\IDE
```
On a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%. Go here to download Team Explorer for free.
Export the WIT definition file where you want to modify or add a field. Specify the name of the WIT and a name for the file.
```
witadmin exportwitd /collection:CollectionURL /p:ProjectName /n:TypeName /f:"DirectoryPath/FileName.xml"
```
An example of a CollectionURL is http://MyServer:8080/tfs/TeamProjectCollectionName.
Edit the file. For details, see Work item tracking: Index to XML element definitions.

Import the WIT definition file.

witadmin importwitd /collection:CollectionURL /p:ProjectName /f:"DirectoryPath/FileName.xml"

Open either TWA or Team Explorer to view the changes. If the client is already open, refresh the page.

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.

For more information about using witadmin, see Import, export, and manage work item types [witadmin].

Q & A

Q: How do I work with tags?

A: To learn how to add tags and filter lists, go here.

Q: What customizations can I make and still use the Configure Features Wizard to update my team project after a TFS upgrade?

A: You can add custom WITs and change the form layout. The Configure Features Wizard will update your team projects and you’ll get access to the latest features.

Changing the workflow or renaming a WIT might require you to perform some manual operations when updating your team project. To learn about other customizations that you can safely make and which you should avoid, see Customize the work tracking experience: Before you customize, understand the maintenance and upgrade implications.

Q: How do I add a new WIT?

A: The easiest way to add a new WIT is to copy an existing WIT and then modify the definition file. For an example, see Create a work item type.

Q: Can I rename a WIT?

A: Yes. To rename an existing WIT use witadmin renamewitd. For example, you can rename a WIT 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 WIT that belongs to a category, you have to update the categories definition for the team project to reflect the new name. In particular, the Agile planning tools will not work until you update the categories definition.

For more information, see Import, export, and manage work item types [witadmin] and Import and export categories [witadmin].

Q: How do I deactivate or disable a WIT? How do I restrict users from creating work items of a certain type?

A: If you have a WIT that you want to retire, but maintain the work items that have been created based on that type, you can add a rule that disables all valid users from saving the work item type.

<TRANSITION from=" " to="New">
   <FIELDS>
     <FIELD refname="System.CreatedBy">
         <VALIDUSER not="[Team Project Name]Project Valid Users" />
     </FIELD>
   </FIELDS>
</TRANSITION>

If you want to restrict creation of a specific WIT to a group of users, there are two ways to restrict access:

Add the WIT 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.
Add a field rule to the workflow for the System.CreatedBy field to effectively restrict a group of users from creating a work item of a specific type. As the following example shows, the user who creates the work item must belong to the Allowed Group in order to save the work item.
```
<TRANSITION from=" " to="New">
   <FIELDS>
     <FIELD refname="System.CreatedBy">
         <VALIDUSER for="Allowed Group" not="Disallowed Group" />
     </FIELD>
   </FIELDS>
</TRANSITION> 
```

Q: How do I delete a WIT?

A: To prevent team members from using a specific WIT to create a work item, you can remove it from the team project. When you use witadmin destroywitd, you permanently remove all work items that were created using that WIT as well as the WIT itself. For example, if your team doesn’t use “Impediment,” you can delete the WIT 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 WIT that belongs to a category, you must update the categories definition for the team project to reflect the new name. In particular, the Agile planning tools will not work until you update the categories definition.

For more information, see Import, export, and manage work item types [witadmin] and Import and export categories [witadmin].

Q: Can I change the color associated with a WIT?

A: Yes. In Team Web Access, work items appear in query results and on the backlog and board pages of the Agile planning tools. To change the color associated with an existing WIT or add the color to use for a new WIT, edit the process configuration.

Color assignments to different work item types

Q: Can I add or remove a WIT from the backlog or task board?

A: Yes. The Agile planning tools—product backlog, sprint backlog, and task board pages—display specific WITs based on the process template used to create your team project. You can add or remove WITs to appear on these pages. For example, if your team project uses Scrum WITs, both product backlog items and bugs appear on the backlog pages. However, if your team 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.

Updated panel with bug work item type added

To learn how to add or remove WITs from the backlog or task board, go here. To add a new WIT to support a portfolio backlog, go here.

Q: When I modify a WIT, how does it affect existing work items?

A: The following table summarizes the effect on existing work items when you modify fields or WIT definitions.

Action	Effect on existing work items
Remove fields from a WIT	Data for the removed fields remains in the data store. However, no new data can be added, because you’ve removed them from the WIT 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 WIT	All data remains intact under the new name.
Delete a WIT	All data for work items created as the deleted WIT 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. See Manage work item fields [witadmin].

Q: How do I change the type of an existing work item?

A: You can’t change the 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.

Copy a work item and specify a new type

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.

Q: Can I delete work items from TFS?

A: Yes. Use witadmin destroywi to permanently remove work items from the database.

Q: What should I know about WIT customization and TFS upgrades?

A: See Configure features after a TFS upgrade.

Q: Where can I go if I have more questions?

A: To find answers or post a question, visit the forum: Team Foundation Server - Project Management & Work Item.

For more information, see Specify work item form controls.

Use the Process Editor, available with the download of TFS Power Tools, to modify the workflow or to view a state diagram of the workflow.