Bagikan melalui

Customizing the Field Mapping Between Project Server and Team Foundation Server

  • Artikel

To synchronize data between an enterprise project plan and a team project, you must associate the work-item fields in Visual Studio Team Foundation Server 2010 with the fields in Microsoft Project Server 2007 or Project Server 2010. 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 Access or Project Web App (PWA). You can upload the default mappings, or you can customize a mapping file and upload it. To upload the default mappings, see Upload Mappings later in this topic.

Warning

The mappings for the integration of Team Foundation Server and Project Server are distinct from the mapping file for Microsoft Project. For more information, see The Microsoft Project Field Mapping File.

As the following illustration shows, you customize the mappings in five steps:

Customizing the Field Mappings Between Team Foundation Server and Project Server

Workflow for Customizing PS-TFS Field Mapping

Important

You can update the mapping file as often as you want. The fields that appear on the Project Server tab are updated for each type of work item that participates in data synchronization. You must not manually change the definitions for the Project Server tab. For more information, see Customize the Project Server Tab later in this topic.

In this topic

  • Default Mappings

  • Determine Additional Fields to Map

  • Download Mappings to a File

  • Update Mappings

  • Upload Mappings

  • (Optional) Customize the Project Server Tab

Note

For a demonstration video, see the following page on the Microsoft website: Managing Field Mappings for Integration of Team Foundation Server and Project Server.

Required Permissions

To complete the procedures in this topic, you must have the Administer Project Server integration permission set to Allow. In addition, the service account for Team Foundation Server must be granted the Administer Project Server integration. For more information, see Assigning Permissions to Support Integration of Project Server and Team Foundation Server.

Default Mappings

The mappings determine which fields get synchronized when a user updates information in Team Foundation or Project Server. Each of the following synchronization types has its own set of mappings:

  • For publish synchronization, the data in Project Server updates the data in Team Foundation. You use the targetToTfs element to specify the field in Project Server that updates the field in Team Foundation.

  • For status synchronization, the data in Team Foundation is submitted to the status queue in Project Server. You use the tfsToTarget element to specify the field that updates the status queue field in Project Server.

For more information about these two types of synchronization, see Overview of the Synchronization Process for Team Foundation Server and Project Server Integration.

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 three project templates for Microsoft Solutions Framework (MSF). 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 v5.0 or Capability Maturity Model Integration (CMMI) Process Improvement v5.0. If you are mapping to a team project that was created from the Scrum 1.0 process template, you will need to make some modifications as Modifying Field Mappings When Mapping to a Team Project That Was Created Using the Scrum 1.0 Process Template describes later in this topic.

For more information about mappings and the synchronization process, see Field Mapping XML Element Reference for Integration of Team Foundation Server and Project Server.

Team Foundation field

Project Server field

Status Queue field

Work item types in Agile 5.0

Work item types in CMMI 5.0

Work item types in Scrum 1.0

Title

Task Name

Title

All

All

All except for Sprint

Assigned To

Resources

Resources

All

All

All except for Sprint

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

Sprint

Finish Date

Task Finish

Resource Finish

Task and User Story

Task and Requirement

Sprint

Back to top

Adding Fields to Types of Work Items When Mapping to a Team Project That Was Created From the Scrum 1.0 Process Template

Because the Scrum 1.0 process template does not use the Completed Work and Original Estimate fields, you must add these fields to the types of work items that you want to participate in data synchronization. For example, you can add the unused fields to the task type of work item.

To add these fields, you must export the task type of work item from the team project, and then, for each field, add a FIELD element in the FIELDS section. You can also add a Control element in the FORM section. You can add the following FIELD elements:

<FIELD name="Completed Work" refname="Microsoft.VSTS.Scheduling.CompletedWork" type="Double" reportable="measure" formula="sum">
   <HELPTEXT>The number of units of work that have been spent on this task</HELPTEXT>
</FIELD>
<FIELD name="Original Estimate" refname="Microsoft.VSTS.Scheduling.OriginalEstimate" type="Double" reportable="measure" formula="sum">
   <HELPTEXT>Initial value for Remaining Work - set once, when work begins. </HELPTEXT>
</FIELD>

You can also add the following Control elements:

<Control FieldName="Microsoft.VSTS.Scheduling.OriginalEstimate" Type="FieldControl" Label="Original Estimate:" LabelPosition="Left" />
<Control FieldName="Microsoft.VSTS.Scheduling.CompletedWork" Type="FieldControl" Label="Completed:" LabelPosition="Left" />

For more information, see Export and Import Work Item Types from an Existing Project, Defining Work Item Fields, and Designing and Customizing a Work Item Form.

Back to top

Determine Additional Fields to Map

