Add or modify a work item type

Last Update: 4/5/2017

Team Services (Hosted XML) | TFS 2017 | TFS 2015 | TFS 2013

IMPORTANT

This topic applies to team project customization for Hosted XML and On-premises XML process models. For the Inheritance process model, see Customize a process. For an overview of process models, see Customize your work tracking experience.

Your team project contains 14 or more work item types (WITs), based on the process—Agile, Scrum, or CMMI—used to create the team project. A WIT is the object you use to track different types of work.

You can modify an existing WIT or add a custom WIT based on your team's 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.

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 WIT customizations are made to the WIT definition, however, other customization are made through the Process Configuration definition or via the witadmin command line tool.

NOTE

Feature availability: You can exercise some features only from an on-premises TFS and are noted as such.

Command line change

Add or modify a WIT

To add a custom WIT or modify an existing WIT, you define or modify the XML definition file for the WIT and then import it to your team project based on the process model you use. You modify a WIT by specifying the elements defined within the three main sections of the WIT definition file: FIELDS, WORKFLOW, and FORM.

Summary of WIT elements

The easiest way to add a new WIT is to copy an existing WIT 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 WIT definition file. This is true for all but system fields (fields whose reference name start with System.). All System fields are defined for all WITs, whether or not you include them in WIT 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 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.

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.

Example workflow state diagram, Agile user story

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:

  1. Modify the WORKFLOW of the WIT definition.

  2. Modify the process configuration to map new workflow states to metastates.

    This second step is required when you change the workflow for a WIT that appears on an Agile tool page. These WITs 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.

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

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 (Team Services, TFS 2017)

Header element within web form

Old web form in use (TFS 2017, TFS 2015)

WIT form controls

You can customize the form to accomplish the following objectives:

Add or remove a WIT from the backlog or task board

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.

NOTE

The images you see from your web portal may differ from the images you see in this topic. These differences result from updates made to Team Services or your on-premises TFS, options that you or your admin have enabled, and which process was chosen when creating your team project—Agile, Scrum, or CMMI. However, the basic functionality available to you remains the same unless explicitly mentioned. For an overview of changes in the navigation experience and working within the user and administration contexts, see Work in the web portal.

To learn how to add or remove WITs from the backlog or task board, see Add a work item type to a backlog and board. To add a new WIT to support a portfolio backlog, see Add a portfolio backlog level.

Change the color for a WIT or workflow state

In the web portal, 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. To change the color for a workflow state, you also edit the process configuration.

NOTE

To change or specify the workflow state color requires you work with the Hosted XML process model or TFS 2017 or later version.

This topic addressed how to add and customize WITs and process configuration for Hosted XML and On-premises XML process models. For information on adding and customizing fields for Hosted XML and On-premises XML process models, see Add or modify a work item type. For the Inheritance process model , see Customize a process.

Other related topics or resources:

Required permissions

  • To list work item types, you must have your View project-level information permission for the team project in the collection set to Allow.
  • (TFS) To add or customize a WIT, you must be a member of the Project Administrators group or have your Edit project-level information permission set to Allow.
  • (Team Services) To add or customize a WIT by customizing a process template, you must be a member of the Project Collection Administrators group or have your Edit process permission set to Allow

To get added as an administrator, see Add administrators.

Import and export WIT definition files (On-premises XML)

NOTE

If you use the Hosted XML process model, you need to import and export the process template used by your team project. For details, see Customize the work item tracking web form.

  1. If you don't have administration permissions for your team project, get them.

  2. 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 Visual Studio Community for free.

  3. 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.

  4. Edit the file. For details, see Work item tracking: Index to XML element definitions.

  5. Import the WIT definition file.

    witadmin importwitd /collection:CollectionURL /p:ProjectName /f:"DirectoryPath/FileName.xml"  
    
  6. 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.

Enable features after upgrade (On-premises XML)

NOTE

Feature availability: You can exercise the Configure Features Wizard only from an on-premises TFS.

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

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.

Rename a WIT (On-premises XML)

NOTE

Feature availability: You can exercise witadmin renamewitd only from an on-premises TFS.

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 backlogs and boards will not work until you update the categories definition.

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

Deactivate or disable a WIT (On-premises XML)

How do you restrict users from creating work items of a certain type?

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> 
    

Delete a WIT (On-premises XML)

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. For more information, see Import, export, and manage work item types and Import and export categories.

How do WIT modifications affect existing work items?

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]((../reference/witadmin/manage-work-item-fields.md).

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.

Clone a WIT

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.

Workflow changes and earlier versions of the Test Manager client

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.