Update a project based on a MSF v4.2 process template

TFS 2017 | TFS 2015 | TFS 2013

If you have upgraded from Visual Studio Team System 2008 Team Foundation Server to TFS 2013, you can update your project manually. If your project was based on a MSF version 4.2 process template, follow the procedures in this topic. After you apply these updates, you'll be able to access the new features described in Configure features after an upgrade as well as interface with Microsoft Test Manager.

These procedures will only support access to new features available with TFS 2012 and later versions. Additional work is required to add new queries or the latest reports, update customized reports, or access dashboards. For more information, see Additional information about changes made when upgrading TFS.

Update tasks required to access new features:

1. Rename system fields
2. (Agile only) Rename Scenario to User Story
3. Download the latest version of MSF process template
4. Import link types
5. (Optional) Apply as needed customizations
6. Import work item types
7. Import the category file
8. Import the process configuration files
9. Verify access to new features

Additional tasks required to interface with Microsoft Test Manager:

1. Specify the bug type to be created in Microsoft Test Manager
2. Grant permissions to test team members
3. Launch Microsoft Test Manager

Requirements

• To download a process template, you must be a member of the Project Collection Administrators group. If the required security permissions are set explicitly, your Manage process template permission for the project collection must be set to Allow.
• To run the witadmin and tcm command-line tools, you must be a member of one of the following groups: Team Foundation Administrators, Project Collection Administrators, or Project Administrators for the project.
• To grant permissions, you must be a member of the administrative group at the level of the group that you want to change. For example, if you want to change permissions for a group or user at the project collection level, you must be a member of the Project Collection Administrators group for that collection, or your Edit Collection-Level Information permission must be set to Allow.

For more information, see Add administrators, set permissions at the project-level or project collection-level.

1. Rename system fields

Because the friendly names of several system fields were renamed in Visual Studio Team Foundation Server 2010, you need to manually rename these fields in your project collection. System fields that were renamed include System.AreaID, System.IterationID, System.HyperLinkCount, System.ExternalLinkCount, and System.AttachedFileCount.

Perform this task for each project collection defined on the application-tier server you've upgraded.

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

1. Type each of the following commands, substituting your data for the arguments that are shown, and then choose the ENTER key.

   witadmin changefield /collection:CollectionURL /n:System.AreaId /name:"Area Id"  
   witadmin changefield /collection:CollectionURL /n:System.AttachedFileCount /name:"Attached File Count"  
   witadmin changefield /collection:CollectionURL /n:System.ExternalLinkCount /name:"External Link Count"  
   witadmin changefield /collection:CollectionURL /n:System.HyperLinkCount /name:"Hyperlink Count"  
   witadmin changefield /collection:CollectionURL /n:System.RelatedLinkCount /name:"Related Link Count"  
   

   Use this format for CollectionURL: http://ServerName:Port/VirtualDirectoryName/CollectionName, for example: http://srvalm:8080/tfs/DefaultCollection.

2. (Agile only) Rename the Scenario work item type

To minimize the amount of customizations you need to make, and to comply with future updates to the Agile process template, you should rename the Scenario work item type to User Story.

Perform this task for each project that you want to update.

• Type the following command, substituting your data for the arguments that are shown, and then choose the ENTER key.

  witadmin renamewitd /collection:CollectionURL /p:projectName /n:Scenario /new:"User Story"  
  

  Tip

  Enclose a parameter in quotes when it contains spaces. For example, specify /p:"My Project X" when your project name contains spaces.

  Back to top

3. Download the latest version of MSF process template

• See Download the latest process template.

  Tip

  To get access to the latest versions of the default process templates, install the latest update for TFS. TFS 2012.1 provided significant updates that were made to the workflow for several work item types. These changes support backward transitions so that when you inadvertently drag a work item on the Kanban board or the task board to a resolved or closed state, you can drag it back to an earlier workflow state.

  You can obtain the upgrade for TFS 2012 from the Microsoft download site: Quarterly Update for Microsoft Visual Studio Team Foundation Server 2012.

