Add updates to projects manually
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 |
|
My Work |
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 |
|
Planning Tools |
|
Storyboarding |
|
Portfolio Backlogs |
Note: To add additional portfolio backlogs or further customize your portfolio backlogs, see Add a portfolio backlog level. |
Shared Parameters |
|
Test Plan and Test Suite |
|
Bug Behavior |
|
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.
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.
Open the Process Template Manager from the Team>Team Project Collection Settings menu.
You'll see a list of each process template that has been uploaded to the project collection.
The Upload, Download, Make Default, and Delete buttons are disabled when you don't have the necessary permissions to manage process templates.
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
- Open a Command Prompt window according to the instructions provided in witAdmin: Customize and manage objects for tracking work. For example:
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.
Export the WITs that you have defined for the corresponding category.
witadmin exportwitd /collection:CollectionURL /p:ProjectName /n:TypeName [/f:FileName]
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
, andtype=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
toRemoved
andResolved
toRemoved
; remove rules that populateActivated By
andActivated Date
fields when state=Resolved
- Scrum, Product backlog item: Add transition from
Committed
toRemoved
.
If you've customized the
WORKFLOW
section, make sure to define the required state-to-metastate mappings in the ProcessConfigurationRequirementBacklog
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
, andtype=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
andRemoved
states and transitions fromNew
andRemoved
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
, andtype=RemainingWork
.- All fields that are included in the
BugWorkItems-AddPanel
section of the ProcessConfiguration file. If you've customized theWORKFLOW
, make sure to define the required state-to-metastate mappings in the ProcessConfigurationBugWorkItems
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
, andtype=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 theState=Closed
orState=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 ProcessConfigurationTaskBacklog
section.Feature Category
Update the Feature WIT:
- Add the following fields to the
FIELDS
andFORM
sections: Time Criticality, Effort, and Value Area - Add the ID to the
FORM
section - Add a Transition from
Active
toRemoved
in theWORKFLOW
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.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.
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.
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>
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.
- 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.
- 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"
<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
<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 theMicrosoft.VSTS.Feedback.ApplicationType
. - Map the start of each workflow state to
- Import your ProcessConfiguration file.
witadmin importprocessconfig /collection:CollectionURL /p:ProjectName /f:FileName
Tip
Migrate existing test plans and suites
Migrate existing test plans and suites to work item based test plans and suites.
Open a Command Prompt window on the TFS application-tier server. For example:
cd %programfiles%\TFS 14.0\Tools
Run the
TfsConfig TCM
command.TFSConfig TCM /upgradeTestPlans /CollectionName:CollectionName /TeamProject:TeamProjectName
For example:
TFSConfig TCM /upgradeTestPlans /CollectionName:"Fabrikam Fiber Collection" /TeamProject:"Fabrikam Fiber"
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.
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.
Related articles
You can learn more about the objects used to track work and support Agile tools from these topics:
- Choose a process
- Customize your work tracking experience
- Customize a process template
- Overview of process template files
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.