Del via

Add updates to projects manually

  • Artikkel

TFS 2017 | TFS 2015 | TFS 2013

Important

This article applies only to projects defined on an on-premises Team Foundation Server (TFS). Projects defined on Azure DevOps Services update automatically with each service upgrade.

For an overview of customization options, see Customize your work tracking experience

You can update projects that were created in earlier versions of Team Foundation Server (TFS) to use new features added with the upgrade to TFS. These new features are delivered through new work item type definitions or updates to the process configuration. You should update projects by using the Configure Features wizard. However, if the wizard is unable to add a feature, you can add it manually.

Note

If you're upgrading a project that was based on a Microsoft Solutions Framework (MSF) version 4.2 process template, follow the procedures provided in Update a project based on a MSF v4.2 process template. If you have several projects you need to update, see apply updates programmatically.

Update a project

Prior to manually adding or editing a work tracking object, first download the latest process template. You'll use the definition files from the process template that most closely matches your existing project.

Several features, such as Code Review and Feedback, simply require importing WITs from the process template that you download, and updating the Categories and ProcessConfiguration file. Other features, however, may require more extensive changes depending on the customizations you've made to your project.

Note

Follow the links for each step to detail procedures provide later in this topic.

Feature Steps to manually add a new feature
Code Review
  1. Download the latest process template: Get the definitions you need to import or update
  2. Import WITs: Code Review Request and Code Review Response
  3. Update Categories:
    • Add the Code Review Request and Code Review Response Categories
    • Add the Code Review Request and Code Review Response Categories to the Hidden Types Category
  4. Update ProcessConfiguration: Add work item colors for Code Review Request and Code Review Response
  5. To verify, create a code review request.
My Work
  1. Download the latest process template: Get the definitions you need to import or update
  2. Import WITs: Code Review Request and Code Review Response
  3. Update Categories: Verify Bugs Category is present and contains the Bug WITs you use to track bugs.
  4. Update ProcessConfiguration: Add the BugWorkItems section and verify or add custom state-to-metastate mappings to the BugWorkItems section
  5. To verify, check in a code fix and check that the bug state automatically updates.
Note: If you use other WITs to support bug tracking or you've customized the workflow for the WITs you include in the Bug Category, see Support bug update status using My Work.
Feedback
  1. Download the latest process template: Get the definitions you need to import or update
  2. Import WITs: Add the Feedback Request and Feedback Response WITs
  3. Update Categories:
    • Add the Feedback Request and Feedback Response Categories
    • Add the Feedback Request and Feedback Response Categories to the Hidden Types Category
  4. Update ProcessConfiguration :
    • Add the Feedback Request and Feedback Response Categories
    • Add TypeField field mappings to support Feedback
    • Add work item colors for Feedback Request and Feedback Response to ProcessConfiguration
  5. To verify, create a feedback request.
Planning Tools
  1. Download the latest process template: Get the definitions you need to import or update
  2. Edit WITs:
    • Add fields that support planning tools to WITs that you include for the Requirement Category, Task Category, and Bug Category
    • Edit the workflow of WITs that you include for the Requirement Category, Task Category, and Bug Category to support any-to-any transitions; add Removed state if not present.
      If you're upgrading a project that was based on version 5.0 of the Microsoft Solutions Framework (MSF) Agile process template, follow the procedures provided in Update the workflow for agile projects.
  3. Update Categories:
    • Add Categories if not present
    • Add custom WITs to the Requirement Category and Task Category
  4. Update ProcessConfiguration:
    • Add ProcessConfiguration if not present.
    • Add RequirementBacklog and TaskBacklog if not present.
    • Verify or update the metastate mappings for the Requirement Category, Task Category, and Bug Category
    • Add TypeField field mappings to support planning tools
    • Add work item colors for those WITs that you include in the Requirement Category, Task Category, and Bug Category
  5. To verify, start creating your backlog.
Storyboarding
  1. Edit WITs: Add StoryboardsControl to the FORM section of those WITs you include in the Requirement Category; for example, add it to the User Story (Agile), Requirement (CMMI), or Product backlog item (Scrum)
  2. To verify, open Storyboarding from the WIT you updated.
