MS Project Fields Mapping with TFS

TFS works with MS Project via mapping file with specific fields mapped from one application to another. TFS allows us to work with this mapping file in order to customize the behavior of the tasks we are publishing from TFS to MS Project.

In order to modify mapping file, which is XML based file, we need to download this file first then make any required modification and upload it back into the server.

We download and upload xml file with the following lines of code
TFSFieldMapping download TFSServer1 Application MapFile.xml
TFSFieldMapping upload TFSServer1 Application MapFile.xml

We use XML mapping element to map two fields between MS Project and TFS.
<Mapping WorkItemTrackingFieldReferenceName="" ProjectField="" ProjectName="" ProjectUnits="" PublishOnly=""/>

Mapping element posses several important attributed listed in the table below.


WorkItemTrackingFieldReferenceName Required. Specifies the reference name of a work item type field.
ProjectField Required. Specifies the name of a Microsoft Project field. Specify predefined field names by prefixing "pj" to the name, such as pjTaskName for the Task Name column. Specify custom fields as pjTaskText followed by a number, such as pjTaskText11.
ProjectName Optional. Specifies the name to be displayed as the column name to the user. If this attribute is not specified, the work item type field name is used.
ProjectUnits Optional. Specifies the type of units to use when you map a field type to Microsoft Project. Valid values are pjMinute, pjHour, pjDay, pjWeek, and pjMonthUnit.
PublishOnly Optional. If set to true, indicates that the field is published to the work item database, but not refreshed. This value is typically used for calculated fields that should not be updated in Team Explorer. If set to no, indicates that the field is both published and refreshed. The default value when not specified is no.

<Mapping WorkItemTrackingFieldReferenceName="System.Title" ProjectField="pjTaskName"/>

If one of the fields inside MS Project is calculated field, its best to set it to read-only field in TFS so that it is not being modified outside of MS Project file but rather published every time we sync two fields.

Context Field is another type of a work item and it displays information about task’s hierarchical relationship to a summary task. For instance, if the taks name is “Risk Plan” and it is a subtask of “Planning Risks” the Context Field would read “Planning Risks > Risk Plan”

<ContextField WorkItemTrackingFieldReferenceName="" />

Other types of Fields are: Links and Attachments Fields, Synchronization Fields.

In order to ensure that fields are copied correctly from between TFS and MS Project we need to preserve field types. Here is a list of corresponding types between TFS and MS Project.


Work Item Field TypeMicrosoft Project Field Type
Integer Work, units, numbers, and any field type with a range of -2,147,483,648 to 2,147,483,647.
Double Work, units, percentages, fractions, and any field type with a range of ±5.0 x 10-324 to ±1.7 x 10308.
String Text (maximum of 255 characters.)
DateTime Datetime.
TreePath Custom outline codes.
Html Not Supported.
PlainText Not Supported.
History Not Supported.

We can map any field in the MS Project as long as they begin with pjTaks.

Finally, we need to spend a little bit more time on download and upload aspects of fields mapping that was mentioned earlier. In order to download mapping file or upload it back, we need to use TFSFieldMapping utility. Also, you need to be a member of the Project Administrators group or have Edit and View Project Level Info permissions set. In addition, we need to have permission to create mapping file in the local path.

Download command line should be set like that:
TFSFieldMapping download Team_Foundation_Server team_project MappingFile.xml

Upload command line should be set like that:
TFSFieldMapping upload Team_Foundation_Server team_project MappingFile.xml

Featured pages

SharePoint Integration

Windows SharePoint Services is an integral part of Team Foundation Server. As a result, there is v…

Creating Team Project

Team Foundation Server allows creation of the portal project via TFS Portal Creation Wizard. This …

SQL Server Agent Jobs

Team Foundation Server installs several SQL Server Agent Jobs that allow it to perform certain tas…

tf Command

tf Command line utility provide many useful operations that we can perform with Team Foundation Se…

Shelving and Unshelving

Shelving is very powerful feature of the Source Control in VSTS that allows storing pending change…

MS Project Fields Mapping

TFS works with MS Project via mapping file with specific fields mapped from one application to ano…

Using MS Project with Team Foundation Server

MS Projects allows accessing Team Foundation Server and working with the TFS Work Items. This is a…

Managing Documents in TFS

Team Foundation Server provides us with the capability to manage various documents, also called ar…