Dela via

Field Mapping XML Element Reference for Integration of Team Foundation Server and Project Server

  • Artikel

By customizing the field mappings, you can define which fields in Visual Studio Team Foundation Server 2010 and Project Server should be kept synchronized and which fields are updated in the status queue for Project Server and in Team Foundation.

Note

The field mappings for integration of Team Foundation Server with Project Server are distinct from the mapping file for Microsoft Project. For information about the latter file, see The Microsoft Project Field Mapping File.

You maintain one set of field mappings for each team project collection that hosts team projects that you want to synchronize with Project Server. To retrieve the field mappings, you can download them to a file from the collection. After you modify the file, you can upload it to the collection, and the changes will apply to all team projects that are defined for that collection. For more information about how to download or upload field mappings, see Customizing the Field Mapping Between Project Server and Team Foundation Server.

In this topic

  • Required Fields

  • Default Fields That are Mapped

  • Mapping Elements and Attributes

  • Default Field Mappings

Required Fields

The following fields must be mapped to support data synchronization. If you have customized the fields that are used to schedule work, you must customize the field mappings to reference the fields that you use.

  • System.Title must be mapped to pjTaskName.

  • System.AssignedTo must be mapped to pjResourceNames.

  • The field that you use to track the start of work in Team Foundation must be mapped to pjTaskStart. By default, this field is Microsoft.VSTS.Scheduling.StartDate.

  • The field that you use to track completed work in Team Foundation must be mapped to pjTaskFinish. By default, this field is Microsoft.VSTS.Scheduling.FinishDate.

Back to top

Default Fields That Are Mapped

For each field in Team Foundation, you can specify two mappings. In the first mapping, you specify the field in Project that the field in Team Foundation updates in the status queue. In the second mapping, you specify the field in Project that updates the field in Team Foundation. In addition, you can specify whether the field in Team Foundation appears on the work item form and how updates are made to reference and mirrored fields.

By default, all Project fields that are mapped are also mirrored, which means that their values are stored in Team Foundation.

Important

In most configurations, you should not remove the default field mappings because the synchronization process requires them. For example, do not remove the default mappings if your enterprise project plan maps to a team project that was created from a process template that is based on either the Microsoft Solutions Framework (MSF) for Agile Software Development v5.0 or the Capability Maturity Model Integration (CMMI) Process Improvement v5.0.

However, if your plan maps to a team project that was created using the MSF Scrum 1.0 process template, you may need to remove some of the default mappings. If your project collection contains only team projects that were created using the Scrum template, you may receive an error when you configure the two server products. For best results, add Completed Work (Microsoft.VSTS.Scheduling.CompletedWork) and Original Estimate (Microsoft.VSTS.Scheduling.OriginalEstimate) to the work items that you intend to map. For more information, see Modifying Field Mappings When Mapping to a Team Project That Was Created From the Scrum 1.0 Process Template.

The following table describes the default mappings that are assigned to fields in Team Foundation. You can specify how you want reference and mirror fields to be updated. You can set OnConflict to PSWins to overwrite the value in Team Foundation with the value from Project Server. If you leave the OnConflict attribute unspecified, the fields maintain different values. For more information, review the Field Elements and Attributes table later in this topic.

For more information about mirrored fields and the synchronization process, see Understanding How Updates to Specific Fields Are Managed.

Team Foundation field

Project field

Display field on Project Server tab of work item form (displayTfsField)

Display mirrored field on Project Server tab of work item form (displayTfsMirror)

Field updates (OnConflict)

Title

Task Name

No

No

The value in Project Server replaces the value in Team Foundation.

Assigned To

Resources

No

No

The value in Project Server replaces the value in Team Foundation.

Remaining Work

Resource Remaining Work (Status Queue)

Task Remaining Work (Project Server)

Yes

Yes

Each value is maintained.

Completed Work

Resource Actual Work (Status Queue)

Task Actual Work (Project Server)

Yes

Yes

Each value is maintained.

Original Estimate

Baseline Work

No

Yes

The value in Project Server replaces the value in Team Foundation.

Start Date

Resource Start (Status Queue)

Task Start (Project Server)

No

No

The value in Project Server replaces the value in Team Foundation.

End Date

Resource Finish (Status Queue)

Task Finish (Project Server)

No

No

The value in Project Server replaces the value in Team Foundation.

You can display more Project fields on the Project Server tab of a work item form in Team Foundation if you add them to the field mappings. For more information about this tab, see Project Server Fields Added to Support Data Synchronization.

Back to top

Mapping Elements and Attributes

You use a field element to specify a reference field in Team Foundation to synchronize. All field elements are contained in the mappingFile, persistables, and Microsoft.TeamFoundation.Sync.Mapping.Impls.FieldMapping container elements.

