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 linkenlarge screenshot

     

  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 screenenlarge screenshot

 

Synchronization Mappings XML Overview

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

 

  • SyncConfiguration
    • Root node for all settings.
    • Do not modify any attributes in this element (except for the SyncAttachments attribute).
    • Elements
      • ConfigSettings
      • ValueMappings
      • EntityMappings
  • ConfigSettings
    • Do not modify the attributes for ConfigSetting elements with the following keys: TfsProjectName, TfsServerVersion, TfsProcessTemplateName.
    • To turn off TFS impersonation for this project in the sync service, add the following ConfigSetting:

     
    <ConfigSetting Key=”UseTfsImpersonation” Value=”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.
    • Attributes
      • None
    • Elements
      • ConfigSetting
  • ConfigSetting
    • Attributes
      • Key – the name/key of the config setting.
      • Value – the value of the config setting.
    • Elements
      • None
  • ValueMappings
    • Attributes
      • None
    • Elements
      • ValueMapping
  • ValueMapping
    • Used to map a value in TeamPulse to a different value in TFS.
    • One common value mapping is to map a user display name in TeamPulse to a user display name in TFS.
    • Attributes
      • Name – the name of the value mapping.  The name will be used to refer to this value mapping from FieldMapping elements.
    • Elements
      • Value
  • Value
    • Attributes
      • TeamPulseValue – value in TeamPulse.
      • DestinationValue – value in the destination system (i.e. TFS).
    • Elements
      • None
  • EntityMappings
    • Attributes
      • None
    • Elements
      • EntityMapping
  • EntityMapping
    • Used to specify a mapping between a TeamPulse entity and a TFS entity (work item type).
    • Attributes
      • TeamPulseEntityName – the name of the TeamPulse entity (Story, Bug, Issue, Risk or Task).
      • DestinationEntityName – the name of the entity in the destination system (i.e. TFS work item type name).
    • Elements
      • FieldMappings
      • DefaultValues
  • FieldMappings
    • Contains all the field mappings for an entity mapping.
    • Attributes
      • None
    • Elements
      • FieldMapping
  • 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.
    • Elements
      • None
    • Special Field Mappings
      • Acceptance criteria
        • 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
    • 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.
    • Attributes
      • None
    • Elements
      • DefaultValue
  • DefaultValue
    • 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.
    • Elements
      • None

 

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 diffucult to parse and split into unique items for use in TeamPulse.

 

Story

Field Name Display Name Type Direction Notes
Name Name string Both
Description 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
Points Estimate double Both
Complexity Complexity string Both
Maturity Maturity string Both
Certainty Certainty string Both
PriorityID Priority integer Both
PriorityClassification Priority Class. string Both
ValueClassification 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
Description 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.