Add a backlog to Agile portfolio management

Visual Studio 2013

If you want more levels in your portfolio backlog than only Feature, this topic shows you how to add one. When you organize your backlogs into portfolios, you can view a rollup of the work defined in lower-level backlogs, including work in progress across several teams. A portfolio backlog helps ensure that all work is represented.

A team only sees initiatives they work on

This topic walks you through adding a portfolio backlog in three steps: (1) create the Initiative work item type, (2) add an Initiative Category, (3) and add the Initiative portfolio backlog. When you’re done, you’ll get to manage your portfolio of projects by grouping work within three levels – Product Backlog Items, Features, and Initiatives.

The easiest way to create a work item type (WIT) is to copy an existing one, rename it, and edit it to support your requirements.

  1. If you don't have administrative permissions for your team project, get them. You must be a member of the Team Project Administrators group to edit team project files.

  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)%. You can download Team Explorer for free.

  3. Export the Feature WIT definition to an XML file labeled Initiative.

    witadmin exportwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject  /n:Feature /f:Directory/Initiative.xml
  4. Edit the file named Initiative.

    1. Rename the WIT. Replace <WORKITEMTYPE name="Feature"> with <WORKITEMTYPE name="Initiative">, and update the description.

      <witd:WITD application="Work item type editor" version="1.0" xmlns:witd="">
      <WORKITEMTYPE name="Initiative">
         <DESCRIPTION>Tracks an initiative that will be released with the product. </DESCRIPTION>
    2. Add any more fields that you want to track using this WIT. To learn more, see Modify or add a custom work item type (WIT).

    3. Edit the Tab section named Implementation. Replace <Filter WorkItemType="Product Backlog Item" /> with <Filter WorkItemType="Feature" />.

      <Tab Label="Implementation">
       <Control Type="LinksControl" Name="Hierarchy" Label="" LabelPosition="Top">
               <LinkColumn RefName="System.Id" />
               <LinkColumn RefName="System.Title" />
               <LinkColumn RefName="System.AssignedTo" />
               <LinkColumn RefName="System.State" />
            <WorkItemLinkFilters FilterType="include">
               <Filter LinkType="System.LinkTypes.Hierarchy" FilterOn="forwardname" />
            <ExternalLinkFilters FilterType="excludeAll" />
            <WorkItemTypeFilters FilterType="include">
               <Filter WorkItemType="Feature" />

      By specifying Feature, you indicate that this tab control will be used to show child work items that are Features.

  5. Import the file.

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

Now, add the Initiative Category. This adds the Initiative backlog to process configuration. The agile experience manages WITs according to categories.

  1. Export the categories definition.

    witadmin exportcategories /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/categories.xml

  2. Add the Initiative Category.

    <CATEGORY refname="MyCompany.InitiativeCategory" name="Initiative Category">
        <DEFAULTWORKITEMTYPE name="Initiative" />

    You can add this category anywhere within the definition file. Since you are adding a custom category, best practice is to label the category using your company name.

  3. Import the categories file.

    witadmin importcategories /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/categories.xml

In this last step, you add the Initiative portfolio backlog to the process and modify the Feature portfolio backlog to reflect the hierarchy between Initiatives and Features. The process configuration determines the parent-child relationships among the portfolio backlogs.

  1. Export the ProcessConfiguration file:

    witadmin exportprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\ProcessConfiguration.xml"
  2. Edit the file to add a new portfolio backlog within the PortfolioBacklogs section.

    Add the Initiative Category by adding the following syntax. Replace the names, workflow state values, and default column fields to match those that you use.

    <PortfolioBacklog category="MyCompany.InitiativeCategory" pluralName="Initiatives" singularName="Initiative">
            <State value="New" type="Proposed" />
            <State value="In Progress" type="InProgress" />
            <State value="Done" type="Complete" />
            <Column refname="System.WorkItemType" width="100" />
            <Column refname="System.Title" width="400" />
            <Column refname="System.State" width="100" />
            <Column refname="Microsoft.VSTS.Common.BusinessValue" width="50" />
            <Column refname="Microsoft.VSTS.Scheduling.TargetDate" width="100" />
            <Column refname="System.Tags" width="200" />
              <Field refname="System.Title" />

    If you have modified the workflow states, then verify that each work flow state is mapped to one of the metastates of Proposed, InProgress, and Complete. The last state within the workflow must map to Complete.

  3. Edit the PortfolioBacklog element for the Feature Category to point to Initiative as the parent backlog.

    <PortfolioBacklog category="Microsoft.FeatureCategory" parent="MyCompany.InitiativeCategory" pluralName="Features" singularName="Feature">

    Intermediate portfolio backlogs require specifying the parent category, which must be configured as a portfolio backlog.

  4. Add the color to use for Initiative to the WorkItemColors section.

    <WorkItemColor primary="FFFF6600" secondary="FFFEB380" name="Initiative" />

    This assigns a bright orange color as the primary color to use in list displays, and a paler orange color to use on the Kanban board.

    To get hexadecimal colors, use this HTML color picker tool.

  5. Import the file.

    witadmin importprocessconfig /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\ProcessConfiguration.xml"
  6. Open or refresh the browser for TWA and confirm that the portfolio backlogs work as expected. See Work with portfolio backlogs.

A: You can add up to five portfolio backlogs. This includes the default backlog of Feature. In total, this provides you with seven levels from the top-level portfolio backlog to task.

Conceptual image of 5 levels of portfolio backlog

A: The process configuration determines the hierarchy through the assignment of parent categories to portfolio backlog categories. Only parent-child relationships are supported. The upper-most category within the hierarchy doesn’t contain a parent assignment.

A: Yes. For example, you can add Goal and Initiative WITs to a portfolio backlog category. The main restriction is to not add the same WIT to two different categories that are assigned to one of the following sections for process configuration: a PortfolioBacklog, RequirementBacklog, or TaskBacklog.

A: You can nest backlog items, but not portfolio backlog items. Nesting is not recommended.

A: To view and work with portfolio backlogs requires that each team member has Advanced access.

A: You might find answers to your questions or you can post a question in one of the following TFS forums: