Use team fields instead of area paths to support teams

TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013


Feature availability:  Team fields are only supported for on-premises TFS. Team fields are not supported in VSTS.

Also, you can use a Team field or Area Paths to configure Team-scoped tools, but not both.

The default configuration for team projects configures each team as an area path. For information on adding a team, see Multiple teams.

If your organization has several teams that work from a common backlog and across many product areas, this configuration might not fit how you want to organize your work. By adding a custom field to represent teams in your organization, you can reconfigure the agile planning tools and pages to support your teams and decouple assignment to teams and area paths.

Many features available through the web portal for TFS are scoped to a team. Teams access their set of team-scoped features by choosing their team context. Each team gets access to a suite of Agile tools and team assets. These tools provide teams the ability to work autonomously and collaborate with other teams across the enterprise. To learn more, see Configure team settings.

When you customize your team project to support team fields, the Team field tab appears in the administration page for the team project and each team.


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 VSTSor your on-premises TFS, options that you or your admin have enabled, and which process was chosen when creating your team project—Agile, Scrum, or CMMI. However, the basic functionality available to you remains the same unless explicitly mentioned.

Work items are denoted with icons for VSTS and TFS 2017.2 and later versions. For an overview of changes in the navigation experience and working within the user and administration contexts, see Work in the web portal.

Web portal, team project admin context, Team field page added


This topic describes how to reconfigure a team project that is based on the Scrum process template. If your team project is based on another process template and that template is compatible with TFS 2013 or later version, you can make similar changes. Even if you've used the default configuration, you can reconfigure your team project.

1. Create a global list to manage teams

  1. If you aren't a member of the Project Administrators group, get those permissions.

  2. Open a Command Prompt window where you've installed a version of Visual Studio (you can download Visual Studio Community for free) and enter:

    For Visual Studio 2017: cd %programfiles%\Microsoft Visual Studio 15.0\Common7\IDE

    For Visual Studio 2015: cd %programfiles%\Microsoft Visual Studio 14.0\Common7\IDE

    For Visual Studio 2013: cd %programfiles%\Microsoft Visual Studio 12.0\Common7\IDE

    On a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%.


    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):

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

  3. Export the global list for the team project collection.

    witadmin exportgloballist /collection:"http://MyServer:8080/tfs/DefaultCollection" /f:Directory/globallist.xml"

    Add the global list definition for your team. Include a value you'll want to use for items not yet assigned to a team. If your global list is empty, simply copy the following code, paste into the XML file, and modify to support your team labels.

    <?xml version="1.0" encoding="utf-8"?>
    <gl:GLOBALLISTS xmlns:gl="">
       <GLOBALLIST name="Teams">
          <LISTITEM value="Unassigned"/>
          <LISTITEM value="Team A"/>
          <LISTITEM value="Team B"/>
          <LISTITEM value="Team C"/>
          <LISTITEM value="Team D"/>
  4. Import the global list definition.

    witadmin importgloballist /collection:"http://MyServer:8080/tfs/DefaultCollection" /f:Directory/globallist.xml"

    Note that global lists are defined for all team projects within a team project collection.

2. Add a custom team field to work item types

Add a custom team field to all work item types (WITs) that are included in the Feature Category, Requirement Category, and Task Category. And, if you've upgraded to TFS 2013.3 or later version, add the custom team field to all WITs included in the Test Plan Category.

  1. Export the work item type definitions. For Scrum, export the type definitions for the feature, product backlog item, bug, and task.

    witadmin exportwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /n:"Product Backlog Item" /f:Directory/pbi.xml
    witadmin exportwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /n:Bug /f:Directory/bug.xml
    witadmin exportwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /n:Task /f:Directory/task.xml 
    witadmin exportwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /n:"Test Plan" /f:Directory/TestPlan.xml
  2. For each type, add a custom Team field that references the global list.

    . . . 
       <FIELD name="Team" refname="MyCompany.Team" type="String" reportable="dimension">
          <HELPTEXT>Name of the team that will do the work.</HELPTEXT>
             <ALLOWEDVALUES >
                <GLOBALLIST name="Teams" />
             </ALLOWEDVALUES >
             <DEFAULT from="value" value="Unassigned" />
    . . . 

    Name your custom field to distinguish it from other system fields. Do not use "System" as a prefix for refname. And, keep the name and refname labels to 128 characters and 70, respectively.

  3. Add the Team field to the Layout section of the work item form. If you are working in VSTS and TFS 2017, you'll also need to edit the WebLayout section of the WIT definition.

    . . . 
       <Group Label="Status">
          <Column PercentWidth="100">
             <Control FieldName="MyCompany.Team" Type="FieldControl" Label="Team" LabelPosition="Left" EmptyText="&lt;None&gt;" />
             <Control Type="FieldControl" FieldName="System.AssignedTo" Label="Assi&amp;gned to:" LabelPosition="Left" />
             <Control FieldName="System.State" Type="FieldControl" Label="Stat&amp;e" LabelPosition="Left" />
             <Control FieldName="System.Reason" Type="FieldControl" Label="Reason" LabelPosition="Left" ReadOnly="True" />
    . . . 

    Optionally, move the Area Path field to appear before or after the Iteration Path.

  4. Import the updated type definitions.

    witadmin importwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/pbi.xml
    witadmin importwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/bug.xml
    witadmin importwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/task.xml
    witadmin importwitd /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/TestPlan.xml

