Editing the Synchronization Mappings

The synchronization mappings define which TeamPulse entities are mapped to which TFS entities (work item types) as well as which fields within those that are mapped together.  These mappings can be edited from the Synchronization Mappings Settings screen.

Before modifying the synchronization mappings, it is recommended that you backup your current settings.

  1. In TeamPulse, from the ribbon, go to Project > TFS Sync Information .
  2. If the TeamPulse project is not already connected to a TFS project, connect it now. 
  3. Expand the TFS Server Configuration section and choose Edit Synchronization Mappings .

     

    Edit synchronization mappings link

     

  4. Use the textbox containing XML to modify the synchronization mappings.
    • An alternative approach would be to copy and paste the XML into an XML editor (such as Visual Studio).  When finished, paste the XML back into the textbox.
    • See the section below for an overview of the important XML elements.

      Do not modify any attributes in the <SyncConfiguration> element (except for the SyncAttachments attribute) or the <ConfigSetting> elements.

  5. When finished, click the Save button to save your settings to the database.
    • If there are any validation errors, they will be displayed to the right of the textbox.
    Edit sync mappings screen

Synchronization Mappings XML Overview

The following is an overview of the important elements in the synchronization mapping XML.

SyncConfiguration

SyncConfiguration is the root node for all settings. It contains three elements: ConfigSettings, ValueMappings and EntityMappings.

IMPORTANT: Do not modify any attributes in this element (except for the SyncAttachments attribute)

ConfigSettings

ConfigSettings is the element where the main settings for the sync like TFS project name, TFS version and TFS template are set.

You can turn off TFS impersonation for this project in the sync service by setting the value of ConfigSetting with Key "UseTfsImpersonation" to False. With this config setting present, the sync service will always use the service account credentials when performing actions in TFS instead of trying to perform actions on behalf of the user who performed the action in TeamPulse.

IMPORTANT: Do not modify the attributes for ConfigSetting elements with the following keys: TfsProjectName, TfsServerVersion, TfsProcessTemplateName.

< ConfigSettings >
  < ConfigSetting Key = "TfsProjectName" Value = "10-Telerik-TeamPulse" />
  < ConfigSetting Key = "TfsServerVersion" Value = "2010" />
  < ConfigSetting Key = "TfsProcessTemplateName" Value = "Agile" />
  < ConfigSetting Key = "TfsQuery" Value = "Team Queries\Sync\Sync query" />
  < ConfigSetting Key = "UseTfsImpersonation" Value = "True" />
</ ConfigSettings >

EntityMappings

EntityMappings is used to specify a mapping between a TeamPulse entity and a TFS entity (work item type).

For every TeamPulse type  (Story, Bug, Issue, Risk or Task) that you want to map to TFS work item type you need to define EntityMapping element. TeamPulseEntityName is the name of the type and the DestinationEntityName is the TFS work item type name.

EntityMapping has two section:

  • FieldMappings - contains the mappings of every field that will be sync.
  • DefaultValues - contains all the default values to be applied when creating new items in TFS.
< EntityMappings >
  < EntityMapping TeamPulseEntityName = "Story" DestinationEntityName = "User Story" >
    < FieldMappings >
      < FieldMapping TeamPulseFieldName = "Name" TeamPulseFieldType = "string" DestinationFieldName = "System.Title" DestinationFieldDisplayName = "Title" DestinationFieldType = "string" />
      < FieldMapping TeamPulseFieldName = "Estimate" TeamPulseFieldType = "single" DestinationFieldName = "Microsoft.VSTS.Scheduling.StoryPoints" DestinationFieldDisplayName = "Story Points" DestinationFieldType = "double" />
    </ FieldMappings >
    < DefaultValues >
      < DefaultValue FieldName = "System.Title" Value = "New User Story" />
      < DefaultValue FieldName = "System.AssignedTo" />
    </ DefaultValues >
  </ EntityMapping >
