Add a portfolio backlog level
VSTS (Hosted XML) | TFS 2018 | TFS 2017
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.
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.
Your team project comes equipped with two portfolio backlogs: Features and Epics. However, if you need one or more additional portfolio backlogs, you can add them.
If you haven't yet enabled the Portfolio Backlogs feature for your on-premises TFS, 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.
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 on-premises TFS, and the process template chosen when creating your team 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.
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 team projects or use it to create a team project.
- For On-premises XML: You'll first export your work tracking definition files, update them, and then import them to your team project.
This topic walks you through adding a portfolio backlog to a team project based on the Agile process in these five steps:
- Export the files you need
- Create the Initiative work item type
- Update Categories with the Initiative Category
- Update ProcessConfiguration to add the Initiative portfolio backlog
- Update your team project and verify your changes
You can apply the same steps if you work with a team 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.
1. Export the files you need
- If you aren't the account owner or a member of the Project Collection Administrator's group, get added as an administrator. You need these permissions to customize the team project.
- 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:
- For Hosted XML: Export the process you want to update
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
EpicWIT 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
- Rename the WIT. Replace
WORKITEMTYPE name="Initiative", and update the description.
<WORKITEMTYPE name="Initiative" >
<DESCRIPTION>Initiatives help program managers to effectively manage and organize work across several teams >
. . .
- Add any custom fields that you want to track using this WIT.
- Rename the
<Control Type="LinksControl" Name="Hierarchy">
<Filter LinkType="System.LinkTypes.Hierarchy" />
<Filter WorkItemType="Epic" />
<ExternalLinkFilters FilterType="excludeAll" />
<LinkColumn RefName="System.ID" />
<LinkColumn RefName="System.Title" />
<LinkColumn RefName="System.AssignedTo" />
<LinkColumn RefName="System.State" />
<LinkColumn LinkAttribute="System.Links.Comment" />
With this change, you cause the tab control to exclusively show or link to epics as child work items of the initiative.
- Rename the WIT. Replace
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.
Edit the ProcessConfiguration file to add a new portfolio backlog within the
PortfolioBacklogssection. (The ProcessConfiguration.xml file is located in the WorkItem Tracking/Processfolder 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
Complete. The last state within the workflow must map to
PortfolioBacklogelement for the Epic Category to point to
Initiativeas 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.
Add the color to use for Initiative to the
<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 team project and verify access to the new portfolio backlog
Update your team project:
Open or refresh the web portal and confirm that Initiative appears as a portfolio backlog as expected. See Organize your backlog.
- Grant Advanced access to users who'll need to exercise 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 team 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:
- Categories.xml (located in the WorkItem Tracking folder)
- ProcessConfiguration.xml (located in the WorkItem Tracking/Process folder)
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.
Open a Command Prompt window according to the instructions provided in witAdmin: Customize and manage objects for tracking work. For example:
%programfiles(x86)%\Microsoft Visual Studio\2017\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer
witadmincommand, 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 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 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
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.