Add a work item type to a backlog and board

Last Update: 3/16/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 your backlogs or boards for a process.

For an overview of process models, see Customize your work tracking experience.

To satisfy other business processes, your team may want to track additional work item types (WITs) as requirements or as tasks. This way, you can add them and track them within the product and sprint backlogs or Kanban and task boards.

For example, you may want to track different types of requirements based on their target customer, or different types of bugs based on their source. Here the Fabrikam Fiber team has added the Service App WIT to track work that supports their customer service team.

Add a custom WIT, e.g., Service App, to the Requirement Category to track it like a requirement

TIP

If all you want to do is add bugs to your backlogs and boards, see Show bugs on backlogs and boards to make your team's selection. If you want to add another WIT and portfolio backlog, see Add a portfolio backlog level.

To add a WIT to track as requirements, tasks, or as bugs perform the corresponding steps:

NOTE

We recommend that you add a WIT to one and only one of the following categories: Requirement Category, Task Category, or Bug Category. The system prevents you from adding the same WIT to both the Requirement Category and Task Category. WITs that you add to the Bug Category will follow the bug behavior set for the team.

First steps

Hosted XML process model customization sequence

NOTE

Use the following guidance if you customize your process through import/export of definition files. Otherwise, if you customize your process through the admin UI, see Add or modify a custom work item type for a process.

You'll make your changes to your process definition files, and then import that process to either update existing team projects or use the process to create a team project.

On-premises XML process model customization sequence

You'll first export your work tracking definition files, update them, and then import them to your team project.

Add a WIT to track it like a requirement

WITs that you add to the Requirement Category show up on the product backlog and Kanban board. You must make sure that the WIT definition contains required fields to support the Agile planning tools.

  1. Export your process (Hosted XML) or your definition files (On-premises XML) as indicated in First steps.
  2. Edit the WIT definition to support planning tools.

    Customize Syntax to add or update
    Backlog priority field (Agile, CMMI) <FIELD name="Stack Rank" refname="Microsoft.VSTS.Common.StackRank" type="Double" reportable="dimension">
       <HELPTEXT>Work first on items with lower-valued stack rank. Set in triage.</HELPTEXT>
    </FIELD>

    Stack rank field (Scrum) <FIELD name="Backlog Priority" refname="Microsoft.VSTS.Common.BacklogPriority" type="Double" reportable="detail" />
    Value Area field
    <FIELD name="Value Area" refname="Microsoft.VSTS.Common.ValueArea" type="String">
       <REQUIRED />
       <ALLOWEDVALUES>
          <LISTITEM value="Architectural" />
          <LISTITEM value="Business" />
       </ALLOWEDVALUES>
       <DEFAULT from="value" value="Business" />
       <HELPTEXT>Business = delivers value to a user or another system; Architectural = work to support other stories or components</HELPTEXT>
    </FIELD>
    Requirement Type field (CMMI) <FIELD name="Requirement Type" refname="Microsoft.VSTS.CMMI.RequirementType" type="String" reportable="dimension">
       <REQUIRED />
       <ALLOWEDVALUES>
          <LISTITEM value="Scenario" />
          <LISTITEM value="Quality of Service" />
          <LISTITEM value="Functional" />
          <LISTITEM value="Operational" />
          <LISTITEM value="Interface" />
          <LISTITEM value="Security" />
          <LISTITEM value="Safety" />
          <LISTITEM value="Business Objective" />
          <LISTITEM value="Feature" />
       </ALLOWEDVALUES>
       <DEFAULT from="value" value="Functional" />
    </FIELD>
    WORKFLOW section

    Update or verify the WORKFLOW section as follows:

    • Agile, User Story: Add transitions from Active to Removed and Resolved to Removed; remove rules that populate Activated By and Activated Date fields when state=Resolved
    • Scrum, Product backlog item: Add transition from Committed to Removed

    If you've customized the WORKFLOW, make sure to define the required state-to-metastate mappings in the ProcessConfiguration RequirementBacklog section.

    FORM section

    Add or verify the following fields have been added to the FORM section:

    • Agile:

      <Control FieldName="Microsoft.VSTS.Scheduling.StoryPoints" Type="FieldControl" Label="Story Points" LabelPosition="Left" />
      <Control FieldName="Microsoft.VSTS.Common.ValueArea" Type="FieldControl" Label="Value area" LabelPosition="Left" />
    • CMMI:

      <Control Type="FieldControl" FieldName="Microsoft.VSTS.Scheduling.Size" Label="Size" LabelPosition="Left" />
      <Control Type="FieldControl" FieldName="Microsoft.VSTS.CMMI.RequirementType" Label="Type" LabelPosition="Left" />
      <Control FieldName="Microsoft.VSTS.Common.ValueArea" Type="FieldControl" Label="Value area" LabelPosition="Left" />
    • Scrum:

      <Control FieldName="Microsoft.VSTS.Scheduling.Effort" Type="FieldControl" Label="Effort" LabelPosition="Left" />
      <Control FieldName="Microsoft.VSTS.Common.ValueArea" Type="FieldControl" Label="Value area" LabelPosition="Left" />

  3. Edit the Categories definition. Add the WIT to the Requirement category. Here we add Service App.

     <CATEGORY name="Requirement Category" refname="Microsoft.RequirementCategory">
        <DEFAULTWORKITEMTYPE name="User Story" />
        <WORKITEMTYPE name="Service App" />
     </CATEGORY>
    
  4. Update or verify ProcessConfiguration definition: RequirementBacklog section for the WIT you're adding. Specifically, make sure that the following conditions are met:

    • Map the start of each workflow state to type="Proposed"
    • Map each intermediate workflow state you want to have show up on the Kanban board to type="InProgress"
    • Map the end of each workflow state to type="Complete"
    • Make sure that you have only one State mapped to type="Complete"
    For example, add the Pending workflow state:

        <States>
          <State value="New" type="Proposed" />
          <State value="Active" type="InProgress" />
          <State value="Pending" type="InProgress" />
          <State value="Resolved" type="InProgress" />
          <State value="Closed" type="Complete" />
        </States>
    
  5. Add the WIT color definition to the ProcessConfiguration WorkItemColors section. For example:
    <WorkItemColor primary="FF33CC33" secondary="FFD6F5D6" name="Service App" />

  6. Update your team project:

Add a WIT to track it like a task

WITs that you add to the Task Category show up on the sprint backlogs and task boards. The WIT you add must specify required fields to support the Agile planning tools.

  1. Export your process (Hosted XML) or your definition files (On-premises XML) as indicated in First steps.
  2. Edit the WIT definition to support planning tools.

    Customize Syntax to add or update
    Backlog priority field (Agile, CMMI) <FIELD name="Stack Rank" refname="Microsoft.VSTS.Common.StackRank" type="Double" reportable="dimension">
       <HELPTEXT>Work first on items with lower-valued stack rank. Set in triage.</HELPTEXT>
    </FIELD>

    Stack rank field (Scrum) <FIELD name="Backlog Priority" refname="Microsoft.VSTS.Common.BacklogPriority" type="Double" reportable="detail" />
    Activity field (Agile, Scrum) <FIELD name="Backlog Priority" refname="Microsoft.VSTS.Common.BacklogPriority" type="Double" reportable="detail" />
    Discipline field (CMMI) <FIELD name="Discipline" refname="Microsoft.VSTS.Common.Discipline" type="String" reportable="dimension">
       <ALLOWEDVALUES>
          <LISTITEM value="Analysis" />
          <LISTITEM value="User Experience" />
          <LISTITEM value="User Education" />
          <LISTITEM value="Development" />
          <LISTITEM value="Test" />
       </ALLOWEDVALUES>
       <HELPTEXT>The discipline to which the task belongs</HELPTEXT>
    </FIELD>
    Remaining Work field (all) <FIELD name="Remaining Work" refname="Microsoft.VSTS.Scheduling.RemainingWork" type="Double" reportable="measure" formula="sum">
       <HELPTEXT>An estimate of the work remaining to complete the task (in person hours)</HELPTEXT>
       <HELPTEXT>The discipline to which the task belongs</HELPTEXT>
    </FIELD>
    Additional scheduling fields (Agile, CMMI) <FIELD name="Original Estimate" refname="Microsoft.VSTS.Scheduling.OriginalEstimate" type="Double" reportable="measure" formula="sum">
       <HELPTEXT>The original estimate of work required to complete the task (in person hours)</HELPTEXT>
    </FIELD>
    <FIELD name="Remaining Work" refname="Microsoft.VSTS.Scheduling.RemainingWork" type="Double" reportable="measure" formula="sum">
       <HELPTEXT>An estimate of the work remaining to complete the task (in person hours)</HELPTEXT>
    </FIELD>
    <FIELD name="Completed Work" refname="Microsoft.VSTS.Scheduling.CompletedWork" type="Double" reportable="measure" formula="sum">
       <HELPTEXT>The work that has been completed for this task (in person hours)</HELPTEXT>
    </FIELD>
    <FIELD name="Start Date" refname="Microsoft.VSTS.Scheduling.StartDate" type="DateTime" reportable="dimension" />
    <FIELD name="Finish Date" refname="Microsoft.VSTS.Scheduling.FinishDate" type="DateTime" reportable="dimension" />
    WORKFLOW section

    Update or verify the WORKFLOW section as follows:

    • Agile, User Story: Add transitions from Active to Removed and Resolved to Removed; remove rules that populate Activated By and Activated Date fields when state=Resolved
    • Scrum, Product backlog item: Add transition from Committed to Removed

    If you've customized the WORKFLOW, make sure to define the required state-to-metastate mappings in the ProcessConfiguration TaskBacklog section.

    FORM section

    Add or verify the following fields have been added to the FORM section:

    • Agile:

      <Control FieldName="Microsoft.VSTS.Scheduling.StoryPoints" Type="FieldControl" Label="Story Points" LabelPosition="Left" />
      <Control FieldName="Microsoft.VSTS.Common.ValueArea" Type="FieldControl" Label="Value area" LabelPosition="Left" />
    • CMMI:

      <Control Type="FieldControl" FieldName="Microsoft.VSTS.Scheduling.Size" Label="Size" LabelPosition="Left" />
      <Control FieldName="Microsoft.VSTS.Common.ValueArea" Type="FieldControl" Label="Value area" LabelPosition="Left" />
    • Scrum:

      <Control FieldName="Microsoft.VSTS.Scheduling.Effort" Type="FieldControl" Label="Effort" LabelPosition="Left" />
      <Control FieldName="Microsoft.VSTS.Common.ValueArea" Type="FieldControl" Label="Value area" LabelPosition="Left" />

  3. Edit the Categories definition. Add the WIT to the Task category. Here we add Service Task.

     <CATEGORY name="Task Category" refname="Microsoft.TaskCategory">
        <DEFAULTWORKITEMTYPE name="Task" />
        <WORKITEMTYPE name="Service Task" />
     </CATEGORY>
    
  4. Update or verify ProcessConfiguration definition: TaskBacklog section for the WIT you're adding.

    Specifically, make sure that the following conditions are met:

    • Map the start of each workflow state to type="Proposed"
    • Map each intermediate workflow state you want to have show up on the task board to type="InProgress"
    • Map the end of each workflow state to type="Complete"
    • Make sure that you have only one State mapped to type="Complete"
    For example, add the Blocked workflow state:

        <States>
          <State value="New" type="Proposed" />
          <State value="Active" type="InProgress" />
          <State value="Blocked" type="InProgress" />
          <State value="Resolved" type="InProgress" />
          <State value="Closed" type="Complete" />
        </States>
    
  5. Add the WIT color definition to the ProcessConfiguration WorkItemColors section. For example:
    <WorkItemColor primary="FFF2CB1D" secondary="FFF6F5D2" name="Service Task" />

  6. Update your team project:

  7. Confirm that you can add the WIT to the task board. Open the task board page, or refresh the page if it's already open.
    You should be able to select either Task or Service Task as a linked work item to a user story.
    Task board with Service Task work item type added

    On the task board, drag the work item to update its status. You'll notice that you can't drag an item to a column for which the state isn't valid. For example, you can't drag Task to the Blocked state, or a Task into a resolved state. If you want to use these states, then add them to the workflow definition for the corresponding WIT definition.

Add a WIT to the Bug Category

WITs that you add to the Bug Category will be treated based on the team setting. Because these WITs may be treated either as requirements or tasks, they must meet Agile planning tool requirements for both requirements and tasks.

  1. Export your process (Hosted XML) or your definition files (On-premises XML) as indicated in First steps.
  2. Edit the WIT definition to support planning tools by meeting the conditions listed for Step 2 of Add a WIT to track as requirements and Add a WIT to track as tasks.

  3. Edit the Categories definition. Add the WIT to the Bug Category. Here we add two WITs.

     <CATEGORY name="Bug Category" refname="Microsoft.BugCategory">
        <DEFAULTWORKITEMTYPE name="Bug" />
        <WORKITEMTYPE name="Service Bug" />
        <WORKITEMTYPE name="Feedback" />
     </CATEGORY>
    
  4. Update or verify ProcessConfiguration definition: BugWorkItems section for the WIT you're adding.

    Specifically, make sure that the following conditions are met:

    • Map the start of each workflow state to type="Proposed"
    • Map each intermediate workflow state you want to have show up on the Kanban or task board to type="InProgress"
    • Map the end of each workflow state to type="Complete"
    • Make sure that you have only one State mapped to type="Complete"
    For example, add the Investigate workflow state:

        <States>
          <State value="New" type="Proposed" />
          <State value="Active" type="InProgress" />
          <State value="Investigate" type="InProgress" />
          <State value="Resolved" type="InProgress" />
          <State value="Closed" type="Complete" />
        </States>
    
  5. Add the WIT color definition to the ProcessConfiguration WorkItemColors section. For example:
    <WorkItemColor primary="FFF2CB1D" secondary="FFF6F5D2" name="Service Bug" /> <WorkItemColor primary="FFFF00FF" secondary="FFFFCCFF" name="Feedback" />

  6. Update your team project:

  7. Choose your team setting.

  8. Confirm that the WIT appears on the backlogs and boards as expected and that you can add it through the backlogs as expected.