</ EntityMappings >
FieldMappings
  • FieldMappings contains all the field mappings for an entity mapping.
  • FieldMapping Attributes:
    • TeamPulseFieldName – the name of a field in an entity from TeamPulse.
    • TeamPulseFieldType – the type of the field (int, single, double, string, etc.).
    • DestinationFieldName – the name of a field in an entity from the destination system (i.e. TFS field reference name such as System.Title).
    • DestinationFieldType – the type of the field (int, double, string, html , etc.).
    • DestinationFieldDisplayName – the display name of the field.  This value will be used in the TeamPulse client when displaying conflicts.
    • ValueMappingName – the name of a value mapping to use when synchronizing this field.
  • Special Field Mappings
    • Acceptance criteria may be synchronized from TeamPulse to TFS.
    • Note that this is only a one-way synchronization from TeamPulse to TFS and any changes made to acceptance criteria in TeamPulse will overwrite the data in the field it's mapped to in TFS.
      An example for mapping acceptance criteria to a TFS Scrum template project is as follows:
      < FieldMapping TeamPulseFieldName = "AcceptanceCriteria" TeamPulseFieldType = "string" DestinationFieldName = "Microsoft.VSTS.Common.AcceptanceCriteria" DestinationFieldDisplayName = "Acceptance Criteria" DestinationFieldType = " html " />
DefaultValues
  • DefaultValues contains all the default values to be applied when creating new items in the destination system (i.e. TFS).
  • During synchronization, when a new work item is created in TFS, a "stub" item is created first and then the values from TeamPulse are applied to it. The purpose of the default values specified here is to provide values to use to satisfy all required fields so that the "stub" work item can be saved in TFS.
  • Default values are not applied to TeamPulse entities.
  • The DefaultValue Element have two attributes:
    • FieldName – the name of a field in an entity from the destination system (i.e. TFS field reference name such as System.Title).
    • Value – value to set for the field.

ValueMappings

ValueMappings allows you to map different values of the fields in TeamPulse and TFS during the synchronization.

Every mapping is define in it's own ValueMapping element and the Name attribute is the name of  from FieldMapping elements

One common value mapping is to map a user display name in TeamPulse to a user display name in TFS.

< ValueMappings >
  < ValueMapping Name = "AssignedToMapping" >
    < Values >
      < Value TeamPulseValue = "TeamPulse User 1" DestinationValue = "TFS User 1" />
      < Value TeamPulseValue = "TeamPulse User 2" DestinationValue = "TFS User 2" />
      < Value TeamPulseValue = "TeamPulse User 3" DestinationValue = "TFS User 3" />
    </ Values >
  </ ValueMapping >
</ ValueMappings >

Fields available for synchronization

This section lists all the fields in TeamPulse that can be synced with TFS and includes some notes about some fields that have special cases.

Fields whose direction is TP to TFS will only sync one way, from TeamPulse to TFS, except in two scenarios:
1) If the TeamPulse field value has not been set, the TFS value will be pulled into TeamPulse.
2) If the field mapping is for acceptance criteria , it will always be a one-way sync and the TFS acceptance criteria value will never be brought into TeamPulse.  The reason for this is because in TeamPulse acceptance criteria items are stored individually but in TFS it's just one single field that is very difficult to parse and split into unique items for use in TeamPulse.

Feature

Field Name Display Name Type Direction Notes
Name Name string Both
DescriptionPlainText Description string TP to TFS Use this field to sync a text-only version of the description to TFS.   It cannot be mapped at the same time as DescriptionRichText below.
DescriptionRichText Description richtext Both Use this field to sync a version of the description that includes formatting to TFS.  This field must be mapped to a field of type " html " in TFS.  Also, it cannot be mapped at the same time as Description above.
AssignedTo Assigned To string Both
Status Status string Both
AreaPath Area string Both
IterationPath Iteration string Both
Estimate Estimate double Both
BacklogPriority Backlog Priority double Both
AssignedToTeamID Team integer Both This field is usually used with a value mapping that maps TeamPulse Team IDs to some value in TFS.

