Add a portfolio backlog level

TFS 2018

Your project comes equipped with two portfolio backlogs: Features and Epics. However, if you need one or more additional portfolio backlogs, you can add them.

Important

This article applies to 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.

Portfolio backlogs are useful for organizing your backlog under business initiatives. When you organize your backlogs into portfolios, you can gain a hierarchical view of the work defined in lower-level backlogs, including work in progress across several teams. Program managers can track the status of those backlog items of interest and drill down to ensure that all work is represented.

Note

If you haven't yet enabled the Portfolio Backlogs feature for your on-premises Azure DevOps project, do that first.

Here, we add a third portfolio backlog, Initiative. With it, the management team can set priorities and view progress of work belonging to initiatives.

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 your project, and the process template chosen when creating your project—Agile, Scrum, or CMMI. However, the basic functionality available to you remains the same unless explicitly mentioned.

You can add up to five levels of portfolio backlogs. And, each team can choose which backlogs appear for them to work on.

Process overview

The process to add another portfolio backlog differs slightly depending on the process model you use.

• For Hosted XML: You'll first export your process, add or update definition files, and then import that process to either update existing projects or use it to create a project.
• For On-premises XML: You'll first export your work tracking definition files, update them, and then import them to your project.

This article walks you through adding a portfolio backlog to a project based on the Agile process in these five steps:

1. Export the files you need
2. Create the Initiative work item type
3. Update Categories with the Initiative Category
4. Update ProcessConfiguration to add the Initiative portfolio backlog
5. Update your project and verify your changes

You can apply the same steps if you work with a project based on the Scrum or CMMI process. When you're done, you'll get to manage your portfolio of projects by grouping work within these four levels: User Stories (or Product backlog items or Requirements), Features, Epics, and Initiatives.

For more informaiton, see About processes and process templates. For an overview of the three process models, see Customize your work tracking experience.

1. Export the files you need

1. If you aren't a member of the Project Collection Administrators group, get added as an administrator. You need these permissions to customize the project.

2. Get the files you need:

   • For Hosted XML: Export the process you want to update. Save the files to a folder that you'll use to update these files and folders: Categories, ProcessConfiguration, and WorkItemTypes.
   • For On-premises XML: Export the definition files you'll need: Epic, Categories, and ProcessConfiguration.

2. 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. In this example, we copy the Epic WIT and label it Initiative.

- Copy the `Epic` WIT definition to an XML file labeled `Initiative`. (The Epic.xml file is located in the WorkItem Tracking folder of the ProcessTemplate folder.)

• Edit the file named Initiative.
  
- Rename the WIT. Replace `WORKITEMTYPE name="Epic"` with `WORKITEMTYPE name="Initiative"`, and update the description.
`<WORKITEMTYPE name="Initiative" >`
   `<DESCRIPTION>Initiatives help program managers to effectively manage and organize work across several teams >`
   `</DESCRIPTION>`
`. . .`
`</WORKITEMTYPE>`

- Add any custom fields that you want to track using this WIT.
- Rename the `Tab` section named `Features` to `Epics` and replace `Filter WorkItemType="Feature"` with `Filter WorkItemType="Epic"`.
`<Tab Label="Epics">`
`<Control Type="LinksControl" Name="Hierarchy">`
   `<LinksControlOptions>`
   `<WorkItemLinkFilters FilterType="include">`
   `<Filter LinkType="System.LinkTypes.Hierarchy" />`
   `</WorkItemLinkFilters>`
   `<WorkItemTypeFilters FilterType="include">`
      `<Filter WorkItemType="Epic" />`
   `</WorkItemTypeFilters>`
      `<ExternalLinkFilters FilterType="excludeAll" />`
      `<LinkColumns>`
          `<LinkColumn RefName="System.ID" />`
          `<LinkColumn RefName="System.Title" />`
          `<LinkColumn RefName="System.AssignedTo" />`
          `<LinkColumn RefName="System.State" />`
          `<LinkColumn LinkAttribute="System.Links.Comment" />`
          `</LinkColumns>`
   `</LinksControlOptions>`
