Configuring the “Epics” for upgraded team projects in Team Foundation Server (TFS) 2015

were introduced in TFS 2015 to support Scaled Agile Framework(SAFe). In TFS 2015, if you create a new team project, you would see “Epics”.
But if you have upgraded from previous versions of Team Foundation Server, then you won’t be able to see them without making few additional changes. You would see how we can make those additional changes to get “Epics” in the remainder of this post.

If you have tried to enable the new features using “Configure Features” wizard, you would see “Epics” were not included (Portfolio backlogs configured (will be skipped)).


Click on “Verify” and complete the wizard. Then in the Team Admin page, you won’t see “Epics” as an option to enable it.


Steps to enable “Epics” manually:

1. Download the latest process template from Process template manager (In Visual Studio IDE, Team -> Team Project Collection Settings -> Process Template Manager).

Note: I recommend you to download the Process template which is same as the current team project. I have used “Scrum” process template to create this team project and downloaded “Scrum” process template.

2. Import the “Epic” work item type from the downloaded process template. You can use the Powertools or witadmin command to import the WIT definition file. Below is the command for your reference:

witadmin importwitd /collection:CollectionURL /p:Project /f:FileName


3. Export the categories.xml file for this team project. Below is the command for reference:

witadmin exportcategories /collection:CollectionURL /p:Project /f:FileName

Below is the output


4. Open the categories.xml file and add the “Epic” category. You can add the snippet below:

<CATEGORY name="Epic Category" refname="Microsoft.EpicCategory">

5. Save the categories.xml file and then import it to the team project. Below is the command for your reference.

witadmin importcategories /collection:CollectionURL /p:Project /f:FileName


6. Export ProcessConfiguration.xml file from the team project. Below is the command for your reference:

witadmin exportprocessconfig /collection:CollectionURL /p:Project /f:FileName


7. Open the ProcessConfiguration.xml file in notepad or in any xml editor to make the changes below:

a. Add Portfoliobacklog of type “Epic” under the section < PortfolioBacklogs>

<PortfolioBacklog category="Microsoft.EpicCategory" pluralName="Epics" singularName="Epic" workItemCountLimit="1000">
<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.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" />
<Field refname="System.Title" />

b. Add parent="Microsoft.EpicCategory" to the Portfoliobacklog feature as below (highlighted text):

<PortfolioBacklog category="Microsoft.FeatureCategory" pluralName="Features" singularName="Feature" parent="Microsoft.EpicCategory" workItemCountLimit="1000">

c. Add below line under < WorkItemColors>

<WorkItemColor primary="FFFF7B00" secondary="FFFFD7B5" name="Epic" />

d. Add the below line with in <Properties> section as below (highlighted text):

<Property name="HiddenBacklogs" value="Microsoft.EpicCategory" />

So, your XML looks like this,

<Property name="BugsBehavior" value="AsRequirements" />
<Property name="HiddenBacklogs" value="Microsoft.EpicCategory" />

Note: If entire <Properties> section is missing; you can add the above snippet.

e. Save the ProcessConfiguration.xml file

8. Import the ProcessConfiguration.xml file. Below is the command for your reference:

witadmin importprocessconfig /collection:CollectionURL /p:Project /f:FileName


9. Go to Team profile page. Now, you would see “Epics” to enable it.


Now, you can select “Epics” to enable it.

Note: If Portfolio backlogs features were not configured in TFS 2012/2013, then after upgrade to TFS 2015 the “configure Features” wizard will configure Features and Epics.


After configuring the features:


Hope this helps!

Content created By: Chandra Sekhar Viswanadha

Comments (6)

  1. Matt Ring says:

    Thanks for sharing this, though I'm surprised a configuration upgrade path for this scenario isn't available, and that it requires such manual, tedious steps. This is particularly tedious if you want to apply this across several projects in a collection.

    Looks like another opportunity for some PowerShell scripting…

  2. Matt Ring says:

    FYI… A clarification on step 7d:

    If the <properties> node already exists, you simply need to put the following addition within that node:

    <Property name="HiddenBacklogs" value="Microsoft.EpicCategory" />

    Lines 2-5 of that code block are to be what the XML may look like AFTER you've updated the code block. Right now, it may be a little confusing if users are supposed to insert the code snippet above and within the <properties> node or just in one place.

    Chandra – Can you update the post to make that a bit more clear?



  3. Hey Matt,

    Thanks for the suggestion! It seems we had forgotten to highlight the text. I have also modified 7d to make it a bot more clear.

  4. ranrads says:

    Nice clear steps, thank you. It is a shame there's no automated way to do this.

    Obviously if you're applying the change for multiple projects all using the same process template, once you have the correct xml files you can simply script/run the 3 importxxxx commands changing just the project name on each.

  5. Chris Forehand says:

    Thanks, I understand what needs to be done, but is there an easy way to did it also with VSO (Online) 1) download template or Copy a default one, 2) upload it if project is still very simple stages of creating one ( only have a few running items in a project
    To Matt Ring comment, totally agree – has anyone scripted this ( will look but though I would ask 🙂 ) Thanks Chris

  6. Mary Ann Yeager says:

    Another clarification if you are using Agile instead of Scrum. Because the States for Epic differ between the 2, the State portion of section 7a would look like:

    instead of:

Skip to main content