Customize the field mapping between TFS and Project Server

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.

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

Customizing the Field Mappings Between Team Foundation Server and Project Server

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

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.

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.

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

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

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