Update a customized process template to access new features

  • Article

TFS 2017 | TFS 2015 | TFS 2013

Important

This topic applies only to projects defined on an on-premises Azure DevOps Server. Projects defined on Azure DevOps Services update automatically with each service upgrade. To update a project that uses the Hosted XML process, see Import process.

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

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

    Do steps: Step 1, Step 2, Step 4, and Step 5

    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: Step 1, Step 3, Step 4, and Step 5

    Choose this option when you have made very few customizations to your process template.

  • Option C: Manually update your project to add features

    Choose this option when you've made customizations to your project that aren't present in any of your process templates.

  • Option D: Programmatically update many projects. First, choose Option A or Option B to update your customized process template. Then, batch update all projects defined for a project collection using the following information and resources: How to Configure Features for dozens of projects and Features4tfs CodePlex solution.

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

Tip

Optional information to help a user be more successfulReview Changes made to process templates to learn about changes made to the default process templates to enable 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.

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

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

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

  4. 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 project.

    To download or upload process templates, you must connect to TFS 2015 from either Visual Studio 2015 or Team Explorer 2015.

  5. 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 or updating the WITs, Categories, and ProcessConfiguration as described in Add features using a manual update process. Instead of using witadmin to export and import definition files, simply make the changes directly to your process template files.

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.

Review Changes made to process templates to learn about all the changes made to the default process templates to enable new features.

Add a WIT to a process template

Perform the following steps for each WIT that you add to your process template. This example shows how to add the Epic WIT to your process template.

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

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

    <CATEGORY name="Epic Category" refname="Microsoft.EpicCategory">
<DEFAULTWORKITEMTYPE name="Epic" />
</CATEGORY>

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

    1. Add a task for uploading the Feature work item type to the <WORKITEMTYPES> section.

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

  4. 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 your ProcessConfiguration definition. For more information, see Process Configuration XML Reference.

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

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

  1. 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 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 than 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.

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

    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)

    To support the team configurable setting to show bugs on backlogs and boards, 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 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 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.

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.

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

  2. Update the name to reflect the version changes you've made. For example:

    <name>MyCompany Custom Scrum </name>

  3. 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 change the guid in the version to 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="14" minor="1"/>
    CMMI <version type="27450541-8E31-4150-9947-DC59F998FC01" major="14" minor="1"/>
    Scrum <version type="6B724908-EF14-45CF-84F8-768B5384DA45" major="14" minor="1"/>

    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 isn't present, the Configure Features wizard can't select the process template for updating a project. Also, if more than one process template has been uploaded that specifies the same highest version number, then none of these process templates can be selected for updating a project.

  4. Upload the process template.

    To verify your changes, create a test project. See create a project.

5. Run the Configure Features wizard

Step 5 When you've verified that the process template supports your customizations, run the Configure Features wizard to update your existing projects.

  1. Verify the features work as expected by exercising them as described in the following articles:

    Feature

    Changes

    Code Review

    Request a code review from the My Work page in Team Explorer. My Work only appears when you have Visual Studio Premium or Visual Studio Ultimate installed.

    My Work

    Develop code and manage pending changes from the My Work page in Team Explorer. My Work only appears when you have Visual Studio Premium or Visual Studio Ultimate installed.

    Feedback

    Request feedback.

    Planning Tools

    Create your backlog, plan a sprint, work with the Kanban board, and more.

    Storyboarding

    Launch Storyboarding or link a storyboard to a work item.

    Portfolio Backlogs

    Select the portfolio backlogs they work with to organize their backlogs.

    Shared Parameters

    You use Shared Parameter work items to run tests with different data.

    Test Plan and Test Suite

    Create test plans and test suites.

    Bug Behavior

    Configure the option as described in Show bugs on backlogs and boards feature.

  2. Apply additional configuration options based on those features of interest.

Keep these tips in mind when modifying process template files:

  • See Overview of process template files for information about each folder and file contained within the interdependent set of files.
  • Don't remove a file or a task from the set 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.

You can learn more about each process template definition files from these resources:

You can post a question or search for answers to your update questions in one of these forums: Team Foundation Server - work tracking (Archived) or the Developer Community page.

Customizations that interfere with smooth updates

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

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.

Add portfolio backlog levels

You can add up to five portfolio backlogs total. This includes the Feature and Epic portfolio backlogs. You can add this to a custom process template or after your project is updated. To get started, see Add a portfolio backlog.

Rename a work item type

Use witadmin renamewitd command to change the name, and then update the Categories definition file. To learn more, see Add or modify a work item type.