Determine the following information for each field that you want to synchronize in addition to the default fields:

  • The reference name of the field in Team Foundation. If you want to synchronize a field in Project Server with a field that you must create in Team Foundation, first create the field in each type of work item that you are synchronizing. For more information, see Using System Fields and Fields Defined by the MSF Process Templates and Defining Work Item Fields.

  • The name of the field in Project Server that will update the field in Team Foundation. For a list of available fields, see Restrictions on Mapping Project Server Fields for Integration with Team Foundation Server.

  • The name of the field in to be updated in Project Server and the name of the field in Project Server that will update the mirror field in Team Foundation Server will update.

  • Whether to display the fields on the work item form. You set the value of the displayTfsField attribute to true for fields that you want to appear on the work-item form. You set the value of the displayTfsMirror attribute to true for work-item form.

  • Whether to resolve data conflicts by allowing the value of the field in Team Foundation to overwrite the value of the field in Project Server or to maintain both values. This decision determines the value of the onConflict attribute. When onConflict=”PsWins” is set, the value of the field in Project Server overwrites the value of the field in Team Foundation. For more information, see Field Elements and Attributes.

  • Additional values that you must define to support pick lists or custom lookup tables in Project Server.

Back to top

Restrictions on Data That You Can Map

After you determine which fields you want to map, note the following restrictions:

  • You can send only task-level information, pjTask* fields, from Project Server to Team Foundation Server.

  • You can send only resource-level information, pjResource* fields, from Team Foundation Server to the status queue of Project Server.

  • The Title field is the only field that you can send both to Team Foundation Server and to the status queue.

  • Rollup is automatically calculated for the Assigned To, Completed Work, and Remaining Work fields. You cannot map additional fields and have rollup calculated for them. For more information, see Working with Resource Rollup in Enterprise Projects Mapped to Team Projects.

  • You must make sure that the data types or units of each field that you map conform to the field mapping criteria for standard and custom enterprise fields. For more information, see “Data Types and Field Mapping Criteria” in Restrictions on Mapping Project Server Fields for Integration with Team Foundation Server.

  • You can map fields that are associated with pick lists in Team Foundation. However, you must create lookup tables in Project Server to match the pick lists. You cannot automatically synchronize pick lists and lookup tables.

For more information, see Restrictions on Mapping Project Server Fields for Integration with Team Foundation Server.

Back to top

Example: Mapping the Team Name to Appear in Project

In the following example, the custom string field in Team Foundation, MyCompany.MyOrg.DevTeamName, is mapped to an enterprise custom text field in Project Server, My Company Team Name. You can use this example to display in Project Professional the name of the team that is associated with a task.

<field tfsName="MyCompany.MyOrg.DevTeamName" tfsMirrorName="Mirror.MyCompany.MyOrg.DevTeamName" displayTfsField="false" displayTfsMirror="false" onConflict="DoNothing">
   <tfsToTarget>
   <target provider="ProjectServerStatusQueue" name=" My Company Team Name" />
   </tfsToTarget>
   <targetToTfs>
      <target provider="ProjectServerPublished" name=" My Company Team Name" />
   </targetToTfs>
</field>

Neither field appears on the work item form. Also, if the values do not match, each field retains its own value.

Back to top

Example: Displaying the Area and Iteration Paths in Project

You can map the Area (System.AreaPath) and Iteration (System.IterationPath) fields in Team Foundation so that they appear in your project plans. Because these tree path fields change frequently, you should map them as text fields in Project. Project managers who use these fields must manually enter the full area path or iteration path.

Important

The current implementation of Visual Studio Team Foundation Server 2010 and Project Server integration does not support automatic synchronization of allowed value lists, pick lists, global lists, or tree path lists that are defined for mapped fields between the two server products. For the best experience, you must make manual entries in the project plan that match those in Team Foundation. If you specify an entry that is not valid, a validation dialog box will appear when you publish the plan.

To add the Area and Iteration fields to a project plan, perform the following actions:

  1. Add two customer enterprise fields to Project Server, and label them as Area (TFS) and Iteration (TFS).

    For more information, see the following page on the Microsoft website: Creating Lookup Tables and Enterprise Custom Fields.

  2. Export the field mappings from the team project collection where the team projects are defined.

    For more information, see Download Mappings to a File later in this topic.

  3. Add the following code to the file:

    <field tfsName="System.AreaPath" tfsMirrorName="Mirror.System.AreaPath" displayTfsField="true" displayTfsMirror="true">
        <tfsToTarget>
          <target provider="ProjectServerStatusQueue" name="Area (TFS)" />
        </tfsToTarget>
        <targetToTfs>
          <target provider="ProjectServerPublished" name="Area (TFS)" />
        </targetToTfs>
      </field>
      <field tfsName="System.IterationPath" tfsMirrorName="Mirror.System.IterationPath" displayTfsField="true" displayTfsMirror="true">
        <tfsToTarget>
          <target provider="ProjectServerStatusQueue" name="Iteration (TFS)" />
        </tfsToTarget>
        <targetToTfs>
          <target provider="ProjectServerPublished" name="Iteration (TFS)" />
        </targetToTfs>
      </field>

  4. Import the updated field mappings file as Upload Mappings describes later in this topic.

  5. Synchronize your project plan with Project Server.

  6. Add the two new columns for the new fields, Area (TFS) and Iteration (TFS), to your project plan

