Customize a team project to support team fields

The default configuration for team projects configures each team as an area path. 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.

Here’s how to reconfigure your team project to use a team field instead of the team-as-area-path.

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

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 11.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="https://schemas.microsoft.com/VisualStudio/2005/workitemtracking/globallists">
      <GLOBALLIST name="Teams">
         <LISTITEM value="Unassigned"/>
         <LISTITEM value="Team A"/>
         <LISTITEM value="Team B"/>
         <LISTITEM value="Team C"/>
         <LISTITEM value="Team D"/>
      </GLOBALLIST>
   </gl:GLOBALLISTS>
   

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.

Add a custom team field to work item types

Add a custom team field to those work item types that you'll assign to teams. At a minimum, add the Team field to the work item types defined in the Requirements Category.

1. Export the work item type definitions, which are included in the Requirements and Task categories. For Scrum, export the type definitions for the 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
   

2. For each type, add a custom Team field that references the global list.

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

   Tip

   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.

   <FORM>
   . . . 
      <Group Label="Status">
         <Column PercentWidth="100">
            <Control FieldName="MyCompany.Team" Type="FieldControl" Label="Activity" 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" />
            </Column>
      </Group>
   . . . 
   </FORM>
   

   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
   

Change process configuration to reference the team field

1. Export the CommonConfiguration definition.

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

2. Replace System.AreaPath for the field used to specify type="Team".

   <TypeField refname="MyCompany.Team" type="Team" />
   

3. Import the definition file.

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

Configure Team settings

Create and configure teams in Team Web Access (TWA) to both match and reference 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.

   

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

   

3. On the team field admin page, select the teams that are available. They should match the same list that you have added to the global list for teams.

   

   When finished, your team field assignments should look similar to this:

   

4. At the team project level, create teams, using the same names you use in the global list.

   

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

5. Each team will also have to configure their team field.

   

Work from the product backlog for the team project

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.

Credits

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.

Q & A

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

A: See the Visual Studio 2013 version of this topic.

What other witadmin commands can I use?

A: For a list of all witadmin commands, see witAdmin: Customize and Manage Objects for Tracking Work Items.

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.

Where can I learn more about process templates?

A: See Customize Process Templates.