Update a Team Project Based on an MSF v4.2 Process Template

If you have upgraded from Visual Studio Team System 2008 Team Foundation Server to Team Foundation Server 2012, you can update your team project manually. If your team project was based on a Microsoft Solutions Framework (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 a TFS upgrade as well as interface with Microsoft Test Manager.

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 team 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 team 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 team 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 Team Foundation Server Permissions.

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 team project collection. System fields that were renamed include System.AreaID, System.IterationID, System.HyperLinkCount, System.ExternalLinkCount, and System.AttachedFileCount.

Perform this task for each team project collection defined on your upgraded Team Foundation Server.

1. Open a Command Prompt window where either Visual Studio 2012 or Team Explorer 2012 is installed and type:

   cd %programfiles%\Microsoft Visual Studio 11.0\Common7\IDE
   

   On a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%.

2. 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. System.IterationID /name:"Iteration ID"
   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.

   Back to top

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 team 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 Version of the Process Templates.

Back to top

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 team project collection defined on your upgraded Team Foundation 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.

  Back to top

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 metastate mappings provided here: Customize the Backlog and Board Pages Using 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 the following topics:

• Agile Process Template for Visual Studio ALM (v6.0)

• CMMI Process Template for Visual Studio ALM (v6.0)

Back to top

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 team 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 Tracking\TypeDefinitions.

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

Back to top

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

Back to top

8. Import the process configuration files

The process configuration files determine the layout and features available through the backlog and board pages of Team Web Access. To use these pages, you must import the process configuration files in the sequence indicated

• To import the definition files for process configuration, type the following two commands, one at a time, substituting your data for the arguments that are shown, and then choose the Enter key.

  witadmin importcommonprocessconfig /collection:CollectionURL /p:" ProjectName" /f:"DirectoryPath\CommonConfiguration.xml"
  witadmin importagileprocessconfig /collection:CollectionURL /p:" projectName" /f:"DirectoryPath\AgileConfiguration.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:\MSFTemplateFolder\WorkItem Tracking\Process.

Back to top

9. Verify access to new features

Perform the tasks provided in Learn more about new features.

Back to top

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 team project. The tcm bugfieldmapping command supports the import and export of a mapping file to the team 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 Specify the Bug Type to File By Using Microsoft Test Manager.

Back to top

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 team project for testing. It also indicates the default assignments that are made in version 5.0 of the MSF 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 team project.	Project-level
Manage test configurations	Can create and delete test configurations for the team project.	Project-level
Manage test environments	Can create and delete test environments for the team project.	Project-level
Delete test runs	Can delete a scheduled test for the team 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 team 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 Team Web Access. See Managing Permissions and Create and Modify Areas and Iterations.

• 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 Collection-Level Groups.

For more information, see Change Permissions for a Group or User.

Back to top

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. For more information, see Testing the Application.

Back to top

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 2010. 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)

• Updating an Upgraded Team Project to Access New Features (VS ALM 2010 article)

• Locating Reports After the Upgrade to Team Foundation Server 2010 (VS ALM 2010 article)

• Changes and Additions to the Schema for the Analysis Services Cube (VS ALM 2010 article)

• Changes Made to Team Projects and Default Process Templates During Upgrade of Team Foundation Server (VS ALM 2012 article)

See Also

Concepts

Configure features after a TFS upgrade

Other Resources

witAdmin: Customize and Manage Objects for Tracking Work Items