Hands-On LabManaging Field Mappings for Integration of Team Foundation Server and Project Server

Lab version: 11.0.51106.01 Update 1

Last updated: 3/21/2013

CONTENTS

OVERVIEW................................................................................................................................................. 3

EXERCISE 1: ADDING A LOOKUP TABLE AND TASK CUSTOM FIELD IN PROJECT SERVER.........4

EXERCISE 2: MODIFYING THE DEFAULT FIELD MAPPING..................................................................8

EXERCISE 3: TESTING THE NEW FIELD MAPPING.............................................................................12

Overview

To synchronize data between a team project and a project plan, you must associate the work-item fields in Visual Studio Team Foundation Server with the fields in Microsoft Project Server. You can add fields and specify how they synchronize by customizing the field mappings. You can map both built-in and custom fields in Project. For example, you can share data that does not relate to schedules (such as cost centers, team names, or health status) if you add the fields that store these types of data to the mappings.

You maintain one set of field mappings for each team project collection that hosts team projects that you want to synchronize with Project Server. You must define the field mappings for each team project collection that you have mapped to an instance of Project Web App (PWA). You can upload the default mappings, or you can customize a mapping file and upload it.

Figure 1Customizing the field mappings between Team Foundation Server and Project Server

The following table lists the default set of fields that are mapped between Team Foundation and Project Server. The table also indicates which types of work items use the fields based on the default process templates that TFS provides. You should not modify these mappings if you are mapping to a team project that was created from a process template that is based on Agile Software Development or Capability Maturity Model Integration (CMMI) Process Improvement. If you are mapping to a team project that was created from the Scrum process template, you will need to make some modifications.

Team

Foundation

field

Project Server

field

Status Queue

field

Work item

types in Agile

Work item

types in CMMI

Work item

types in Scrum

Title Task Name Title All All All

Assigned To Resources Resources All All All

Completed Work Task Actual

Work

Resource Actual

Work

Task Task None

Remaining Work Task Remaining

Work

Resource

Remaining Work

Task Task Task

Original

Estimate

Baseline Work Task Bug, Change

Request, Issue,

Requirement,

Risk, and Task

None

Start Date Task Start Resource Start Task and User

Story

Task and

Requirement

None

Finish Date Task Finish Resource Finish Task and User

Story

Task and

Requirement

None

Prerequisites

In order to complete this lab you will need the Team Foundation Server 2012 and Project Server 2013 Integration virtual machine provided by Microsoft. For more information on acquiring and using this virtual machine, please see this blog post.

Exercises

This hands-on lab includes the following exercises:

1. Adding a Lookup Table and Task Custom Field in Project Server

2. Modifying the Default Field Mapping

3. Testing the New Field Mapping

Estimated time to complete this lab: 60 minutes.

Exercise 1: Adding a Lookup Table and Task Custom Field in Project Server

In this exercise, you will learn how to add a new field lookup table and Task custom field using Project Web Access (PWA). We need to do this before we can add in the new field mapping in the next exercise.

1. Log in as Lina Abola (username: linaa). All user passwords are P2ssw0rd.

