Customize the field mapping between TFS and Project Server

TFS 2015 | TFS 2013

To synchronize data between an enterprise project plan and a 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 project collection that hosts projects that you want to synchronize with Project Server. You must define the field mappings for each 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

Requirements

To complete the procedures in this topic, you must have the Administer Project Server integration permission set to Allow. In addition, the TFS service account must be granted the Administer Project Server integration. For more information, see Assign permissions.

Default mappings

The mappings determine which fields get synchronized when a user updates information in TFS 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 TFS. You use the targetToTfs element to specify the field in Project Server that updates the field in TFS.

• For status synchronization, the data in TFS 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.

  The following table lists the default set of fields that are mapped between TFS 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 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 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 reference.

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

There are two changes you must make to enable data flow from a project created from a Scrum process 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 project collection, ProjectName specifies the name of a 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:CollectionURL /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:CollectionURL  /p:"ProjectName" /f:"DirectoryPath\FileName.xml"  
   

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

   For more information, see Export and import work item types, Modify a field or add a custom field, and Design and customize a work item form.

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 TFS field. If you want to synchronize a field in Project Server with a field that you must create in TFS, first create the field in each type of work item that you are synchronizing. For more information, see Index of work item fields and Modify a field or add a custom field.

• The name of the field in Project Server that will update the TFS field. For a list of available fields, see Restrictions on mapping fields.

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

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

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

• The Title field is the only field that you can send both to TFS 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.

• 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 Restrictions on mapping fields, Data Types and Field Mapping Criteria.

• You can map fields that are associated with pick lists in TFS. 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 fields.

Example: mapping the team name to appear in Project

In the following example, the custom string field in TFS, 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.

Example: displaying the area and iteration paths in Project

You can map the Area (System.AreaPath) and Iteration (System.IterationPath) fields in TFS 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 project collection where the 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.

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

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

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

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

   Replace tpcUrl with the URL of the 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.

Customize the Project Server tab

When you associate an enterprise project plan with a 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 that support data synchronization.

Related articles

Specify work item types
Configure TFS-Project Server integration
Administer TFS-Project Server integration