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 2013, 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.
Important
You only have to follow the procedures in this topic if you are upgrading a team project that you created with a process template provided with Visual Studio Team System 2008 Team Foundation Server, or one that does not contain the work item types Test Cases and Shared Steps.
These procedures will only support access to new features available with Team Foundation Server 2012. 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:
Rename system fields
(Agile only) Rename Scenario to User Story
Download the latest version of MSF process template
Import link types
(Optional) Apply as needed customizations
Import work item types
Import the category file
Import the process configuration files
Verify access to new features
Additional tasks required to interface with Microsoft Test Manager:
Specify the bug type to be created in Microsoft Test Manager
Grant permissions to test team members
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 Permission reference for Team Foundation Server.
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.
Open a Command Prompt window where either Visual Studio 2012 or Team Explorer 2012 is installed and type:
cd %programfiles%\Microsoft Visual Studio 12.0\Common7\IDEOn a 64-bit edition of Windows, replace %programfiles% with %programfiles(x86)%.
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.
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.
Note
Of course, renaming the Scenario work item type will require you to update existing reports and queries that reference the Scenario work item type. However, because of the schema changes made to data warehouse with the upgrade to Team Foundation Server 2010, the pre-existing or pre-upgrade reports need to be rewritten to work with the new schema. See Locating Reports After the Upgrade to Team Foundation Server 2010.
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.
Tip
To get access to the latest versions of the default process templates, install the latest quarterly update for Team Foundation Server. Significant updates were made to the workflow for several work item types in the latest quarterly update. 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 from the Microsoft download site: Quarterly Update for Microsoft Visual Studio Team Foundation Server 2012.
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
Work item type |
Removed fields |
Added fields |
|---|---|---|
Bug |
|
|
Task |
|
|
User Story (previously named Scenario) |
|
CMMI work item types
Work item type |
Removed fields |
Added fields |
|---|---|---|
Bug |
|
|
Task |
|
|
Requirement |
|
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: Configure and customize Agile planning tools for a team project.
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:
MSF for Agile software development for Visual Studio ALM (v6.0)
MSF for CMMI process improvement 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 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.
Back to top
8. Import the process configuration file
The process configuration file determines 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 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:\TemplateFolder\WorkItem Tracking\Process.
Back to top
9. Verify access to new features
Perform the tasks provided in New features enabled for Team Web Access.
Note
You will not have to perform the additional steps to update the workflow for Agile team projects as described here: Update the workflow for agile team projects. By following the procedures in this topic, you will have applied these changes already.
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.
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.
Save the file, and label it bugfieldmappings.xml.
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:projectNameFor DirectoryPath, specify the folder where you saved the bugfieldmappings.xml file.
For more information, see Customize and manage the test experience [tcm and 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 |
.png "check mark"){kind=icon} |
|
|
|
|
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 Add and modify area and 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 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