Update a customized process template to access new features

Article
09/18/2015

Go here to open the Visual Studio 2015 version of this topic.

When the Configure Features wizard can’t update your team project, it’s because your team project was created from a process template other than those TFS provides, or you’ve customized your team project in ways that conflict with its ability to apply the updates. In these situations, you have these options to update your existing team projects:

Option A: Add features to your customized process template, and then run the Configure Features wizard

Do steps: , , , and

Choose this option when you have made extensive customizations to your process template.
Option B: Apply your customizations to the latest process template, and then run the Configure Features wizard

Do steps: , , , and .

Choose this option when you have made very few customizations to your process template.
Option C:Manually update your team project to add features

Choose this option when you’ve made customizations to your team project that aren’t present in any of your process templates.
Option D: Programmatically update many team projects. First, choose Option A or Option B to update your customized process template. Then, batch update all team projects defined for a team project collection using the following information and resources: How to Configure Features for dozens of team projects and Features4tfs CodePlex solution.

Choose this option when you have dozens of team projects that were created from the same process template.

To learn more about additions made to the latest default process templates, see Configuration changes made to add new features.

1. Download the latest process template

Step 1 You will copy or add files from the folder of the latest version of process template that you download to the corresponding folder containing your customized process template definitions.

If you’re updating a process template based on a version earlier than MSF 6.0 or Visual Studio Scrum 2.0, first apply the updates provided in the 2012 version of this topic.

You can check the ProcessTemplate.xml file for version information.
If you haven’t upgraded your application-tier server to the TFS version that contains the features you want, do that now. Get the download and Upgrade Team Foundation Server.
If you aren’t a member of the Project Collection Administrators group, get added. You need the Manage process template permission set to Allow to download and manage process templates.
After TFS has been upgraded, download the latest process template from TFS and choose the process template that most closely matches the one used to create your team project.

See Download the latest version of the process templates.

To download or upload process templates, you must connect to TFS 2013 from either Visual Studio 2013 or Team Explorer 2013.
Copy the process template to a new folder where you’ll apply your customizations (Option B), or copy XML definitions to add new features to your existing process template (Option C).

2. Add features to your customized process template (Option A)

Step 2 Update your customized process template by adding the following work item types (WITs):

Feature supports managing portfolio backlogs.
Shared Parameter supports repeating tests with different data.
Test Plan and Test Suite support customization of these artifacts and the ability to query against these WITs. Additional changes were introduced, as described in the following two topics: New features enabled for Team Web Access and Plan manual tests.

Copy or add files from the folder of the latest version of process template that you download to the corresponding folder containing your customized process template definitions.

Add Feature and portfolio backlog support (required TFS 2013)

Copy the Feature.xml file from the WorkItem Tracking/TypeDefinitions folder to the corresponding folder of your customized process template.

Add the Feature Category to the Categories file located in the WorkItem Tracking folder.

<CATEGORY name="Feature Category" refname="Microsoft.FeatureCategory">
    <DEFAULTWORKITEMTYPE name="Feature" />
  </CATEGORY>

Open the WorkItems plug-in file located in the WorkItem Tracking folder.

Add a task for uploading the Feature work item type to the <WORKITEMTYPES> section.
```
<WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\Feature.xml" />
```

Replace the two process configuration tasks within the PROCESSCONFIGURATION element…

<PROCESSCONFIGURATION>
   <CommonConfiguration fileName="WorkItem Tracking\Process\CommonConfiguration.xml"/>
   <AgileConfiguration fileName="WorkItem Tracking\Process\AgileConfiguration.xml"/>
</PROCESSCONFIGURATION>

.. with the single element statement that references the ProcessConfiguration file.

<PROCESSCONFIGURATION>
   <ProjectConfiguration fileName="WorkItem Tracking\Process\ProcessConfiguration.xml"/>
</PROCESSCONFIGURATION>

Copy the ProcessConfiguration file from the WorkItem Tracking/Process folder of the downloaded process template to your customized template folder in the same location.

Incorporate any customizations that you made to the AgileConfiguration or CommonConfiguration files to ProcessConfiguration. For more information, see Process Configuration XML Reference.
Delete the AgileConfiguration and CommonConfiguration files from the WorkItem Tracking/Process folder.