Portfolio Backlogs
  1. Download the latest process template: Get the definitions you need to import or update
  2. Import WITs: Add the Feature and Epic WITs
  3. Update Categories: Add the Feature and Epic Categories
  4. Update ProcessConfiguration:
    • Add PortfolioBacklogs section
    • Add work item colors for Feature and Epic to ProcessConfiguration
    • Add the HiddenBacklogs property to ProcessConfiguration
  5. To verify, add some features and epics.
Note: To add additional portfolio backlogs or further customize your portfolio backlogs, see Add a portfolio backlog level.
Shared Parameters
  1. Download the latest process template: Get the definitions you need to import or update
  2. Import WITs: Add the Shared Parameter WIT
  3. Update Categories:
    • Add the Shared Parameter Category
    • Add the Shared Parameter Category to the Hidden Types Category
  4. Update ProcessConfiguration: Add a work item color for the Shared Parameter to ProcessConfiguration
  5. Verify that you can add a shared parameter set or convert to shared parameters.
Test Plan and Test Suite
  1. Download the latest process template: Get the definitions you need to import or update
  2. Import WITs: Test Plan and Test Suite
  3. Update Categories:
    • Add the Test Plan and Test Suite Categories
    • Add the Test Plan and Test Suite Categories to the Hidden Types Category
  4. Run the TfsConfig TCM: Migrate existing test plans and suites to work item based test plans and suites.
  5. To verify, create a test plan using the web portal
Bug Behavior
  1. Download the latest process template: Get the definitions you need to import or update
  2. Edit WITs:
    • Agile Bug:
      • Add fields: Activity, Story Points, Original Work, Completed Work, Remaining Work, Severity, and Value Area
      • Add New state and corresponding workflow transitions
      • Add field rules to copy or set defaults during state transitions
      • Add Fixed and verified as a Resolved Reason
    • CMMI Bug:
      • Add fields: Size, Discipline, Original Work, Completed Work, and Value Area
      • Add New state and corresponding workflow transitions
    • Scrum Bug:
      • Add fields: Activity, Remaining Work, Priority, and Value Area
      • Add rule to zero out Remaining Work when State=Done
  3. Edit ProcessConfiguration: Add the BugsBehavior property
  4. To verify, go to the team settings admin page to choose how the team tracks bugs.

Get the latest version of the most compatible process template

The quickest way to make many of these updates is to copy definition files from the latest process template and import them to your project.

Important

If you are connecting to Azure DevOps Services, you can't export a process template. Instead, you customize your work tracking experience using the inheritance process. For details, see Process customization and inherited processes.

  1. Open the same version of Visual Studio or Team Explorer as the on-premises TFS that you connect to. For example, if you connect to a TFS 2017 instance, you must connect from Visual Studio 2017, Visual Studio Community 2017, or Visual Studio Team Explorer 2017.

    You can always download a free version of Visual Studio and Team Explorer from the Visual Studio download site.

    If you aren't a member of the Project Collection Administrators group, get added as one.

  2. Open the Process Template Manager from the Team>Team Project Collection Settings menu.

    Open Process Template Manager

    You'll see a list of each process template that has been uploaded to the project collection.

    Select process template to work with

    The Upload, Download, Make Default, and Delete buttons are disabled when you don't have the necessary permissions to manage process templates.

  3. Download the process template to a local computer, select a folder where the process template will be downloaded.

    Choose the process that corresponds to the one you used previously to create your project. For example, if you're updating a project based on the Scrum process template, then select Scrum. Note that all version numbers have been removed from the process templates. If you don't see Agile, CMMI, or Scrum, then you need to update TFS.

You can determine which process template to select based on the work item types defined for your existing project.

To learn more about managing process templates, see, Upload or download a process template.

Import a WIT

  1. Open a Command Prompt window according to the instructions provided in witAdmin: Customize and manage objects for tracking work. For example:

  1. Enter the witadmin importwitd command, substituting your data for the arguments that are shown.

    witadmin importwitd /collection:CollectionURL /p:"ProjectName" /f:"DirectoryPath\WITDefinitionFile.xml"

    For CollectionURL specify the URL of a project collection and for ProjectName specify the name of a project defined within the collection. You must specify the URL in the following format: http://ServerName:Port/VirtualDirectoryName/CollectionName.

    For DirectoryPath, specify the path to the WorkItem Tracking/TypeDefinitions folder that holds the process template that you downloaded. The directory path must follow this structure: Drive:\TemplateFolder\WorkItem Tracking\TypeDefinitions.

    For example, import the Feedback Request WIT:

    witadmin importwitd /collection:"http://MyServer:8080/tfs/DefaultCollection"/p:MyProject /f:"C:\MyTemplates\WorkItem Tracking\TypeDefinitions\FeedbackRequest.xml"

