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 might 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 might 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.
.png "Process Template Customization Workflow")
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.
Note
The Microsoft Solutions Framework (MSF) process templates that were installed with Team Foundation Server are replaced by new versions when you upgrade to the current release of Team Foundation Server. If you have customized the old templates and saved them by the same name, they should be downloaded before you upgrade, or they will be replaced and your customizations will be lost.
If you want to update your customized process templates so that they are based on the most recent version of the MSF templates, they must be manually updated. For more information, see Update a Customized Process Template to Access New Features.
1. 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.
You can download an existing process template to use as your base for customization. You can download process templates by using the Process Template Manager. For more information, see Step-by-Step Customization Process.
Back to top
2. 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 Customize 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:
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 Define 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 Customize and Manage 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.
Note
You can download the power tool from the following page on the Microsoft Web site: Team Foundation Server Power Tools.
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.
.png "Work Item Tracking Objects")
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.
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 Define the Tasks to Process a Plug-in and Define 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.
Step |
Task |
Notes and dependencies |
|---|---|---|
|
You define areas to organize work items into logical, physical, or functional categories. You define iterations to group work items into milestones or time cycle categories. The Classification plug-in is required for all process templates. |
|
|
You can set permissions for a collection, project, area or iteration path, and event subscriptions. The tasks in the Groups and Permissions plug-in may have dependencies on the defined in the Classification plug-in. |
|
|
Specify the objects for tracking work, the work item queries, and the work item instances to upload. |
You must specify the tasks to upload files and define queries in a specific sequence: first link types, then work item types, then queries. Each definition file for these objects depends on the definitions that are specified in the tasks that precede them. In general, you should maintain the task sequence that is defined in the process template that you are customizing. Definitions of work item types may depend on the Classifications and Groups and Permissions plug-ins. |
|
Define default policies and permissions for version control. |
You configure a team project's initial permissions, check-out policies, and check-in notes by customizing the Version Control plug-in. |
|
Define default build permissions and tasks to support build operations. |
By customizing the Build plug-in, you configure a team project's initial permissions and template files that Team Foundation Build Service uses. |
|
You can define settings such as test variables and test configurations that combine test variables by customizing the Test Management plug-in. In addition, you can customize the default test settings and the list of valid test resolution states. |
|
|
You can configure a team project's initial permissions and template files by customizing the Lab plug-in. |
|
|
Define the reports to upload and the folder structure of the Reports node. |
You can modify the set of .rdl reports to upload. The Reporting plug-in is required to create the Reports node for a team project. The Reporting plug-in requires that the team project collection where you will create a team project has been configured with SQL Server Analysis Services and SQL Server Reporting Services. |
|
You can modify the set of documents to upload and the features to activate. The Portal plug-in is required to create the Documents node for a team project. The Portal plug-in requires that the team project collection where you will create a team project has been configured with SharePoint Products. |
.png "Step 1")
.png "Step 2")
.png "Step 3")
.png "Step 4")
.png "Step 5")
.png "Step 6")
.png "Step 7")
.png "Step 8")
.png "9")
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 Define 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.
Agile plug-in sequence |
CMMI plug-in sequence |
|---|---|
|
|
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
3. 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 Step-by-Step Customization Process.
Back to top
4. 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 Delete a Team Project [TFSDeleteProject].
Back to top
5. 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.
Back to top
See Also
Tasks
Reference
Customize and Manage Work Item Types [witadmin]