Process configuration is now supported by the single file ProcessConfiguration.
Replace the Backlog/Stories/Requirement Overview.rdl and Stories/Requirements Progress.rdl files in the Reports folder of your customized template folder with the files of the downloaded process template in the same location.

These updates reflect changes required with the introduction of the Feature portfolio backlog work item type as described in this blog post: Update your Overview and Progress reports to support the Portfolio backlogs.
Replace the Process Guidance folder, located under Windows SharePoint Services folder, with the contents of the latest folder.

These files provide forward links to the latest process guidance content.

Add Shared Parameters support (required TFS 2013.2)

Copy the SharedParameter.xml file from the WorkItem Tracking/TypeDefinitions folder to the corresponding folder of your customized process template.

Add the Shared Parameter Category to the Categories file located in the WorkItem Tracking folder.

<CATEGORY name="Shared Parameter Category" refname="Microsoft.SharedParameterCategory">
    <DEFAULTWORKITEMTYPE name="Shared Parameter" />
  </CATEGORY>

Add Shared Parameter to Hidden Types Categories.

<CATEGORY name="Hidden Types Category" refname="Microsoft.HiddenCategory">
    <DEFAULTWORKITEMTYPE name="Code Review Request" />
    <WORKITEMTYPE name="Code Review Response" />
    <WORKITEMTYPE name="Feedback Request" />
    <WORKITEMTYPE name="Feedback Response" />
    <WORKITEMTYPE name="Shared Steps" />
    <WORKITEMTYPE name="Shared Parameter" />  </CATEGORY>

Open the WorkItems plug-in file located in the WorkItem Tracking folder.

Add a task for uploading the Shared Parameter WIT to the <WORKITEMTYPES> section.

<WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\SharedParameter.xml" />

Add test plan and test suite WITs (required TFS 2013.3)

When you upgrade your application-tier server to TFS 2013.3, the TFS Upgrade Wizard automatically updates your existing team projects to support the new work item tracking objects for test plans and test suites.

Changes are made to your team project but no changes are made to any existing customized process templates. You can manually update your customized process templates, however. Reasons you'd do this include supporting future TFS upgrades that require using the Configure Features Wizard, or if you plan to create team projects with your customized process template on your upgraded server. You need to manually add these objects to your customized process templates.

Copy the TestPlan.xml and TestSuite.xml files from the WorkItem Tracking/TypeDefinitions folder to the corresponding folder of your customized process template.

Add the Test Plan Category and Test Suite Category to the Categories file located in the WorkItem Tracking folder.

<CATEGORY name="Test Plan Category" refname="Microsoft.TestPlanCategory">
    <DEFAULTWORKITEMTYPE name="Test Plan" />
  </CATEGORY>
  <CATEGORY name="Test Suite Category" refname="Microsoft.TestSuiteCategory">
    <DEFAULTWORKITEMTYPE name="Test Suite" />
  </CATEGORY>

Add the Test Plan Category and Test Suite Categoryto Hidden Types Categories.

<CATEGORY name="Hidden Types Category" refname="Microsoft.HiddenCategory">
    <DEFAULTWORKITEMTYPE name="Code Review Request" />
    <WORKITEMTYPE name="Code Review Response" />
    <WORKITEMTYPE name="Feedback Request" />
    <WORKITEMTYPE name="Feedback Response" />
    <WORKITEMTYPE name="Shared Steps" />
    <WORKITEMTYPE name="Shared Parameter" />
    <WORKITEMTYPE name="Test Plan" />
    <WORKITEMTYPE name="Test Suite" />
  </CATEGORY>

Open the WorkItems plug-in file located in the WorkItem Tracking folder.

Add a task for uploading the Test Plan and Test Suite WITs to the <WORKITEMTYPES> section.

<WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\TestPlan.xml" />
<WORKITEMTYPE fileName="WorkItem Tracking\TypeDefinitions\TestSuite.xml" />

3. Apply your customizations to the process template (Option B)