3. Change process configuration to reference the team field

  1. Export the ProcessConfiguration XML definition.

    witadmin exportprocessconfig /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/ProcessConfiguration.xml
  2. Replace System.AreaPath for the field used to specify type="Team".

    <TypeField refname="MyCompany.Team" type="Team" />
  3. (Optional) Add the Team field to the quick add panel for the backlog page. . . .

  4. Import the definition file.

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

4. Configure the Team field for each team

Create and configure teams in the web portal to both match and reference the Team field. Each team, including the team project, Fabrikam Fiber Website, must be configured with a default value for the Team field.

  1. Refresh your web portal, and from the team project home page, open a product backlog item, PBI or user story. Verify that the changes appear as you expect and that you can select a team.

    Open PBI and confirm the Team field

  2. If you haven't yet created teams to match those that are in your global list, do that now. See Multiple teams, Add another team.

    Create teams

    If you have previously created teams, they will continue to exist. You can rename them as needed.

  3. Open the product backlog or the task board for the team project. You'll see an error indicating you'll need to select a team area.

    Select team's areas link on Backlogs page in the web portal

  4. On the administration page, open the Team field tab and select the value or values from the global list that you want to associate with the default team.

    Unconfigured Team field for a team project

    To support rollup of all teams to the default team, all teams are selected.

    Team field page for team project admin context

  5. Next, configure each team within the hierarchy of teams with the Team field value that matches their name.

    Configure team field for each team

    Repeat this step for all sub teams within the hierarchy.

Assign work to teams using the Team field

From the product backlog page for the team project, you can create backlog items and assign them to teams by opening each item and selecting the Team field. Assigned items will show up on the team's backlog, and they can then work with them using their sprint backlog and task board.

Work from a common backlog

For backlog items you create from a team's backlog page, TFS assigns the default value associated with the team to the Team field.

Q: Why don't teams that I add to a team project show up in the Team field?

A: Teams that you add to a team project from the Overview page of the team project, will not show up in the pick list of the custom field that you created to capture teams. You must update the global list that you created in Create a global list to manage teams for new teams to appear.

Use the global list to add new teams and then configure them as described in Configure Team settings.

Q: How do I configure features for an upgraded team project that has been customized to use team fields?

A: Before you can configure features for an upgraded team project that you have customized to use team fields, you'll need to customize the latest process template with the same changes outlined in this topic. Here are the basic steps:

  1. Upgrade TFS to the latest version.

  2. Download the process template that corresponds to the template used to create your team project.


    Make sure that you download the process template from the upgraded server. Also, the Visual Studio client version you use for both the download process and using witadmin must match the server version. For example, if you have upgraded to TFS 2015, you need to work from Visual Studio 2015. If you use an older version of Visuals Studio, you may get errors during the upload process.

  3. Modify the ProcessTemplate file, and update the process template name and version number. For example:

    <?xml version="1.0" encoding="utf-8"?>
        <name>Microsoft Visual Studio Scrum 2013.3 with Team Field</name>
        <description>This template is for teams who follow the Scrum methodology and use Scrum terminology.</description>
        <version type="6B724908-EF14-45CF-84F8-768B5384DA45" major="3" minor="60" />
  4. As described earlier in this topic, Add a custom team field to work item types, update the WIT definitions for the work item types assigned to the Feature, Requirements, and Task categories. For the Scrum process template, this corresponds to the Feature, Product Backlog Item, Bug, Task, and Test Plan WITs.

  5. As described in Change process configuration to reference the team field, update the ProcessConfiguration file to use the custom team field.

  6. Upload the process template that you just modified.

  7. Configure features using the wizard. Upon verify, the wizard should select the process template that you uploaded in the previous step.


Guidance for customizing teams decoupled from area paths was developed in partnership with Martin Hinshel, a senior devops consultant and Microsoft Visual Studio ALM MVP.