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.
Do not modify any attributes in the
<SyncConfiguration>
element (except for the SyncAttachments attribute) or the
<ConfigSetting>
elements.
The following is an overview of the important elements in the synchronization mapping XML.
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 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.
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:
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.
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:
Editing the Synchronization Mappings
Synchronization Mappings XML Overview
SyncConfiguration
ConfigSettings
<
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
>
<
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
>
DefaultValues
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
"
/>
ValueMappings
<
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
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 |