Step 3 With this option, you apply customizations you’ve made to your team project or process template to the latest process template that most closely matches the template used to create your team project.

Apply the customizations that you’ve made to the new process template folder:
- Apply customizations you’ve made to the default work item type (WIT) definitions. This could include additions of fields or modifications to the workflow or form.
- Add custom WITs to the work item tracking folder, and update the WorkItems definition file as needed. See Add type definitions for work items to a process template.
  
  If you want to use a customized WIT that contains the same name as those in the default process template, then make sure that you swap out the WIT definition files. If you want to use a customized WIT with a different name that that provided in the default process template, then you’ll need to modify the categories and process configuration definition files prior to import to reflect the different naming.
- Apply customizations to the Categories definition file.
- Apply customizations to the ProcessConfiguration definition file. Check that the WITs that you want are represented in the correct categories and that all workflow states are mapped to metastates.
- Copy any additional process template files that you’ve customized to the appropriate process template folder. For a complete list of process template files and information about customizing them, see Overview of process template files.

Review your changes against this checklist to make sure that you have applied all the required customizations:

Customization	Update or verify the WIT definition	Update or verify the process configuration definition
Add a WIT to the Requirement Category (A WIT can belong to the Requirement Category or the Task Category, but not both.)	To include the following fields: The field value assigned to type=Order in the process configuration file (Backlog Priority in Scrum, Stack Rank in Agile or CMMI) The field value assigned to type=Effort in the process configuration file (Effort (Scrum), Story Points (Agile), or Size (CMMI)) The Area path or the field value assigned to type=Team in the process configuration file. All fields that are included in the AddPanel section of the process configuration file (fields must be defined within the FIELDS section but don’t have to be included within the FORM section.	To contain the necessary metastate mappings under the RequirementBacklog section: Map the initial states of each WIT in the Requirement Category to type="Proposed" Map each intermediate workflow state you want to have show up on the Kanban board to type="InProgress" Map the end of each workflow state to type="Complete" You can have more than one State mapped to type="Complete" To contain an entry to define the color codes associated with the WIT. For example: <WorkItemColor primary="FF009CCC" secondary="FFD6ECF2" name="Product Backlog Item" />
Change the workflow of a WIT in the Requirement Category	N/A	To contain the necessary metastate mappings as described above for adding a WIT to the Requirement Category.
Add a WIT to the Task Category	To include the following fields: The field value assigned to type=Order in the process configuration file (Backlog Priority in Scrum, Stack Rank in Agile or CMMI) The field value assigned to type=Activity in the process configuration file (Activity (Scrum or Agile) or Discipline (CMMI) ) Area path or the field value assigned to type=Team in the process configuration file The field value assigned to type=RemainingWork in the process configuration file (Remaining Work) (Optional) Original Work and Completed Work (Agile and CMMI only)	To contain the necessary metastate mappings under the TaskBacklog section: Map the initial states of each WIT in the Task Category to type="Proposed" Map each intermediate workflow state that you want to have show up on the task board to type="InProgress" Map the end of each workflow state to type="Complete" You can have more than one State mapped to type="Complete" To contain an entry to define the color codes associated with the WIT. For example: <WorkItemColor primary="FFF2CB1D" secondary="FFF6F5D2" name="Task" />
Change the workflow of a WIT in the Task Category	N/A	To contain the necessary metastate mappings as described above for adding a WIT to the Task Category.
Add a WIT to the Bug Category or change the workflow of a WIT in the Bug Category (Agile and CMMI only) (See Note a)	To support the team configurable setting to add bugs to the backlog, include the following fields: The field value assigned to type=Order in the process configuration file (Backlog Priority in Scrum, Stack Rank in Agile or CMMI) The field value assigned to type=Effort in the process configuration file (Effort (Scrum), Story Points (Agile), or Size (CMMI))	To contain the necessary metastate mappings under the BugWorkItems section: Map the initial state of each WIT in the Bug Category to type="Proposed" Map each intermediate workflow state you want to have show up on the Kanban Board or for My Work to type="InProgress" Map the end of each workflow state type="Complete" You can have more than one State mapped to type="Complete" To learn more, see Support bug update status using My Work.
Remove a WIT from the Requirement Category or Task Category	N/A	To remove any metastate mappings that are only associated with that WIT
Remove a WIT	Remove the WIT from the categories file	To remove any metastate mappings that are only associated with the WIT that you removed and the WorkItemColor element that defines the color codes for the WIT you removed.
Rename a WIT	Update the categories file with the new names	Update the process configuration file with the new names

Notes:

If you’ve updated to TFS 2013.4, see Add bugs to the backlog or task board. TFS 2013.4 introduces a setting which enables each team to view bugs on their backlog and Kanban board. This feature references the metastate mappings made under BugWorkItems.

4. Rename and upload the process template to TFS

Step 4 For the Configure Features wizard to select the latest version of a process template, you must update the version statement to differentiate your updated process template version from previous versions.

Open the ProcessTemplate plug-in file located in the top folder.

Update the name to reflect the version changes you’ve made. For example:
```
<name>MyCompany Custom Scrum 2013.3  </name>
```

Update the code snippet after the description element. Increase the minor version to reflect that you’ve made updates to the existing process template and distinguish it from the default TFS process template.

Your choice of code snippet is based on the template category that you are updating:

Category	Version statement
Agile	`<version type="ADCC42AB-9882-485E-A3ED-7678F01F66BC" major="7" minor="20"/>`
CMMI	`<version type="27450541-8E31-4150-9947-DC59F998FC01" major="7" minor="10"/>`
Scrum	`<version type="6B724908-EF14-45CF-84F8-768B5384DA45" major="3" minor="10"/>`

5. Run the Configure Features wizard

Step 5 When you’ve verified that the process template supports your customizations, run the Configure Features wizard as to update your existing team projects. See Configure features after a TFS upgrade.

Q & A

Q: What types of customizations stop the Configure Features wizard from being able to update a team project?

A: The following changes made to a process template can interfere with the Configure Features wizard’s ability to run:

Renamed or removed WITs that belong to the Requirement Category or Task Category.
Renamed states or customized workflow states defined for WITs that belong to the Requirement Category or Task Category. Metastates define how planning tools treat each workflow state. At least one workflow state must map to the InProgress and to the Completed metastates
Removal of fields defined for WITs that belong to the Requirement Category or Task Category. These fields are defined in the ProcessConfiguration definition file and include the fields used to manage backlog priority, effort, task activity or discipline, and remaining work.

To learn more, see Process configuration XML element reference.

Q: How is the version statement in process templates used?

A: The Configure Features wizard uses the version statement to determine which process template within a category is the latest version and automatically selects that version.

If the version statement is not present, the Configure Features wizard cannot select the process template for updating a team project. Also, if more than one process template has been uploaded to TFS that specifies the same highest version number, then none of these process templates can be selected for updating a team project.

Q: I’m new to working with process templates. What should I know about making manual updates?

A: Keep these tips in mind when modifying process template files:

For an overview of what process templates are and their files and folders, see Customize a process template Overview of process template files.
Do not remove a file or a task in order to upload a file unless you know what the file is and that you will have no use for it.
To locate the customizations that you have made, you can perform a diff operation on comparable files that exist in the two templates. However, you could receive some false positives because the sequence of element definitions might have changed between two versions.
You can search for the dependency element across all plug-in files to learn what tasks depend on other tasks that are being completed. For example, Microsoft Test Manager and Lab Management require the SharedSteps and TestCase work item types, the SharedSteps and TestedBy links types, and categories. See Define dependencies for task groups and tasks in plug-in files.

Q: How do I rename a work item type?

A: Use witadmin renamewitd command to change the name, and then update the Categories definition file. To learn more, see Modify or add a custom work item type (WIT).

Q: What if I want to use more than one level of portfolio backlog?

A: You can add up to five portfolio backlogs. This includes the default backlog of Feature. You can add this to a custom process template or after your team project is updated. To get started, see Add a Portfolio Backlog.

Q: Where can I learn more about the definition files to modify?

A: See these topics for more information:

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

A: You can post a question or search for answers in one of these forums: Team Foundation Server - Work Item Tracking or Team Web Access.