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:

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

  1. 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\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.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

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

  • Issue (Microsoft.VSTS.Common.Issue)

  • Rank (Microsoft.VSTS.Common.Rank), replaced with Stack Rank

  • Test Name (Microsoft.VSTS.Test.TestName)

  • Test Id (Microsoft.VSTS.Test.TestId)

  • Test Path (Microsoft.VSTS.Test.TestPath)

  • Triage (Microsoft.VSTS.Common.Triage)

Task

  • Baseline Work (Microsoft.VSTS.Scheduling.BaselineWork), replaced with Original Estimate

  • Discipline (Microsoft.VSTS.Common.Discipline), replaced with Activity

  • Exit Criteria (Microsoft.VSTS.Common.ExitCriteria)

  • Issue (Microsoft.VSTS.Common.Issue)

  • Rank (Microsoft.VSTS.Common.Rank), replaced with Stack Rank

  • Task Hierarchy (Microsoft.VSTS.Scheduling.TaskHierarchy)

User Story (previously named Scenario)

  • Exit Criteria (Microsoft.VSTS.Common.ExitCriteria)

  • Issue (Microsoft.VSTS.Common.Issue)

  • Rough Order of Magnitude (Microsoft.VSTS.Common.RoughOrderOfMagnitude), replaced with Story Points

CMMI work item types

Work item type

Removed fields

Added fields

Bug

  • Baseline Work (Microsoft.VSTS.Scheduling.BaselineWork), replaced with Original Estimate

  • Estimate (Microsoft.VSTS.CMMI.Estimate)

  • Issue (Microsoft.VSTS.Common.Issue)

  • Rank (Microsoft.VSTS.Common.Rank), replaced with Stack Rank

  • Steps to Reproduce (Microsoft.VSTS.CMMI.StepsToReproduce), replaced with Repro Steps

  • Test Name (Microsoft.VSTS.Test.TestName)

  • Test Id (Microsoft.VSTS.Test.TestId)

  • Test Path (Microsoft.VSTS.Test.TestPath)

Task

  • Baseline Work (Microsoft.VSTS.Scheduling.BaselineWork), replaced with Original Estimate

  • Estimate (Microsoft.VSTS.CMMI.Estimate)

  • Exit Criteria (Microsoft.VSTS.Common.ExitCriteria)

  • Issue (Microsoft.VSTS.Common.Issue)

  • Rank (Microsoft.VSTS.Common.Rank), replaced with Stack Rank

  • Task Hierarchy (Microsoft.VSTS.Scheduling.TaskHierarchy)

  • Test Name (Microsoft.VSTS.Test.TestName)

  • Test Id (Microsoft.VSTS.Test.TestId)

  • Test Path (Microsoft.VSTS.Test.TestPath)

Requirement

  • Baseline Work (Microsoft.VSTS.Scheduling.BaselineWork), replaced with Original Estimate

  • Completed Work (Microsoft.VSTS.Scheduling.CompletedWork)

  • Estimate (Microsoft.VSTS.CMMI.Estimate), replaced with Scheduling Size

  • Exit Criteria (Microsoft.VSTS.Common.ExitCriteria)

  • Issue (Microsoft.VSTS.Common.Issue)

  • Rank (Microsoft.VSTS.Common.Rank), replaced with Stack Rank

  • Remaining Work (Microsoft.VSTS.Scheduling.RemainingWork)

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:

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.

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

check mark check mark check mark check mark check mark

View test runs

Can view test plans in this node.

Project-level

check mark check mark check mark check mark check mark

Create test runs

Can add and remove test results and add or modify test runs for the team project.

Project-level

check mark check mark check mark check mark

Manage test configurations

Can create and delete test configurations for the team project.

Project-level

check mark check mark

check mark

Manage test environments

Can create and delete test environments for the team project.

Project-level

check mark check mark

check mark

Delete test runs

Can delete a scheduled test for the team project.

Project-level

check mark check mark

check mark

View this node

Can view the security settings for an area node.

Area node

check mark check mark check mark

check mark

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

check mark check mark check mark check mark

Manage test controllers

Can register and unregister test controllers for the team project collection.

Project collection

check mark

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:

See Also

Concepts

Configure features after a TFS upgrade

Other Resources

witAdmin: Customize and manage objects for tracking work