`</Control>`
`</Tab>`


With this change, you cause the tab control to exclusively show or link to epics as child work items of the initiative.

3. Update Categories with the Initiative Category

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

Add the Initiative Category to the Categories.xml file. (The Categories.xml file is located in the WorkItem Tracking folder.)

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

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

4. Update ProcessConfiguration to add the Initiative portfolio backlog

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. Edit the ProcessConfiguration file to add a new portfolio backlog within the PortfolioBacklogs section. (The ProcessConfiguration.xml file is located in the WorkItem Tracking/Process folder of the ProcessTemplate folder.)

   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="FabrikamFiber.InitiativeCategory" pluralName="Initiatives" singularName="Initiative" workItemCountLimit="1000">
     <States>
       <State value="New" type="Proposed" />
       <State value="Active" type="InProgress" />
       <State value="Resolved" type="InProgress" />
       <State value="Closed" 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.Scheduling.Effort" width="50" />
       <Column refname="Microsoft.VSTS.Common.BusinessValue" width="50" />
       <Column refname="Microsoft.VSTS.Common.ValueArea" 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.

2. Edit the PortfolioBacklog element for the Epic Category to point to Initiative as the parent backlog.

   <PortfolioBacklog category="Microsoft.EpicCategory" pluralName="Epics"  
      singularName="Epic" parent="FabrikamFiber.InitiativeCategory"      
      workItemCountLimit="1000">   
      . . .  
   </PortfolioBacklog>
   

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

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

       <WorkItemColor primary="FFCC66FF" secondary="FFF0D1FF" name="Initiative" />
   

   This assigns a bright pink as the primary color to use in list displays, and a paler pink for the secondary color (currently not used).

5. Update your project and verify access to the new portfolio backlog

1. Update your project:

   • For Hosted XML: Import your process.
   • For On-premises XML: Import the definition files you updated in this order:
     a. Initiative.xml
     b. Categories.xml
     c. ProcessConfiguration.xml

2. Open or refresh the web portal and confirm that Initiative appears as a portfolio backlog as expected. See Organize your backlog.

3. Grant Advanced access to users who'll need to exercises all the features available with portfolio backlogs.
   For Hosted XML: See Assign licenses to users.

Import and export definition files (on-premises TFS only)

If you're updating a project that connects to an on-premises TFS, you'll use the witadmin commands to import and export definition files. You need to export the following files:

• Epic.xml
• Categories.xml (located in the WorkItem Tracking folder)
• ProcessConfiguration.xml (located in the WorkItem Tracking/Process folder)

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). Install the TFS Process Template editor from the Visual Studio Marketplace. You can use this version of the Process Editor to modify the old-style work item forms. You can't use it to edit forms associated with the new web forms.

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

1. Open a Command Prompt window according to the instructions provided in witAdmin: Customize and manage objects for tracking work. For example:

1. 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 project collection and for ProjectName specify the name of a 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 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"

Related articles

We've just shown how to add another portfolio backlog level. You can add up to five portfolio backlogs. This includes the default backlogs of Feature and Epic. In total, this provides you with seven levels from the top-level portfolio backlog to task.

If you want to add another WIT to your backlogs or boards, see work item types to backlogs and boards.

To learn more about the syntax for a definition file or command line tool, see these topics:

• All WITD XML elements reference
• Categories XML element reference
• Process configuration XML element reference
• Import, export, and manage work item types
• Import and export categories
• Import and export process configuration

Otherwise, see Customize your work tracking experience to access other configuration and customization options available to you.

If you have additional questions, see Team Foundation Server - work tracking forum.

Portfolio backlog hierarchy

What controls the hierarchy among portfolio backlogs?

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.

Portfolio backlogs and WIT categories

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

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.

Nesting of backlog items

Can you nest backlog items in addition to using portfolio backlogs?

While you can nest backlog items, we don't recommend you do. We don't support drag-and-drop linking of nested backlog items. Instead, we support mapping of backlog items to portfolio items.

For examples of how hierarchically linked items that belong to the Requirements Category appear on the backlogs and boards, see How backlogs and boards display hierarchical (nested) items.