Add a backlog to Agile portfolio management

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.

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.

Create a work item type named Initiative

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="https://schemas.microsoft.com/VisualStudio/2008/workitemtracking/typedef">
      <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">
         <LinksControlOptions>
            <LinkColumns>
               <LinkColumn RefName="System.Id" />
               <LinkColumn RefName="System.Title" />
               <LinkColumn RefName="System.AssignedTo" />
               <LinkColumn RefName="System.State" />
            </LinkColumns>
            <WorkItemLinkFilters FilterType="include">
               <Filter LinkType="System.LinkTypes.Hierarchy" FilterOn="forwardname" />
            </WorkItemLinkFilters>
            <ExternalLinkFilters FilterType="excludeAll" />
            <WorkItemTypeFilters FilterType="include">
               <Filter WorkItemType="Feature" />
            </WorkItemTypeFilters>
         </LinksControlOptions>
       </Control>
      </Tab>
      

      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
   

Add the Initiative Category

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" />
   </CATEGORY>
   

   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
   

Add the Initiative Category to the portfolio backlog hierarchy

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">
         <States>
           <State value="New" type="Proposed" />
           <State value="In Progress" type="InProgress" />
           <State value="Done" type="Complete" />
         </States>
         <Columns>
           <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" />
         </Columns>
         <AddPanel>
           <Fields>
             <Field refname="System.Title" />
           </Fields>
         </AddPanel>
    </PortfolioBacklog>
   

   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.

Q & A

Q: How many portfolio backlogs can I add?

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.

Q: What controls the hierarchy among portfolio backlogs?

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.

Q: Can I have more than one WIT defined in a category that I use for a portfolio backlog?

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.

Q: Can I nest backlog items in addition to using portfolio backlogs?

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

Q: I’ve added portfolio backlogs to my team project. Why can’t all team members view them?

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

Q: Where can I learn more about the syntax for a definition file?

A: These reference topics provide syntax information:

• All WITD XML elements reference

• Categories XML element reference

• Process configuration XML element reference

Q: Where can I learn more about the command line tools used to import and export definition files?

A: These reference topics provide command line tool syntax and examples for usage:

• Import, export, and manage work item types [witadmin]

• Import and export categories [witadmin]

• Import and export process configuration [witadmin]

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

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

• Team Foundation Server - Work Item Tracking

• Team Web Access