Important

When you map a field from Team Foundation Server to Project Server, make sure that you match the data types of those fields. Otherwise, the following error might appear when you try to upload the field mappings:

Index (zero based) must be greater than or equal to zero and less than the size of the argument list.

For more information, see Data Types and Field Mapping Criteria.

The following example shows the nesting structure of XML elements. To view the default mappings, see Default Mapping File later in this topic.

<mappingFile>
   <persistables>
      <Microsoft.TeamFoundation.Sync.Mapping.Impls.FieldMapping>
         <field tfsName="System.Title" tfsMirrorName="Mirror.System.Title" displayTfsField="false" displayTfsMirror="false" onConflict="PSWin">
            <tfsToTarget>
               <target provider="ProjectServerStatusQueue" name="pjTaskName" />
            </tfsToTarget>
            <targetToTfs>
               <target provider="ProjectServerPublished" name="pjTaskName" />
            </targetToTfs>
         </targetToTfs>
      </field>

         . . .

    </Microsoft.TeamFoundation.Sync.Mapping.Impls.FieldMapping>
  </persistables>
</mappingFile>

Field Element Syntax

The following syntax defines the attributes of the field element:

<field tfsName="FieldName" tfsMirrorName="FieldMirrorName" displayTfsField="true | false" displayTfsMirror=" true | false" onConflict="PSWin">

Target Element Syntax

The following syntax defines the attributes of the target element:

<target provider="ProviderName" name="ProjectFieldName" />

To determine the field name, prefix the concatenated friendly name with "pj". For example, the field name for Status Manager is pjStatusManager, and the field name for Custom 01 is pjCustom01.

Back to top

Field Elements and Attributes

The following table describes the subelements and attributes of the field element. You map a Team Foundation field to a Project resource field whose value you want to update during status synchronization. You map a Team Foundation field to a Project task field whose value will update Team Foundation Server during publish synchronization. Also, the units of fields that you map must conform to established criteria. For more information, see Restrictions on Mapping Project Server Fields for Integration with Team Foundation Server.

Element

Attribute

Description

field

Specifies the field in Team Foundation to be mapped and how the field should be mapped.

tfsName

Specifies the reference name of the field in Team Foundation to synchronize. You must specify a field that is defined in the team project collection. You can list all fields in a collection by running the witadmin listfields command. For more information, see Managing Work Item Fields [witadmin].

tfsMirrorName

Required. Specifies the reference name under which to store the value of the Project Server field in Team Foundation Server. You can prefix the reference name with "Mirror." For example, you can specify Mirror.System.Title for System.Title.

NoteNote
Mirror fields that you specify are created automatically. You do not have to add mirror fields to the type definition of a work item.

displayTfsField

Optional. By default, this attribute is set to true. If this attribute is set to true, the field appears on the Project Server tab of the work item form in Team Foundation. If this attribute is set to false, the field does not appear on the form. By default, only the Completed Work and Remaining Work fields appear on the form.

displayTfsMirror

Optional. By default, this attribute is set to true. If this attribute is set to true, the field appears on the Project Server tab of the work item form in Team Foundation. If this attribute is set to false, the field does not appear on the form.

onConflict

Optional. Specifies how the synchronization engine updates the reference field. The only valid value is PSWin.

When this attribute is set to PSWin, the value of the reference field is updated when the current value that is published from Project Server differs from the value in the mirror.

If you do not define this attribute, you indicate that two sets of books should be maintained. In other words, the value in Project can differ from the value in Team Foundation. By default, the values in Project always replace the values of the Title, Assigned To, Start Date, and End Date fields. By default, only the Completed Work and Remaining Work fields are maintained with two sets of books. For more information, see Updates to Fields that Contain Hours.

tfsToTarget

Specifies the name of the field in Project that Team Foundation will update.

target

Specifies the target to receive updates from Team Foundation.

provider

Specifies the name of the update provider. For tfsToTarget, the only valid value is ProjectServerStatusQueue.

name

Specifies the name of the Project field that will be updated with the value in Team Foundation. You can map only built-in or enterprise custom fields in Project Server. For a list of available fields, see Fields Available for Mapping to the Status Queue.

targetToTfs

Specifies the field mapping to synchronize updates in Project Server with Team Foundation Server.

target

Specifies the target to receive updates from Project Server.

provider

Specifies the name of the update provider. For targetToTfs, the only valid value is ProjectServerPublished.

name

Specifies the name of the field in Project that will update the field in Team Foundation. You can map only built-in or enterprise custom fields. For a list of available fields, see Fields Available for Mapping from Project Server to Team Foundation Only.

Back to top