4. Import link types

Import the link types, SharedSteps and TestedBy, located in the LinkTypes folder in the process template that you downloaded in task 3.

Perform this task for each project collection defined on your upgraded application-tier server.

• Type the following two commands, substituting your data for the arguments that are shown, and then choose the ENTER key.

  witadmin importlinktype /collection:CollectionURL /f:"DirectoryPath\TestedBy.xml"  
  witadmin importlinktype /collection:CollectionURL /f:"DirectoryPath\SharedStep.xml"  
  

  For DirectoryPath, specify the location of the LinkTypes folder for the process template that you downloaded. The directory path should follow this structure: Drive:\MSFTemplateFolder\WorkItem Tracking\LinkTypes.

5. (Optional) Apply customizations to the latest versions of work item types

If you have customized any of the following work item types, you should update the latest version of these types with your customizations. The following tables summarize the fields removed and added in the latest versions of each process template.

Agile work item types

CMMI work item types

The types of customizations you might apply include field additions, additions or changes to pick lists, or additions to workflow reasons. Do not change the workflow states as these are used in process configuration and the Agile planning tools. If you must change the workflow, change it after you have finished the update and follow the guidance about state category mappings described in Process configuration.

If you use other work item types defined in the process template, and want to update them to the latest versions, then apply any customizations you have made for them as well. Also, if you have defined a custom work item type that you use to track test cases, you should apply customizations from that type to the Test Case work item type provided with the latest process template.

To learn more about working with the artifacts that these process templates provide, see Agile process or CMMI process.

6. Import work item types

Import the following work item types based on the process template you are working with.

• Agile: Bug, Task, User Story, Test Case, Shared Steps, Code Review Request, Code Review Response, Feedback Request, Feedback Response

• CMMI: Bug, Task, Requirement, Test Case, Shared Steps, Code Review Request, Code Review Response, Feedback Request, Feedback Response

  Perform this task for each project that you want to update.

• Type the following command for each work item type that you need to import, substituting your data for the arguments that are shown, and then choose the ENTER key.

  witadmin importwitd /collection:CollectionURL /p:projectName /f:"DirectoryPath\WITName"  
  

  Tip

  Specify the name of the xml file and not the friendly name of the work item type. For example, specify CodeReviewRequest.xml for the Code Review Request work item type.

  For DirectoryPath, specify the directory location of the TypeDefinitions folder for the process template that you downloaded. The directory path should follow this structure: Drive:MSFTemplateFolder WorkItem TrackingTypeDefinitions.

• (Optional) Verify the work item types are accessible by opening Team Explorer or the web portal. You might have to refresh the cache to see the changes.

7. Import the categories file

Import the category file located in the WorkItem Tracking folder of the process template that you downloaded. Categories support intelligent grouping of work item types. To learn more, see Use categories to group work item types.

• In the Command Prompt window, type the following command, substituting your data for the arguments that are shown, and then choose the ENTER key.

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

  For DirectoryPath, specify the path to the WorkItem Tracking folder for the process template that you downloaded. The directory path should follow this structure: Drive:\MSFTemplateFolder\WorkItem Tracking.

8. Import the process configuration file

The process configuration file determines the layout and features available through the backlog and board pages of the web portal. To use these pages, you must import the process configuration file.

• Import the definition file for process configuration.
  witadmin importprocessconfig /collection:CollectionURL /p:" ProjectName" /f:"DirectoryPath\ProcessConfiguration.xml"
  For DirectoryPath, specify the path to the Process folder for the process template that you downloaded. The directory path should follow this structure: Drive:<em>TemplateFolder\WorkItem Tracking\Process.
  

9. Verify access to new features

Open a web portal and determine if all features are available to you.

Additional tasks to interface with Microsoft Test Manager

Perform the following tasks to complete the updates required to interface with Test Manager.

1. Specify the bug type to be created in Microsoft Test Manager

