Customize the field mapping between TFS and Project Server

  • Article

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 (TFS) 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 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.

Note

The mappings for the integration of TFS and Project Server are distinct from the mapping file for Microsoft Project. For more information, see Customize 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

Note

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.

Requirements

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 Assign permissions to support TFS-Project Server integration.

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 Synchronization process overview for TFS-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 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 as Required Changes to Make When Mapping to a Team Project That Was Created From the Scrum Process Template describes later in this topic.

For more information about mappings and the synchronization process, see Field mapping XML element reference for TFS-Project Server integration.

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

Required changes to make when mapping to a team project that was created from the Scrum process template

There are two changes you must make to enable data flow from a team project created from a Microsoft Visual Studio Scrum process template. You must add the Completed Work and Original Estimate fields to the Task work item type, and you must remove the elements that require the Remaining Work field to be empty when a team member changes the state to Done or Removed.

To update the Scrum task type definition

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

    cd %programfiles(x86)%\Microsoft Visual Studio 12.0\Common7\IDE

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

  2. To export the type definition for Task, type the following command, substituting your data for the arguments that are shown here, where CollectionURL specifies the URL of a team project collection, ProjectName specifies the name of a team project defined within the collection, and "DirectoryPath\FileName.xml" specifies the name and location for the file to export. Then choose Enter.

    witadmin exportwitd /collection: /p:"ProjectName" /n:"Task" /f:"DirectoryPath\FileName.xml"

  3. In a text editor or in Visual Studio, open the file you exported.

  4. Within the FIELDS definition section, add this code snippet before the element for Remaining Work:

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

  5. Within the <WORKFLOW> section, remove the following code snippet from both <STATE value="Done"> and <STATE value="Removed"> definitions:

    <FIELD refname="Microsoft.VSTS.Scheduling.RemainingWork">
   <EMPTY />
</FIELD>

  6. Within the <FORM> section, 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" />

  7. Save and close the file.

  8. Import the file, substituting your data for the arguments that are shown.

    witadmin importwitd /collection: /p:"ProjectName" /f:"DirectoryPath\FileName.xml"

  9. Refresh your team project or work items page to verify the changes.

For more information, see Export and import work item types [redirected], Modify or add a field to support queries, reports, and workflow, and Design and customize a work item form [redirected].

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 Work item field reference for Visual Studio ALM and Modify or add a field to support queries, reports, and workflow.

  • 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 in TFS-Project Server integration.

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

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 Work 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 in TFS-Project Server integration.

  • 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 in TFS-Project Server integration.

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 Team Foundation Server 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 Field mapping XML element reference for TFS-Project Server integration.

To download the mappings to a file

  1. To run the TfsAdmin command-line tool, open a Command Prompt window where either Visual Studio or Team Explorer is installed and enter:

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

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

  2. Type the following command, and then choose 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:

    DownloadingMappingFileto Team Project CollectiontpcUrl.

    You have successfully downloaded field mapping fileMappingFileto Team Project CollectiontpcUrl.

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 TFS-Project Server integration.

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 the command prompt, type the following command, and then choose 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 toCollectionUri.

    You have successfully uploaded field mappings to collectionCollectionUri.

To upload the mappings from a file

  1. At the command prompt, type the following command, and then choose 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:

    UploadingMappingFileto Team Project CollectiontpcUrl.

    You have successfully uploaded field mapping fileMappingFileto Team Project CollectiontpcUrl.

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 TFS to support data synchronization.

See Also

Tasks

ConfigureTFS-Project Server integration

Concepts

Specify the work item types to synchronize

Administrate the integration of Team Foundation Server and Project Server