Upload or download the Microsoft Project Mapping file

TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013

Use TFSFieldMapping to upload and download the Microsoft Project mapping file. This file controls how Microsoft Project publishes tasks to a project that connects to an on-premises Team Foundation Server (TFS). For example, you can modify the file to support fields you added to work item types or modify the way in which existing fields are published and refreshed.

You can specify which work tracking fields map to Project fields. You can also control publishing behavior through the PublishOnly attribute, and designate special fields such as the context field. For the complete XML syntax of the mapping file, see Customize the Microsoft Project field mapping file. This file is the same file that was defined in the process template that was used to create the project. See Map Microsoft Project fields

The TFSFieldMapping command-line tool works for only on-premises deployments. To run the tool, open a Command Prompt window where Team Foundation Server is installed.

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

Requirements

To use the TFSFieldMapping command, you must be a member of the Team Foundation Administrators or the Project Collection Administrators security group. For more information, see Add administrators, set permissions at the project-level or project collection-level.

Syntax

TFSFieldMapping upload | download /collection:CollectionURL /teamproject:ProjectName /mappingfile:MappingFile   

Parameters

To change how work item fields are mapped to Project

1. Open a Command Prompt window where you have installed TFS and change the directory to point to the tools. For example:

   cd %programfiles(x86)%\Common Files\microsoft shared\Team Foundation Server\16.0 
   

   Tip

   Project isn't required to download the mapping file, however, it is required to upload it.

2. Download the mapping file by entering the following command:

   TFSFieldMapping download /collection:CollectionURL /teamproject:ProjectName /mappingfile:MappingFile  
   

   Tip

   If a name contains spaces, enclose the name in quotes.

3. Open the mapping file in a text editor or XML editor.

4. Add new mappings or edit existing mappings in the following format:

   <Mapping WorkItemTrackingFieldReferenceName="System.Id"   
      ProjectField=""  
      ProjectName=""  
      ProjectUnits=""  
      PublishOnly=""  
      IfSummaryRefreshOnly=""/>    
   

   For example, to add additional scheduling fields to a project created using the Scrum process template, add the following mappings:

   <Mapping WorkItemTrackingFieldReferenceName="Microsoft.VSTS.Scheduling.StartDate" ProjectField="pjTaskStart" PublishOnly="true" />  
   <Mapping WorkItemTrackingFieldReferenceName="Microsoft.VSTS.Scheduling.FinishDate" ProjectField="pjTaskFinish" PublishOnly="true" />  
   <Mapping WorkItemTrackingFieldReferenceName="Microsoft.VSTS.Scheduling.OriginalEstimate" ProjectField="pjTaskBaselineWork" ProjectUnits="pjHour" IfSummaryRefreshOnly="true" />  
   <Mapping WorkItemTrackingFieldReferenceName="Microsoft.VSTS.Scheduling.CompletedWork" ProjectField="pjTaskActualWork" ProjectUnits="pjHour" IfSummaryRefreshOnly="true" />    
   

   The default Scrum template only maps the Remaining Work field to Project.

   Note

   For a full list of all Project field values for the ProjectField attribute, see Field mappings in Microsoft Project.

5. (Optional) Indicate if the field is to be published but not refreshed. Add the PublishOnly attribute to the mapping section for that field and set the attribute to true. This attribute can be used to allow for team members to see a field value but not be able to change it in Team Foundation.

6. (Optional) Indicate how summary tasks are to be refreshed in Project. Add fSummaryRefreshOnly="true" attribute to indicate that the field is never published to the work item database but is refreshed from the work item database when the row for the field is a summary task in Project, the summary task has Publish and Refresh=Yes, and the summary task contains at least one child task that is published to work tracking.

7. Save and upload the file:

   TFSFieldMapping upload /collection:CollectionURL /teamproject:ProjectName /mappingfile:MappingFile  
   

Related articles

• Customize the Microsoft Project field mapping file
• Field mappings in Microsoft Project