Changes made to the Area and Iteration fields in Team Foundation will be synchronized with these fields in your project plan. Also, you can update these fields in Project and publish your changes to Team Foundation if you specify values that have been defined in Team Foundation.

Back to top

Download the Mappings to a File

Note

You can download mappings only from a team project collection to which they have been uploaded. If you want to download the default mappings to a file, you must first upload the default mappings, as described in To upload the default mappings later in this topic. As an alternative, you can copy the contents of the default mappings. For more information, see Default Field Mappings.

To download the mappings to a file

  1. On a computer that is running Team Explorer and Service Pack 1 for Visual Studio Team Foundation Server 2010, open a Command Prompt window, and change to the directory that contains the TfsAdmin command-line tool.

    By default, the tool is located in Drive:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE. For 64-bit machines, the tool is in Drive:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE.

  2. At a command prompt, type the following command, and then press ENTER.

    TfsAdmin ProjectServer /DownloadFieldMappings /collection:tpcUrl /filePath:MappingFile

    Replace tpcUrl with the uniform resource locator (URL) of the team project collection, and replace MappingFile with the path and name of the file that you will customize.

  3. Wait until the following messages appear:

    Downloading MappingFile to Team Project Collection tpcUrl.

    You have successfully downloaded field mapping file MappingFile to Team Project Collection tpcUrl.

Back to top

Update the Mappings

For each field that you want to add to the mapping file, you specify the field element and its subelements and attributes. For more information, see Field Mapping XML Element Reference for Integration of Team Foundation Server and Project Server.

Back to top

Upload the Mappings

You upload mappings by using the UploadFieldMappings command. You can upload the default mappings by using the /usedefaultfieldmapping option. Otherwise, you must specify a file that contains the mapping elements.

To upload the default mappings

  1. At a command prompt, type the following command, and then press ENTER.

    TfsAdmin ProjectServer /UploadFieldMappings /collection:tpcUrl /usedefaultfieldmappings

    Replace tpcUrl with the URL of the team project collection.

  2. Wait until the following messages appear:

    Uploading default field mappings to CollectionUri.

    You have successfully uploaded field mappings to collection CollectionUri.

To upload the mappings from a file

  1. At the command prompt, type the following command, and then press ENTER.

    TfsAdmin ProjectServer /UploadFieldMappings /collection:tpcUrl /filePath:MappingFile /force

    Replace tpcUrl with the URL of the team project collection, and replace MappingFile with the path and name of your custom mapping file. Specify /force if you are updating the existing mappings.

  2. Wait until the following messages appear:

    Uploading MappingFile to Team Project Collection tpcUrl.

    You have successfully uploaded field mapping file MappingFile to Team Project Collection tpcUrl.

Back to top

Customize the Project Server Tab

When you associate an enterprise project plan with a team project, the Project Server tab is added to the work item form, as the following illustration shows. The tab is added to only those types of work items that you specify to participate in data synchronization. You customize this tab by setting the displayTfsField or displayTfsMirror attributes to true for those fields that you want to have appear on the form.

Project Server tab

Project Server Tab default fields

Important

The field mappings that are defined for the team project collection determine the fields that appear on the Project Server tab. After this tab has been added to a work item type for a team project, you can update it by modifying the field mappings for the collection. If you manually customize the work item form by adding fields to the Project Server tab or changing its location on the form, the tab may not get automatically updated with future changes that you make to the field mappings. If this condition occurs, you can modify the tab manually. For more information, see XML Elements Added to the Definition for the Work Item Type.

For more information about each default field that appears on the Project Server tab, see Project Server Fields Added to Support Data Synchronization.

Back to top

See Also

Tasks

Configuring the Integration of Team Foundation Server and Project Server

Concepts

Specifying the Work Item Types That Can Be Synchronized

Administering the Integration of Team Foundation Server and Project Server

Change History

Date

History

Reason

June 2011

Added links to a demonstration video from Channel 9 and a topic about how to manually update the definition of a work item type.

Information enhancement.