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.

In TeamPulse, from the ribbon, go to Project > TFS Sync Information .
If the TeamPulse project is not already connected to a TFS project, connect it now.
- For more information about this step, see the section entitled Choosing a TFS Project to Synchronize With.
Expand the TFS Server Configuration section and choose Edit Synchronization Mappings .
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.
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.

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

/>

Custom field types table:

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