2. Launch Internet Explorer from the taskbar to load the Home page of the Project Web App (http://tfspsdemo/pwa).

3. On the PWA home page, select the settings button (gear icon), followed by the PWA Settings option.

Figure 2PWA Server Settings

4. From the Enterprise Data section, select the Enterprise Custom Fields and Lookup Tables hyperlink.

Figure 3Navigating to Enterprise Custom Fields and Lookup Tables

5. Scroll down to the Lookup Tables for Custom Fields section and select the New Lookup Table button.

Figure 4Lookup tables for custom fields

6. Enter the following values for the new lookup table.

Field Value

Name State

Type Text

Code Mask Characters | Any | .

Lookup Table (values) Active, Resolved, Closed, Proposed

7. Select the Save button to create the new lookup table.

Figure 5Creating the new “State” lookup table

8. Now we can create a new Task custom field pointing to the lookup table. In the Enterprise Custom Fields section, select the New Field button.

Figure 6Creating a new custom field

9. Enter the following values for the new custom field.

Field Value

Name State

Description Team Foundation Server Work Item State

Entity Task

Custom Attributes Lookup Table -> State

10. Select the Save button to create the new Task custom field.

Figure 7Creating new custom field

Exercise 2: Modifying the Default Field Mapping

Now that the new metadata has been defined in Project Server, you will learn how to modify the default field mapping between Team Foundation Server and Project Server. We will leverage the TfsAdmin command to do so.

1. Log in as Lina Abola (username: linaa). All user passwords are P2ssw0rd.

2. First, we need to download the default mapping to a file so we can modify it. Open a Developer Command Prompt from Start | All Programs | Microsoft Visual Studio 2012 | Visual Studio Tools | Developer Command Prompt for VS2012.

3. Create a temp folder that we can use to download and modify field mappings.

Figure 8

Creating temp folder

4. To download the field mappings, type the following at the command line and press Enter.

Command

TfsAdmin ProjectServer /downloadfieldmappings /collection:http://tfspsdemo:8080/tfs/defaultcollection /filepath:c:\temp\TFSPSmapping.txt

Figure 9Using TfsAdmin command to download field mappings

5. Now we can open the field mapping file to add in the State field that we created in the previous exercise. Open TFSPSmapping.txt with Notepad from c:\temp\TFSPSmapping.txt.

6. Locate and copy (Ctrl+C) the xml node for the Title field.

Figure 10Default field mappings (selected)

7. Insert a space after the Title field node and paste (Ctrl+V) in the copied XML. We will use this pasted XML as a template for adding in mapping for our custom field.

Figure 11Using existing field mapping XML as template for new mapping

8. Modify the values of the copied XML as shown in the following screenshot. The tfsName attribute should be “System.State”, the tfsMirrorName attribute should be “Mirror.System.State”, and the name attribute for both the tfsToTarget and targetToTfs nodes should be State.

Figure 12New field mapping XML

Note: There are two synchronization types that need to be configured, each with its own set of mappings. Publish synchronization (targetToTfs node) is when data in Project Server updates the data in Team Foundation. Status synchronization (tfsToTarget node) is when data in Team Foundation is submitted to the status queue in Project Server.

9. Save the mapping file as TFSPSmappingv2.txt.

Figure 13Saving changes to field mappings

10. The last step is to upload the newly defined field mapping. Type the following at the command line and press Enter.

Command

TfsAdmin ProjectServer /uploadfieldmappings /collection:http://tfspsdemo:8080/tfs/defaultcollection /filepath:c:\temp\TFSPSmappingv2.txt

Figure 14Uploading new field mappings to TFS

Exercise 3: Testing the New Field Mapping

Now that the field mapping has been modified to include State, you will learn how to use the new field.

1. Log in as Lina Abola (username: linaa). All user passwords are P2ssw0rd.

2. Launch Microsoft Project Professional 2013 from the taskbar and login using the http://tfspsdemo profile. This is the tool for project managers to edit enterprise project plans stored in Project Server.

Figure 15Loading a Project profile

3. Open the Human Resources Application enterprise project plan from Project Server by selecting it from the Recent list.

Figure 16Opening project plan

4. To add the newly created task custom field to the current view, scroll to the right on the grid and click on the Add New Column header.

5. Choose the field labeled State (Enterprise).

Figure 17Adding new column for the State field

6. Locate the New Employee Wizard requirement and then change its state to Active.

Figure 18Assigning State to an existing task

7. Set all of the children tasks (of the same requirement) to the Active state, except for the Write Unit Tests task, which you can set as Proposed.

Figure 19Assigning State to existing tasks

8. To save changes to the project plan, select the Check Out button and then select the Save button (or press Ctrl+S).

Figure 20Saving the enterprise project plan

9. Please wait for the project plan save operation to complete successfully before moving on. This step may take a few seconds to complete.

Figure 21Saving the enterprise project plan

10. To publish the enterprise project plan to Project Server, navigate to the File | Info screen and then select the Publish button.

Figure 22Publishing the enterprise project plan

11. Please wait for the publication operation to complete successfully before moving on. This step may take a few seconds to complete.

Figure 23Publishing the enterprise project plan

12. Close Project and select Yes when prompted to check in.

Figure 24Checking in the project plan

13. Log in as Peder Thode (username: pedert). All user passwords are P2ssw0rd.

Note: As you progress through the exercises in this lab, you can switch users rather than log out completely. To do this, select Start, clicking the right arrow to the right of the Log off button, and finally select the Switch user option. You can do this as an alternative to logging out for the remainder of this lab.

14. Launch Visual Studio Ultimate 2012 from the taskbar. This is the tool used daily by the development team.

15. In the Team Explorer window, connect to the “Human Resources” project (if not already connected) and then select the Work Items link.

Figure 25Navigating to Work Items

Note: The Human Resources project is based on the MSF for CMMI Process Improvement v5.0 template.

16. Double-click on the Work Breakdown work item query to open it.

Figure 26Opening the Work Breakdown query

17. In the Work Breakdown query view, note that the New Employee Wizard requirement and its tasks have been updated with the State values assigned using Project. You may need to scroll to the right in order to see the State column.

Figure 27Synchronized State

Note: You may need to wait a couple of minutes for the synchronization engine to finish. Refresh the query window as need until the State fields are updated.

18. In summary, this introduction to field mapping customization helps illustrate how you can configure additional fields to be synchronized between the project managers and the development team. Now that the task metadata is shared between both systems and synchronized, it becomes easier to build reports and dashboards that leverage the new State attribute.

To give feedback please write to VSKitFdbk@Microsoft.com

To learn more about Microsoft Project, please visit http://office.microsoft.com/project/

Copyright © 2023 by Microsoft Corporation. All rights reserved.