TFS 2017 | TFS 2015 | Previous versions
Feature availability: Team fields are only supported for on-premises TFS. Team fields are not supported in Team Services.
The default configuration for team projects configures each team as an area path. For information on adding a team, see Multiple teams.
Many features available through the web portal for Team Services and 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 Manage team assets.
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.
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 Team Services or 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. For an overview of changes in the navigation experience and working within the user and administration contexts, see Work in the web portal.
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, you can make similar changes. Even if you’ve used the default configuration, you can reconfigure your team project.
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):
- For TFS 2017 and later versions, 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.
- For TFS 2015 and earlier versions, install TFS Power Tools.
Or, you can use the TFS Team Project Manager, an open-source client available from github.
1. Create a global list to manage teams
If you aren't a member of the Project Administrators group, get those permissions.
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 14.0\Common7\IDE
For Visual Studio 2015:
cd %programfiles%\Microsoft Visual Studio 12.0\Common7\IDE
On a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%.
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="http://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>
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.
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
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>
Name your custom field to distinguish it from other system fields. Do not use "System" as a prefix for
refname. And, keep the
refnamelabels to 128 characters and 70, respectively.
<FORM> . . . <Group Label="Status"> <Column PercentWidth="100"> <Control FieldName="MyCompany.Team" Type="FieldControl" Label="Team" LabelPosition="Left" EmptyText="<None>" /> <Control Type="FieldControl" FieldName="System.AssignedTo" Label="Assi&gned to:" LabelPosition="Left" /> <Control FieldName="System.State" Type="FieldControl" Label="Stat&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.
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
Export the ProcessConfiguration XML definition.
witadmin exportprocessconfig /collection:"http://MyServer:8080/tfs/DefaultCollection" /p:MyProject /f:Directory/ProcessConfiguration.xml
System.AreaPathfor the field used to specify
<TypeField refname="MyCompany.Team" type="Team" />
(Optional) Add the Team field to the quick add panel for the backlog page.
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.
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.
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.
If you have previously created teams, they will continue to exist. You can rename them as needed.
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.
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.
To support rollup of all teams to the default team, all teams are selected.
Next, configure each team within the hierarchy of teams with the Team field value that matches their name.
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.
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
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:
Upgrade TFS to the latest version.
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.
Modify the ProcessTemplate file, and update the process template name and version number. For example:
<?xml version="1.0" encoding="utf-8"?> <ProcessTemplate> <metadata> <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" />
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.
As described in Change process configuration to reference the team field, update the ProcessConfiguration file to use the custom team field.
Upload the process template that you just modified.
Configure features using the wizard. Upon verify, the wizard should select the process template that you uploaded in the previous step.
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: What other witadmin commands can I use?
A: For a list of all witadmin commands, see witadmin command-line tools.
Q: Where can I learn more about process templates?
A: See Customize a process template.