Set up team fields to support Agile planning tools

Agile planning tools support multiple teams within a team project. Each team is associated with an area path by default. However, 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.

Instead of area paths, you can add a custom field to configure Agile tools to use team fields. 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.

Configure team field for each team

You can perform this customization before or after you add teams or a hierarchy of teams.

Customization requires that you connect to an on-premises Team Foundation Server (TFS) and that the process template used to create the team project is compatible with TFS 2013. This topic describes how to reconfigure a team project that is based on the TFS Scrum process template. Even if you’ve used the default configuration, you can reconfigure your team project.

The witadmin command line tool supports import and export of definition files. You can also use the Process Editor, available with the download of TFS Power Tools, or TFS Team Project Manager, a community resource project available on CodePlex.

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 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 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, 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 TFS 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 work item form.

    . . . 
       <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 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.

    <RequirementBacklog category="Microsoft.RequirementCategory" parent="Microsoft.FeatureCategory" pluralName="Stories" singularName="User Story">
            <Field refname="System.Title" />
            <Field refname="MyCompany.Team " />
    . . .
  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 Team Web Access (TWA) 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 TWA, and from the team project home page, open a product backlog item. Verify that the changes appear as you expect and that you can select a team.

    Open PBI and confirmTeam field

  2. If you haven’t yet created teams to match those that are in your global list, do that now. See 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 TWA

  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 & A

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 TFS process template that corresponds to the template used to create your team project.

  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 in 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 TFS 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.

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.

What other witadmin commands can I use?

A: For a list of all witadmin commands, see witAdmin: Customize and manage objects for tracking work.

Where can I learn more about process templates?

A: See Customize a process template.


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