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