To support the automatic creation of a work item to track code defects or bugs that are found when a test team member uses Test Manager, you must specify the bug type to be used for your existing project. The tcm bugfieldmapping command supports the import and export of a mapping file to the project. The mapping file defines the type of work item to create and the three data fields to be filled by Test Manager. The three fields are reproducible steps, system information, and the build in which the defect was found. When a tester runs a test and finds a defect, they can create a bug in which the three fields are automatically filled.

1. Open Notepad or a text editor, and copy the following code into the file:

   <?xml version="1.0" encoding="utf-16"?>
   <BugFilerMappings workitemtypetocreate="Bug">  
         <ReproSteps>Microsoft.VSTS.TCM.ReproSteps</ReproSteps>  
         <SystemInformation>Microsoft.VSTS.TCM.SystemInfo</SystemInformation>  
         <BuildFoundIn>Microsoft.VSTS.Build.FoundIn</BuildFoundIn>  
   </BugFilerMappings>  
   

   Note

   If the work item type that you use to create code defects is labeled something other than "Bug," replace "Bug" in the previous example with the name of that work item type.

2. Save the file, and label it bugfieldmappings.xml.

3. In the Command Prompt window, type the following command, substituting your data for the arguments that are shown, and then choose the ENTER key.

   tcm bugfieldmapping /import /mappingfile:"DirectoryPath\bugfieldmappings.xml" /collection:CollectionURL /teamproject:projectName  
   

   For DirectoryPath, specify the folder where you saved the bugfieldmappings.xml file.

   For more information, see tcm: Customize and manage the test experience.

2. Grant permissions to test team members

You must grant permissions to team members who will manage test environments and test configurations, create and view test runs, and perform other tasks.

The following table describes the permissions that control access to test functions and support interfacing with the project for testing. It also indicates the default assignments that are made in version 5.0 of the Agile and CMMI process templates, in addition to the recommended permissions to grant manual testers and test leads.

Permission	Description	Scope	Readers	Contributors	Builders	Recommended for manual testers	Recommended for test leads
View project-level information	Can view membership of project-level groups and the permissions of those members.	Project-level
View test runs	Can view test plans in this node.	Project-level
Create test runs	Can add and remove test results and add or modify test runs for the project.	Project-level
Manage test configurations	Can create and delete test configurations for the project.	Project-level
Manage test environments	Can create and delete test environments for the project.	Project-level
Delete test runs	Can delete a scheduled test for the project.	Project-level
View this node	Can view the security settings for an area node.	Area node
Manage test plans	Can create and edit test plans that are assigned to an area node. If test plans have not been run, you can also delete them.	Area node
Manage test controllers	Can register and unregister test controllers for the project collection.	Project collection

You can grant permissions by following the procedures that are indicated for the specific scope area:

• You can set project-level permissions or area node permissions from the administration page of web portal. See Permissions reference and Customize your area or iteration paths.

• You can set project collection permissions from Team Explorer by choosing Team, Team Project Collection Settings, Security, by opening and using the administration console for Team Foundation, or by using the TFSSecurity and tf command-line tools. For more information, see Add an administrator.

3. Launch Microsoft Test Manager

After you have completed the upgrade tasks that are described earlier in this topic, you can start Microsoft Test Manager, connect to your project, and start to plan your test efforts.

Additional information about changes made when upgrading TFS

When you upgrade from Visual Studio Team System 2008 Team Foundation Server to TFS 2012, you receive updates made to both TFS 2010 and TFS 2012. There were a number of architectural changes made with the release of TFS 2011. To learn more about the changes made by upgrading to the latest version of TFS from Visual Studio Team System 2008 Team Foundation Server, see the following resources:

• Team Foundation Server 2010 Key Concepts (blog post)
• Update a customized process template to access new features
• Locating reports after the upgrade to TFS 2010
• Changes and Additions to the Schema for the Analysis Services Cube
• Changes made to process templates

Related articles

• witAdmin: Customize and manage objects for tracking work
• Configure features after an upgrade