Story

Field Name Display Name Type Direction Notes
Name Name string Both
DescriptionPlainText Description string TP to TFS Use this field to sync a text-only version of the description to TFS.   It cannot be mapped at the same time as DescriptionRichText below.
DescriptionRichText Description richtext Both Use this field to sync a version of the description that includes formatting to TFS.  This field must be mapped to a field of type " html " in TFS.  Also, it cannot be mapped at the same time as Description above.
AssignedTo Assigned To string Both
Status Status string Both
AreaPath Area string Both
IterationPath Iteration string Both
Estimate Estimate double Both
Complexity Complexity string Both
Maturity Maturity string Both
Certainty Certainty string Both
Priority Priority integer Both
PriorityClass Priority Class. string Both
ValueClass Value Class. string Both
BacklogPriority Backlog Priority double Both
AcceptanceCriteria Acceptance Criteria string TP to TFS Use this field mapping to indicate that you want to sync acceptance criteria to a TFS field. When syncing, all the acceptance criteria will be combined into a single value.
AssignedToTeamID Team integer Both This field is usually used with a value mapping that maps TeamPulse Team IDs to some value in TFS.

 

Task

Field Name Display Name Type Direction Notes
Name Name string Both
DescriptionPlainText Description string Both
AssignedTo Assigned To string Both
Status Status string Both
AreaPath Area string Both Areas on Tasks are not displayed in TeamPulse because the value is inherited from its parent story. The area can however be synced.
IterationPath Iteration string Both Iterations on Tasks are not displayed in TeamPulse because the value is inherited from its parent story. The iteration can however be synced.
ParentID  n/a integer Both This is a special field used for creating a parent workitem-to-task link in TFS.
WorkRemaining Work Remaining single Both
WorkCompleted Work Completed single Both
EstimateOptimistic Optimistic Estimate single Both
EstimateProbable Probable Estimate single Both
EstimatePessimistic Pessimistic Estimate single Both

 

Bug

Field Name Display Name Type Direction Notes
Name Name string Both
AssignedTo Assigned To string Both
Status Status string Both
AreaPath Area string Both
IterationPath Iteration string Both
Severity Severity string Both
Estimate Estimate single Both
Priority Priority single Both
SequenceNumber Sequence # double Both
IsTriaged Triaged boolean Both
IsBlocking Blocking boolean Both
BacklogPriority Backlog Priority double Both
DescriptionPlainText Description string TP to TFS Use this field to sync a text-only version of the description to TFS.  It cannot be mapped at the same time as DescriptionRichText below.
DescriptionRichText Description richtext Both Use this field to sync a version of the description that includes formatting to TFS.  This field must be mapped to a field of type “html” in TFS.  Also, it cannot be mapped at the same time as DescriptionPlainText above.
StepsToReproducePlainText Steps to Reproduce string TP to TFS Use this field to sync a text-only version of the steps to reproduce to TFS. It cannot be mapped at the same time as StepsToReproduceRichText below.
StepsToReproduceRichText Steps to Reproduce richtext Both Use this field to sync a version of the steps to reproduce that includes formatting to TFS.  This field must be mapped to a field of type “html” in TFS.  Also, it cannot be mapped at the same time as StepsToReproducePlainText above.
ResolutionPlainText Resolution string TP to TFS Use this field to sync a text-only version of the resolution to TFS.  It cannot be mapped at the same time as ResolutionRichText below.
ResolutionRichText Resolution richtext Both Use this field to sync a version of the resolution that includes formatting to TFS.  This field must be mapped to a field of type “html” in TFS.  Also, it cannot be mapped at the same time as ResolutionPlainText above.
AcceptanceCriteria Acceptance Criteria string TP to TFS Use this field mapping to indicate that you want to sync acceptance criteria to a TFS field. When syncing, all the acceptance criteria will be combined into a single value.
AssignedToTeamID Team integer Both This field is usually used with a value mapping that maps TeamPulse Team IDs to some value in TFS.

 