Default Mappings

The following code lists the default field mappings that are defined when you run the TfsAdmin ProjectServer /UploadFieldMappings command and specify the /useDefaultFieldMappings option. You can download these mappings to a file and then add elements to it or modify the attributes of the listed fields.

For a list of all fields that are added to a type of work item when you add that type to participate in data synchronization, see Project Server Fields Added to Support Data Synchronization.

<mappingFile>
  <persistables>
    <Microsoft.TeamFoundation.Sync.Mapping.Impls.FieldMapping>
      <field tfsName="System.Title" tfsMirrorName="Mirror.System.Title" displayTfsField="false" displayTfsMirror="false" onConflict="PSWin">
        <tfsToTarget>
          <target provider="ProjectServerStatusQueue" name="pjTaskName" />
        </tfsToTarget>
        <targetToTfs>
          <target provider="ProjectServerPublished" name="pjTaskName" />
        </targetToTfs>
      </field>
      <field tfsName="System.AssignedTo" tfsMirrorName="Mirror.System.AssignedTo" displayTfsField="false" displayTfsMirror="false" onConflict="PSWin">
        <tfsToTarget>
          <target provider="ProjectServerStatusQueue" name="pjTaskResourceNames" />
        </tfsToTarget>
        <targetToTfs>
          <target provider="ProjectServerPublished" name="pjTaskResourceNames" />
        </targetToTfs>
      </field>
      <field tfsName="Microsoft.VSTS.Scheduling.CompletedWork" tfsMirrorName="Mirror.Microsoft.VSTS.Scheduling.CompletedWork" displayTfsField="true" displayTfsMirror="true">
        <tfsToTarget>
          <target provider="ProjectServerStatusQueue" name="pjResourceActualWork" />
        </tfsToTarget>
        <targetToTfs>
          <target provider="ProjectServerPublished" name="pjTaskActualWork" />
        </targetToTfs>
      </field>
      <field tfsName="Microsoft.VSTS.Scheduling.RemainingWork" tfsMirrorName="Mirror.Microsoft.VSTS.Scheduling.RemainingWork" displayTfsField="true" displayTfsMirror="true">
        <tfsToTarget>
          <target provider="ProjectServerStatusQueue" name="pjResourceRemainingWork" />
        </tfsToTarget>
        <targetToTfs>
          <target provider="ProjectServerPublished" name="pjTaskRemainingWork" />
        </targetToTfs>
      </field>
      <field tfsName="Microsoft.VSTS.Scheduling.OriginalEstimate" tfsMirrorName="Mirror.Microsoft.VSTS.Scheduling.OriginalEstimate" displayTfsField="false" displayTfsMirror="true" onConflict="PSWin">
        <targetToTfs>
          <target provider="ProjectServerPublished" name="pjTaskBaselineWork" />
        </targetToTfs>
      </field>
      <field tfsName="Microsoft.VSTS.Scheduling.StartDate" tfsMirrorName="Mirror.Microsoft.VSTS.Scheduling.StartDate" displayTfsField="false" displayTfsMirror="false" onConflict="PSWin">
        <tfsToTarget>
          <target provider="ProjectServerStatusQueue" name="pjResourceStart" />
        </tfsToTarget>
        <targetToTfs>
          <target provider="ProjectServerPublished" name="pjTaskStart" />
        </targetToTfs>
      </field>
      <field tfsName="Microsoft.VSTS.Scheduling.FinishDate" tfsMirrorName="Mirror.Microsoft.VSTS.Scheduling.FinishDate" displayTfsField="false" displayTfsMirror="false" onConflict="PSWin">
        <tfsToTarget>
          <target provider="ProjectServerStatusQueue" name="pjResourceFinish" />
        </tfsToTarget>
        <targetToTfs>
          <target provider="ProjectServerPublished" name="pjTaskFinish" />
        </targetToTfs>
      </field>
    </Microsoft.TeamFoundation.Sync.Mapping.Impls.FieldMapping>
  </persistables>
</mappingFile>

Back to top

See Also

Reference

Managing Field Mappings for Integration of Team Foundation Server and Project Server

Concepts

Restrictions on Mapping Project Server Fields for Integration with Team Foundation Server

Project Server Fields Added to Support Data Synchronization

Administering the Integration of Team Foundation Server and Project Server

Other Resources

Customizing the Field Mapping Between Project Server and Team Foundation Server

Change History

Date

History

Reason

April 2011

Removed the Completed Work and Remaining Work fields from the list of required fields that must be mapped. Clarified the mapping of fields in Team Foundation to Project task and resource fields during the status and publishing synchronization stages. Indicated that the tfsMirrorName attribute is required.

Content bug fix.