The Microsoft Project Field Mapping File
The Microsoft Project field mapping file defines field mappings between Team Foundation fields and Microsoft Project fields. Unlike Microsoft Excel, Microsoft Project uses a limited set of fields that includes predefined fields such as Task Name and custom fields. When a user publishes or refreshes work item data in a Microsoft Project file, the field map is used to determine which fields in the work item database match the fields in Microsoft Project.
The field mapping file is specified on a per-team project basis. To retrieve the field mapping file, you must download it from a team project. After you make changes, you upload it to the team project and the changes apply to all users of that team project. For more information about how to download or upload the Microsoft Project field mapping file, see How to: Download or Upload a Microsoft Project Field Mapping File.
Field Mappings
To specify a mapping between a work item field and a project column, use the Mapping element.
Use the following XML syntax to specify a mapping between a work item type field and a Microsoft Project field. The Mapping element is used to specify a field mapping.
<Mapping WorkItemTrackingFieldReferenceName=""
ProjectField=""
ProjectName=""
ProjectUnits=""
PublishOnly=""/>
Mapping Attributes
The following table describes the attributes that can be used with the Mapping element.
Attribute |
Description |
|---|---|
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. |
The following example shows how to map the work item type field that contains the title to the task name Microsoft Project field:
<Mapping WorkItemTrackingFieldReferenceName="System.Title"
ProjectField="pjTaskName"/>
The following XML syntax shows a more complex example of how to map the work item type field that has the start date to the start date Microsoft Project field. Because the field is calculated, it is specified to publish and not refresh in order to prevent errors from being introduced by Team Explorer updates.
<Mapping WorkItemTrackingFieldReferenceName="Microsoft.VSTS.Scheduling.StartDate" ProjectField="pjTaskStart" PublishOnly="true"/>
Note
As a best practice, you should map calculated fields in Microsoft Project to read-only fields in Team Foundation. This helps avoid confusion so that team members do not try to change calculated fields.
Context Field
The context field is a work item type field that displays information about a task's hierarchical relationship to summary tasks. The context field is displayed in Team Explorer so that users who are not using Microsoft Project can still see what summary tasks a subtask belongs to.
When a task is a subtask, the context field will contain the text name of the task, and the text name of its summary task. For example, if the task "Develop Test Plan" is a subtask of "Planning Tasks," the context field would read "Planning Tasks > Develop Test Plan." If a task has more than 1 summary task above it, all the summary tasks are listed in the context field up to the maximum character limit.
Use the following XML syntax to specify which work item type field is the context field. The ContextField element is used to specify a context field. The WorkItemTrackingFieldReferenceName attribute must be set to a valid reference name of an existing work item type field.
<ContextField WorkItemTrackingFieldReferenceName="" />
The following example shows how to specify Microsoft.VSTS.Scheduling.TaskHierarchy as the context field.
<ContextField WorkItemTrackingFieldReferenceName="Microsoft.VSTS.Scheduling.TaskHierarchy" />
Links and Attachments Field
The links and attachments field is a read-only field that indicates if there are links and attachments for a task. The field displays Yes or No depending on if there are links and attachments. The field is displayed as a column with the title Links & Attachments when you use the Team System Task Sheet view.
Use the following XML syntax to specify which Microsoft Project field should display links and attachments information. The LinksField element is used to specify a link field. The ProjectField attribute must be set to a valid Microsoft Project field. Specifying a link field in the Microsoft Project field mapping file is optional.
<LinksField ProjectField="" />
The following example shows how to specify pjTaskText26 as the links and attachments field:
<LinksField ProjectField="pjTaskText26" />
Synchronization Field
The synchronization field lets you control the publish and refresh behavior of each task. The field is displayed as a column with the title Publish and Refresh when you use the Team System Task Sheet view. For more information about how to use the synchronization field in Microsoft Project, see How to: Enable or Disable Publishing of Work Items in Microsoft Project.
You must specify a synchronization field in the Microsoft Project field mapping file. Use the following XML syntax to specify which field is the synchronization field. The SyncField element is used to specify a synchronization field. The ProjectField attribute must be set to a valid Microsoft Project field.
<SyncField ProjectField="" />
The following example shows how to specify pjTaskText25 as the synchronization field:
<SyncField ProjectField="pjTaskText25" />