Import and export definition files (On-premises XML)

Use the witadmin commands to import and export definition files. For details, see witAdmin: Customize and manage objects for tracking work.

TIP

With witadmin, you can import and export definition files. Other tools you can use include the Process Editor (requires that you have installed a version of Visual Studio):

Or, you can use the TFS Team Project Manager, an open-source client available from github.

  1. Open a Command Prompt window where Visual Studio is installed and enter:

    cd %programfiles(x86)%\Microsoft Visual Studio 14.0\Common7\IDE

    On a 32-bit edition of Windows, replace %programfiles(x86)% with %programfiles%.

    The version of Visual Studio must be at the same version as the on-premises TFS.

  2. Enter the witadmin command, substituting your data for the arguments that are shown. For example, to import a WIT:

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

    For *CollectionURL* specify the URL of a team project collection and for *ProjectName* specify the name of a team project defined within the collection. You must specify the URL in the following format: ```http://ServerName:Port/VirtualDirectoryName/CollectionName```.  
    
    For *DirectoryPath*, specify the path to the ```WorkItem Tracking/TypeDefinitions``` folder that holds the process template that you downloaded. The directory path must follow this structure: ```Drive:\TemplateFolder\WorkItem Tracking\TypeDefinitions```.
    

    For example, import the ServiceApp WIT:

    witadmin importwitd /collection:"http://MyServer:8080/tfs/DefaultCollection"/p:MyProject /f:"DirectoryPath/ServiceApp.xml"

Use these commands to export and import WITs, categories, and process configuration:

witadmin exportwitd /collection:CollectionURL /p:"ProjectName" /n:TypeName /f:"DirectoryPath\WITDefinitionFile.xml"

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

witadmin exportcategories /collection:"CollectionURL" /p:"ProjectName" /f:"DirectoryPath/categories.xml"

witadmin importcategories /collection:"CollectionURL" /p:"ProjectName" /f:"DirectoryPath/categories.xml"

witadmin exportprocessconfig /collection:"CollectionURL" /p:"ProjectName" /f:"DirectoryPath/ProcessConfiguration.xml"

witadmin importprocessconfig /collection:"CollectionURL" /p:"ProjectName" /f:"DirectoryPath/ProcessConfiguration.xml"

We've just shown how to add another WIT to your backlogs or boards. However, if you want to add another WIT to act as a portfolio backlog, see Add portfolio backlogs.

See Customize your work tracking experience for an overview of all the options available for customizing work tracking objects.

To learn how hierarchical or nested elements are displayed on a backlog or board, see Backlogs, boards, and plans.