Customize a process template

A process template corresponds to an interdependent set of files that are used to create a Team Foundation Server (TFS) team project. A team project is a central planning tool that you use to track information and to organize source code, builds, tests, and plans for your team. In addition to creating a team project, you use a TFS process template to upgrade an existing team project after an upgrade to an on-premises TFS.

If you’re looking for project templates for software development, see Creating Visual Studio templates. This topic is about process templates for creating TFS team projects.

A TFS process template defines several default configurations as well as the following artifacts that your team uses to collaborate, share information, and plan and track work.

TFS 2013 Agile process template artifacts

Many of these artifacts depend on the creation and definition of the objects that are defined for tracking work. For example, data fields defined in the definition of work item types─such as, Feature, Bug, User Story, or Task─are also used to define work item queries and reports. In addition to these artifacts, you can also define the initial project areas and milestones, the security configuration, and other default settings that support version control and test management.

After you create a team project, you can change configurations and customize artifacts. However, by customizing the process template before you create your team projects, all resulting team projects that you create from it will match a standard set of team processes. The main reasons you might want to customize a process template include:

• You plan to create several team projects and you want to minimize repetitive tasks that you'll have to implement later in each team project that you create.

• You want to make sure all teams adhere to certain standards by providing the templates and structures within the toolset your software development teams will use.

• You need to update a custom process template to support using the Configure Features wizard after a TFS upgrade

If you work with only a single team project, then you might consider simply creating the team project and customizing one or more objects later.

Where should I start?

Before you start customizing a process template, you’ll want to become familiar with what you can configure and customize and then plan your changes accordingly.

• If you’re new to TFS and process templates, first review the three default process templates that TFS provides.

• If you want to become familiar with the file structure of a process template, review a description for each file or download a process template.

• For insight into the toolset, configuration, and customization, review An end-to-end view of what you can configure and customize.

  You can modify the processes for your team project after it is created. As you work with a team project, the initial settings that the process template defined may no longer meet your needs.

• If you’re most interested in customizing objects used to track work, which includes test plans, test suites, and test cases, review Customize work tracking objects to support your team's processes. The customizations you make by modifying an XML definition file for a team project are the same types of customizations you make in a process template file.

  If your focus is to add or modify types of work items, you can achieve this without changing the whole process template. You can make and test changes by using an existing team project. You can use the witadmin exportwit and importwitd command-line tools to download and upload the XML definition files for work item types.

• If you need to update a custom process template to support using the Configure Features wizard after a TFS upgrade, see Update a customized process template to access new features.

  When Visual Studio Team Foundation Server is upgraded from an earlier version, the MSF process templates are replaced with the most recent versions. To use the features that are available with the updated MSF templates and to access customizations that you made previously, you must add the customizations to the new templates.

• If you’re considering making extensive customizations, review how the changes you make will impact maintenance and upgrade of your team projects.

Process template files and functional areas you can customize

Process templates consist of nine plug-ins. Each plug-in defines a set of tasks that will be run and the screens that appear when you launch the New Team Project wizard. Tasks set permissions, create folders, upload files, activate sites, or set other configurable variables. Plug-ins also specify the dependencies that a task has on the successful completion of other tasks.

To customize a process template, you customize one or more files associated with a functional area. While customizing any one object is fairly simple, you’ll want to make sure that you don’t break any interdependencies when you customize.

	Teams and default classifications: Define initial area and iteration paths Configure initial groups, teams, members, and permissions Map Microsoft Project fields to Team Foundation fields Work item tracking: Add or modify WIT definitions Add or modify categories Modify the process configuration Add link types Add work items or work item queries
	Version control, build, lab and test management: Configure default group permissions to functional areas Define default check-in policies Define default test environments, test configurations, resolution states, and test settings
	Reports and project portal: Upload reports Upload documents to the project portal

Because the process template touches on many components of a team's process, you may want to plan, coordinate, and track the changes that you will make. In particular, you may want to check with project leads, test leads, development leads, and release managers before you change the default configuration of any one area.

Steps to customize a process template

Customizing a process template is an iterative process. You will need a team project collection that is defined on a server that is running Team Foundation Server where you can test your process template to make sure that it was customized correctly.

To customize a process template, you first download an existing process template, modify or add files, upload the process template files, and then verify your changes.

Step	Task
	Download a process template. Before you can customize a process template, you must download it to your local computer. To minimize the modifications that you must make, select a template that most closely matches your team processes. In general, you choose a process template based on types of work items and workflow.
	Modify or add files. You customize a process template by modifying, deleting, or adding files that are defined for a process template. You customize a plug-in or definition file by modifying its XML content. Each plug-in file and type definition file must conform to its XML schema definition. The first time that you customize a process template, make a small change. If you make many changes without a good understanding of how the changes may affect your template, you risk encountering multiple mistakes that will be difficult to debug. Make sure that the name of your process template is unique. If you download a process template, make changes, and upload it, you must change its name or it will over-write the existing process template from the project collection.
	Upload a process template. After you have customized your template, upload it to the team project collection where you will create the team project. Ideally, you should use a team project collection that is not used by other team projects. By working in a test-bed project collection, you avoid introducing a change that might collide with existing team processes that are still under development. Also, you will want the team project collection to support the same resources that you want team members to access, such as a project portal and a reporting site. Make sure that the name of your process template is unique. If you downloaded a process template from a team project collection, made a change, and are now uploading the template, you must change its name or delete the existing process template from the team project collection. The upload process performs a verification check to make sure that the XML is valid. If you receive any errors when you try to upload the process template, the changes that you made will have caused the error. Review your changes, and correct any XML syntax errors that you find.
	Create a team project. To test new process templates, you must create a team project. You create a team project by accessing the New Team Project Wizard from Team Explorer. If any errors occur, view the log for team project creation. It contains a list of the tasks that it tried to run and shows which tasks failed. You can map failed tasks back to the XML to determine the cause of the errors. You can clean up unnecessary team projects by using the TFSDeleteProject command-line tool.
	Verify changes to process templates. Before you put your process template in production mode and use it as the basis for several team projects, you should verify that it is well-defined. You perform this task by systematically verifying that each object and artifact works as expected. If you added a report, make sure that it appears in Team Explorer. If you added a field, make sure that you didn’t introduce any schema conflicts.

