Step-by-Step Customization Process

You will want to customize a process template to make sure that all team projects that are created by using the template follow the business processes that your team or organization uses. Also, you may want to customize a process template if you upgrade Visual Studio Team Foundation Server from a previous release and you made changes to an existing process template that you want to continue to use. You may want to add these changes to a new process template or customize the old template to add functionality that was provided in the current release.

To customize a process template, you first download an existing or blank process template, modify or add files, upload the process template files, and then verify your changes. The following illustration shows the sequence of the five main tasks that you perform 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.

This topic provides the recommended sequence and operational tips to support your activities to customize a process template.

In this topic

1. Select and Download a Process Template

2. Customize Your Process Template

3. Upload the Process Template

4. Create a Team Project

5. Verify Your Changes

Select and Download a Process Template

The first step in customizing a process template is to select the process template that you want to customize. To minimize the modifications that you must make, you should 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. For a comparison of process templates for the Microsoft Solutions Framework (MSF), see Choose a Process Template.

For more information about MSF process templates and additional templates that are available from Microsoft partners, see the following page on the Microsoft website: Process Templates and Tools.

You can download an existing process template to use as your base for customization. Depending on the extent of your customizations, you can download a blank template or one that is completely designed. You can download process templates by using the Process Template Manager. For more information, see Download a Process Template.

Back to top

Customize Your Process Template

Before you start to customize your process template, review the following sections for additional guidance, recommended sequences, and useful tools.

• Plan Your Process Template Changes

• Modify Files or Use the Process Editor

• Create or Customize Objects to Track Work

• Customize Plug-in Files

• Customize the Root Process Template File

Back to top

Plan Your Process Template Changes

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 work item tracking, reporting, Team Foundation Build, Team Foundation version control, Microsoft Test Manager, and Visual Studio Lab Management.

For customization guidelines and an overview of the objects that you can customize to track work, see Customizing Project Tracking Data, Forms, Workflow, and Other Objects. For a useful checklist, see Checklist: Plan and Track Changes to Your Process Template.

In addition, review the following notes and tips:

• For an overview of the resources that are required to support team project artifacts, see Launching a New Team Project.

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

• You can modify most functional areas of a process template after you create a team project. The only area that you cannot modify is the test resolution states that are used by Test Runner and Microsoft Test Manager. For more information, see Defining the Initial Configuration of Test Manager.

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

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

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

  For more information, see Add and Customize a Type of Work Item and Customizing and Managing Work Item Types [witadmin].

Back to top

Modify Files or Use the Process Editor

Customizing a process template consists of modifying one or more process template files to add or remove tasks that specify the upload of files to the team project collection. When you modify a process template file, you should understand the dependencies that exist across plug-in elements and of restrictions on naming objects and work item fields.

If you have minor changes and are comfortable working with the XML format, you can modify files by using NotePad or another text editor. In addition, you can use the Process Editor, which is a power tool that is installed as an add-in to Visual Studio.

The Process Editor provides a user interface that you can use to customize many areas in a process template. You can use the editor to modify the most recent versions of the MSF process templates. Specifically, you can use the editor to customize the following areas:

• Work Item Tracking:

  • Create and edit definitions for work item types.

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

  • Create and edit link types.

  • Create and edit categories for grouping work item 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 groups and permissions for Team Foundation Server.

• Version Control:

  • Edit check-out settings.

  • Create and edit check-in notes.

  • Create and edit groups and permissions for Team Foundation Server.

• Portal and Reports:

  • Review files to be uploaded and their folder structure.

  • Add files to be uploaded.

Back to top

Create or Customize Objects to Track Work

You can customize how you track your team project, and you can design your workflow, work item forms, and data fields by customizing one or more objects for tracking work items. You can create or customize all types of objects that the following illustration shows, except for global workflow. In addition to these objects, you can define work item queries and work item instances.

For more information about how to define or customize these objects, see the following topics:

• For types of work items: All WITD XML Elements Reference.

• Working with Link Types

• Working with Work Item Type Categories

• Defining Global Lists

• Define a Work Item Query to Add to a Process Template

• Add a Work Item Instance to a Process Template

Back to top

Dependencies Between Classifications and Work Item Queries

The work item queries that are defined for the MSF process template for agile software development 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@@

Back to top

Restrictions on Naming Work Item Objects

Each work item field has an associated field reference name that uniquely identifies each field and 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 may 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.

Back to top

Customize Plug-in Files

Each plug-in file specifies one or more tasks to process, and each plug-in file performs a unique set of tasks. If you add or remove a file for upload, make sure that you add or remove the task in the corresponding plug-in file that specifies the file to be uploaded. In addition, some tasks that are defined in the plug-in files have dependencies. Make sure that all dependencies are still met after you have made your changes. For more information, see Defining the Tasks to Process a Plug-in and Defining Dependencies for Task Groups and Tasks in Plug-in Files.

The following table describes the recommended sequence for customizing the nine supported plug-in files and provides a link to the related task and topic.

Back to top

Customize the Root Process Template File

The sequence of tasks that the New Team Project wizard performs is determined by the sequence of grouped tasks that are defined in the ProcessTemplate.xml file and the plug-in files that it calls. For more information, see Defining the Root Tasks Using the Process Template Plug-in File. The following table lists the sequence that is defined in the process templates for MSF.

If you list your tasks in each plug-in file in the same order as their dependencies, you eliminate potential problems with missing dependencies.

Back to top

Upload a Process Template

When you upload a process template, you upload it to a team project collection. 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.

For more information, see Upload a Process Template.

Back to top

Create a Team Project

After you upload a process template, you must create a team project so that you can verify your change. Run the New Team Project Wizard, and create a test team project. 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.

For more information, see Create a Team Project.

To test new process templates, you must create team projects. You can clean up unnecessary team projects by using the TFSDeleteProject command-line tool. For more information, see TFSDeleteProject: Deleting Team Projects.

Back to top

Verify Your Changes

If the team project is created successfully, perform additional steps to verify that your change appears in the team project correctly. If you added a report, make sure that it appears in Team Explorer. If you removed a work item type, make sure that the work item type that you removed is no longer available. For each plug-in that is documented, a list of verification steps is provided to help you make sure that your changes are implemented.

For more information, see Verifying Changes to Process Templates.

Back to top

See Also

Tasks

Create a Team Project

Reference

Customizing and Managing Work Item Types [witadmin]

Concepts

Working with Process Template Files

Managing Process Templates

Customizing Process Templates

Other Resources

Verifying Changes to Process Templates

Change History