Here's a checklist of WITs to import to support new features:

  • Portfolio Backlogs: Epic and Feature
  • Code Review: Code Review Request and Code Review Response
  • Feedback: Feedback Request and Feedback Response
  • Shared Parameters: Shared Parameters
  • Test Plan and Test Suite: Test Plan and Test Suite

Edit a WIT

Depending on the customizations that you've made and the features you want to enable, you may need to update one or more WIT definition files. If you haven't customized a WIT, simply import the latest version. Otherwise, you can copy XML syntax from the WIT files you've downloaded from the latest process template.

  1. Export the WITs that you have defined for the corresponding category.

    witadmin exportwitd /collection:CollectionURL /p:ProjectName /n:TypeName [/f:FileName]

  2. Make the updates required to support your project and add new features. Review the following table for details on updates to make.

    WIT Category

    Edits to make

    Requirement Category

    For those WITs that you include in the Requirement Category, add or verify that the following fields are defined in the FIELDS section:

    • Agile: Stack Rank 1, User Story, Area Path, Priority, Acceptance Criteria, and Value Area
    • CMMI: Stack Rank 1, Size, Area Path, and Value Area
    • Scrum: Backlog Priority 1, Effort, Area Path, and Value Area.

    The fields you enter must correspond to the field values assigned in the ProcessConfiguration file for type=Order, type=Effort, and type=Team.

    • All fields that are included in the RequirementBacklog-AddPanel section of the ProcessConfiguration file
    • (Optional: All fields that are included in the RequirementBacklog-AddPanel section of the ProcessConfiguration file
    • All fields that are included in the RequirementBacklog-AddPanel section of the ProcessConfiguration file

    Update or verify the WORKFLOW section as follows:

    • Agile, User Story: Add transitions from Active to Removed and Resolved to Removed; remove rules that populate Activated By and Activated Date fields when state=Resolved
    • Scrum, Product backlog item: Add transition from Committed to Removed.

    If you've customized the WORKFLOW section, make sure to define the required state-to-metastate mappings in the ProcessConfiguration RequirementBacklog section.

    Bug Category

    For Bug or those WITs that you include in the Bug Category, add or verify that the following fields are defined in the FIELDS section:

    • Agile: Stack Rank1, User Story, Activity, Area Path, Remaining Work, Original Work and Completed Work
    • CMMI: Stack Rank1, Size, Area Path, Discipline, Remaining Work, Original Work and Completed Work
    • Scrum: Backlog Priority1, Effort, Activity, Area Path, and Remaining Work.

    The fields you enter must correspond to the field values assigned in the ProcessConfiguration file for type=Order, type=Effort, type=Team, type=Activity, and type=RemainingWork.

    • All fields that are included in the BugWorkItemsAddPanel section of the ProcessConfiguration file.

    Update or verify that the WORKFLOW section supports the following:

    • Agile: New and Removed states and transitions from New and Removed to all other states
    • CMMI: Stack Rank1, Size, Area Path, Discipline, Remaining Work, Original Work and Completed Work
    • Scrum: Backlog Priority1, Effort, Activity, Area Path, and Remaining Work.

    The fields you enter must correspond to the field values assigned in the ProcessConfiguration file for type=Order, type=Effort, type=Team, type=Activity, and type=RemainingWork.

    • All fields that are included in the BugWorkItems-AddPanel section of the ProcessConfiguration file. If you've customized the WORKFLOW, make sure to define the required state-to-metastate mappings in the ProcessConfiguration BugWorkItems section.

    Task Category

    For Task or those WITs that you include in the Task Category, add or verify that the following fields are defined in the FIELDS section:

    • Agile: Stack Rank1, User Story, Activity, Area Path, Remaining Work, Original Work and Completed Work
    • CMMI: Stack Rank1, Size, Area Path, Discipline, Remaining Work, Original Work and Completed Work
    • Scrum: Backlog Priority1, Effort, Activity, Area Path, and Remaining Work

    The fields you enter must correspond to the field values assigned in the ProcessConfiguration file for type=Order, type=Effort, type=Team, type=Activity, and type=RemainingWork.

    • All fields that are included in the TaskBacklog-AddPanel section of the ProcessConfiguration file.

    Add a rule to the WORKFLOW section to empty the Remaining Work field when the State=Closed or State=Done. For example:

    <STATE value="Closed">    
<FIELDS>    
<FIELD refname="Microsoft.VSTS.Common.ClosedDate">  
<REQUIRED />  
</FIELD>   
<FIELD refname="Microsoft.VSTS.Scheduling.RemainingWork">   
<EMPTY />   
</FIELD>   
</FIELDS>  
</STATE>

    If you've customized the WORKFLOW section, make sure to define the required state-to-metastate mappings in the ProcessConfiguration TaskBacklog section.

    Feature Category

    Update the Feature WIT:

    • Add the following fields to the FIELDS and FORM sections: Time Criticality, Effort, and Value Area
    • Add the ID to the FORM section
    • Add a Transition from Active to Removed in the WORKFLOW section.

    Note

    1 Don't add the Backlog Priority or Stack Rank fields to the FORM section. These fields support ordering of backlog items and aren't meant to be set manually.

  3. Import your WIT file.
    witadmin importwitd /collection:CollectionURL [/p:Project] /f:FileName "

Update Categories

Tip

See also Use categories to group work items and Import and export categories.

  1. Export your categories file.

    witadmin exportcategories /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\categories.xml"

    If you don't have a categories file, then copy the one from a default process template. Categories were introduced with TFS 2012 to more easily manage multiple work item types (WITs) as a group.

  2. Make the updates required to support your project and add new features. Here's a checklist of categories to import to add or verify to support new features:

    • Code Review: Code Review Request Category and Code Review Response Category
    • Feedback: Feedback Request Category and Feedback Response Category
    • Planning Tools: Requirement Category, Task Category, Bug Category, and Hidden Types Category
    • Shared Parameters: Shared Parameters Category
    • Portfolio Backlogs: Epic Category and Feature Category
    • Test Plan and Test Suite: Test Plan Category and Test Suite Category

    If you use custom WITs to support requirements or tasks, then you'll want to add or modify the Requirement Category and Task Category. For example, Fabrikam Fiber uses the following definitions to support their requirement tracking:

     <CATEGORY name="Requirement Category" refname="Microsoft.RequirementCategory">
    <DEFAULTWORKITEMTYPE name="Customer App" />
    <WORKITEMTYPE name="Service App" />
 </CATEGORY>

  3. Import your categories file.

    witadmin importcategories /collection:CollectionURL /p:ProjectName /f:"DirectoryPath\categories.xml"

Additional resources: Use categories to group work items, Import and export categories

Update ProcessConfiguration

Agile planning tools and Portfolio Backlogs depend on the WITs, categories, and process configuration definitions that are made. These definitions are interdependent. Always add new WITs, update categories, and then update the ProcessConfiguration in that order.

  1. Export your ProcessConfiguration file.

    witadmin exportprocessconfig /collection:CollectionURL /p:ProjectName /f:FileName

    If you don't have a ProcessConfiguration file, then copy the one from a default process template. ProcessConfiguration was introduced with TFS 2013 and replaced the CommonConfiguration and AgileConfiguration files.

  2. Make the updates required to support your project and add new features. If you've customized the workflow for WITs defined in the Requirement, Task, Bug, Epic, or Feature categories, review Process configuration, Map workflow states to metastates.

    Here's a checklist of updates to make:

    Feature supported Section Edits to make
    Planning Tools RequirementBacklog Verify or update the state-to-metastate mappings for each WIT in the Requirement Category:
    • Map the start of each workflow state 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"
    • Make sure that you have only one State mapped to type="Complete"
    For example:
       <States>
          <State value="New" type="Proposed" />
          <State value="Active" type="InProgress" />
          <State value="Resolved" type="InProgress" />
          <State value="Closed" type="Complete" />
       </States>
    Planning Tools TaskBacklog Verify or update the state-to-metastate mappings for each WIT in the Task Category:
    • Map the start of each workflow state 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"
    • Make sure that you have only one State mapped to type="Complete"
    Planning Tools BugWorkItems

    Verify or update the state-to-metastate mappings for each WIT in the Bug Category:

    • Map the start of each workflow state 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"
    • Make sure that you have only one State mapped to type="Complete"
    Portfolio Backlogs PortfolioBacklogs Add PortfolioBacklogs section and verify the following:
    • Each intermediate portfolio backlog specifies the next level portfolio backlog as its parent
    • The top portfolio backlog doesn't specify a parent portfolio backlog
    For example:
    <PortfolioBacklog category="Microsoft.FeatureCategory" pluralName="Features" singularName="Feature" parent="Microsoft.EpicCategory" workItemCountLimit="1000">
    . . .
    </PortfolioBacklog>
    Planning Tools WorkItemColors Add primary and secondary HEX colors for each WIT defined for the project. For example: <WorkItemColor primary="FF009CCC" secondary="FFD6ECF2" name="User Story" />
    <WorkItemColor primary="FF773B93" secondary="FFEEE2F2" name="Feature" />
    <WorkItemColor primary="FFFF7B00" secondary="FFFFD7B5" name="Epic" />
    Planning Tools and Feedback TypeFields

    Make sure that the fields specified for each TypeField map to those in use for the WITs defined for the Requirement Category, Task Category, and Bug Category.1 For example:

    <TypeField refname="System.AreaPath" type="Team" />
    <TypeField refname="Microsoft.VSTS.Scheduling.RemainingWork" type="RemainingWork" format="{0} h" />
    <TypeField refname="Microsoft.VSTS.Common.StackRank" type="Order" />
    Portfolio Backlogs and Bug Behavior Properties Add the Properties section. For example:
    <Properties>
       <Property name="BugsBehavior" value="AsTasks" />
       <Property name="HiddenBacklogs" value="Microsoft.EpicCategory" />
    </Properties>

    1 Don't modify the TypeFieldValues for the Microsoft.VSTS.Feedback.ApplicationType.

  3. Import your ProcessConfiguration file.
    witadmin importprocessconfig /collection:CollectionURL /p:ProjectName /f:FileName

Tip

See also ProcessConfiguration XML element reference.

Migrate existing test plans and suites

Migrate existing test plans and suites to work item based test plans and suites.

  1. Open a Command Prompt window on the TFS application-tier server. For example:
    cd %programfiles%\TFS 14.0\Tools

  2. Run the TfsConfig TCM command. TFSConfig TCM /upgradeTestPlans /CollectionName:CollectionName /TeamProject:TeamProjectName

    For example:

    TFSConfig TCM /upgradeTestPlans /CollectionName:"Fabrikam Fiber Collection" /TeamProject:"Fabrikam Fiber"

  3. Respond to the questions that appear.

    Logging sent to file C:\ProgramData\Microsoft\Team Foundation\Server Configuration\Logs\TPC_UPG_AT_0515_143821.log
Microsoft (R) TfsConfig - Team Foundation Server Configuration Tool
Copyright (c) Microsoft Corporation. All rights reserved.

Command: tcm
Microsoft (R) TfsConfig - Team Foundation Server Configuration Tool
Copyright (c) Microsoft Corporation. All rights reserved.

In order to upgrade the test plans, you have to complete the following steps:
1. Import the test plan work item definition into the project. Have you complete
d this step? (Yes/No) Yes
2. Import the test plan category into the project. Have you completed this step?
(Yes/No) Yes

Test plan migration job successfully scheduled.

  4. If you're migrating a large quantity of test plans and test suites, you can run the following command to monitor the progress of data migration.

    TFSConfig TCM /upgradeStatus /collectionName:CollectionName /TeamProject:TeamProjectName

After a successful data migration, all test management data should be available for use. For more information about this utility, go here.

Review and verify access to new features

After you update your project manually, you have access to the latest features. However, you still might want to make some additional configurations or customizations to support your work tracking needs.

See Additional configuration options for information on how to verify or activate each feature.

You can learn more about the objects used to track work and support Agile tools from these topics:

If you need to rename a WIT, use witadmin renamewitd command to change the name, and then update the Categories definition file. See Add or modify a work item type.