Q & A

Q: Can I use process templates other than the default ones that TFS provides?

A: Yes. Sometimes third parties make available process templates that they’ve created. You may need to do extra work after a TFS upgrade when using a process template provided by a third-party as described here.

You can do a search on CodePlex.com to determine if any process templates have been uploaded there.

Q: What permissions do I need to customize process templates?

A: To download or upload process templates, you must either be a member of the Project Collection Administrators group, or your Manage process template permission must be set to Allow. See Add accounts to administer project collections.

Q: What tools can I use to customize a process template?

A: You can use any text editor or XML editor to modify XML files. Or, you can use the Process Editor, a power tool for Visual Studio to customize process template files. To download, go to Team Foundation Server Power Tools.

The Process Editor provides a user interface that you can use to customize the following areas:

• Work item tracking:

  • Create and edit definitions for work item types, including adding fields, changing workflows and work item forms

  • Add or edit categories for grouping work item types

  • Edit the process configuration for Agile planning tools

  • Create and edit work item queries, and organize queries into query folders

  • Create and edit link types

• Project classifications and hierarchies:

  • Create and edit product area paths

  • Create and edit milestone releases or iteration paths

  • Modify the mapping file for Microsoft Project

• Security groups: Create and edit TFS groups and their permissions

• Version control:

  • Edit check-out settings

  • Create and edit check-in notes

  • Create and edit TFS groups and their permissions

• Portal and reports:

  • Review files to be uploaded and their folder structure

  • Add files to be uploaded.

Q: What resources are required to support specific plug-ins?

A: The Build, Portal, and Reporting plug-ins require these resources.

Plug-in	Team Foundation Build	SharePoint Products	SQL Server 2008 Analysis Services	SQL Server 2008 Reporting Services
Build
Portal			Recommended	Only required to support basic dashboards
Reporting

Q: Are there artifacts that I can’t customize in the process template?

A: Yes. You can’t customize Microsoft Excel reports and dashboards through the process template files. These artifacts are created for a team project depending on the selections that you make in the New Team Project wizard. For more information, see Customizing Team Foundation Server Project Portals.

Q: How is the ProcessTemplate.xml plug-in file used?

A: You use the ProcessTemplate.xml plug-in file to define which plug-ins to include in the template. This file contains all the task groups that you want to run to create a team project. Each task group references a subordinate XML plug-in file where the specific tasks for that plug-in are defined. Go here for more information.

Q: What do I need to know about dependencies?

A: Many objects rely on the definition of other objects within a process template.

For example, work item queries defined for the Agile process template use the iteration nodes that are defined in the Classification.xml file. If you change the iteration node definitions, you must modify the work item queries on which they rely. You can find these queries by searching for the following macros in the .wiq files:

• Iteration 1 = @@Iteration%201@@

• Iteration 2 = @@Iteration%202@@

• Iteration 3 = @@Iteration%203@@

For an overview of required plug-ins and plug-in dependencies, see Define dependencies for task groups and tasks in plug-in files.

Q: Are there restrictions I need to be aware of?

A: Yes. When you add objects to a process template, you will want to make sure that you label them correctly so that you avoid XML validation errors.

Review the following notes and tips:

• Restrictions are put on the names or labels of most Team Foundation objects. For an overview of naming restrictions that apply to process templates, security groups, area and iteration nodes, work item types, and work item fields, see Naming restrictions in Team Foundation.

• Most process template components that you customize will affect only the team project that you create by using the process template. The exceptions to this rule are global lists, link types, and work item fields that are defined for work item types. These objects are defined for a team project collection.

• Each work item field has an associated field reference name that uniquely identifies each field. The reference name cannot be changed after it is assigned.

  In addition, a work item field can have a reporting name that is assigned to it. The reporting name must match across all work item types that are defined for a team project collection. If they do not, validation errors might occur when you upload the process template, or conflicts might occur in the data warehouse databases.

  Work item field names, link type names, and global lists are scoped to a team project collection. If you customize any of these objects, the change will be reflected in all team projects that are defined in the collection and in the work item types that contain that work item field.

  For more information, see Naming conventions for work item tracking objects.

• The maximum size of a process template is two gigabytes. When you customize a process template, make sure that your changes do not increase its size beyond that value.

Q: Is their a reference for each XML element?

A: Process template files reference two main schema definitions. Plug-in files are based on the process template schemas, and the type definitions for work items are based on the schema for tracking work.

• Process template plug-ins: Index to XML element definitions

• Work item tracking: Index to XML element definitions

Q: Where can I learn more about the Configure Features wizard?

A: See Configure features after a TFS upgrade.

Q: Where can I go if I have more questions?

A: Go to the Microsoft forum: Team Foundation Server – Process Templates.