Risk

Field Name Display Name Type Direction Notes
Name Name string Both
AssignedTo Assigned To string Both
Status Status string Both
AreaPath Area string Both
IterationPath Iteration string Both
Severity Severity string Both
Estimate Estimate single Both
Priority Priority single Both
Probability Probability string Both
SequenceNumber Sequence # double Both
IsTriaged Assessed boolean Both
IsBlocking Blocking boolean Both
BacklogPriority Backlog Priority double Both
DescriptionPlainText Description string TP to TFS Use this field to sync a text-only version of the description to TFS.  It cannot be mapped at the same time as DescriptionRichText below.
DescriptionRichText Description richtext Both Use this field to sync a version of the description that includes formatting to TFS.  This field must be mapped to a field of type “html” in TFS.  Also, it cannot be mapped at the same time as DescriptionPlainText above.
ResolutionPlainText Resolution string TP to TFS Use this field to sync a text-only version of the resolution to TFS.  It cannot be mapped at the same time as ResolutionRichText below.
ResolutionRichText Resolution richtext Both Use this field to sync a version of the resolution that includes formatting to TFS.  This field must be mapped to a field of type “html” in TFS.  Also, it cannot be mapped at the same time as ResolutionPlainText above.

 

Issue

Field Name Display Name Type Direction Notes
Name Name string Both
AssignedTo Assigned To string Both
Status Status string Both
AreaPath Area string Both
IterationPath Iteration string Both
Severity Severity string Both
Estimate Estimate single Both
Priority Priority single Both
SequenceNumber Sequence # double Both
IsTriaged Assessed boolean Both
IsBlocking Blocking boolean Both
BacklogPriority Backlog Priority double Both
DescriptionPlainText Description string TP to TFS Use this field to sync a text-only version of the description to TFS.  It cannot be mapped at the same time as DescriptionRichText below.
DescriptionRichText Description richtext Both Use this field to sync a version of the description that includes formatting to TFS.  This field must be mapped to a field of type “html” in TFS.  Also, it cannot be mapped at the same time as DescriptionPlainText above.
ResolutionPlainText Resolution string TP to TFS Use this field to sync a text-only version of the resolution to TFS.  It cannot be mapped at the same time as ResolutionRichText below.
ResolutionRichText Resolution richtext Both Use this field to sync a version of the resolution that includes formatting to TFS.  This field must be mapped to a field of type “html” in TFS.  Also, it cannot be mapped at the same time as ResolutionPlainText above.
BenefitPlainText Benefit string TP to TFS Use this field to sync a text-only version of the benefit to TFS.  It cannot be mapped at the same time as BenefitRichText below.
BenefitRichText Benefit richtext Both Use this field to sync a version of the benefit that includes formatting to TFS.  This field must be mapped to a field of type “html” in TFS.  Also, it cannot be mapped at the same time as BenefitPlainText above.

Custom Fields

Custom fields can be synced with tfs too. They should be added in Synchronization Mappings XML the same way other fields are added. TeamPulseFieldName should be the field id of the custom field. TeamPulseFieldType should be the corresponding type in the custom field types table below. You could find this information in the custom field details page via going to Settings -> Work Items -> Manage Custom Fields and open the selected custom field.

Here is a sample of Custom Field Details:

Here is sample of the mapping:

< FieldMapping  TeamPulseFieldName = "tp_ClosedDate_cf"  TeamPulseFieldType = "date"  DestinationFieldName = "Microsoft.VSTS.Common.ClosedDate"  DestinationFieldDisplayName = "Closed Date"  DestinationFieldType = " string />

Custom field types table:

Custom Field Type TeamPulseFieldType  
Text  string
 Multi-line text
 string
 Drop-down list  string
 Number  single
 Checkbox  boolean
 Date  date