How Assigned To Is Synced

In most cases syncing the Assigned To field between TeamPulse and TFS will "just work".  However, this field has some special behaviors that are important to be aware of.  This section will explain these behaviors and also show how to use a value mapping when the automatic behaviors don't achieve the desired result.

Important Notes

• When syncing, the value you see in the Assigned To drop-down in both TeamPulse and TFS is what gets synced between the two systems (unless you use a value mapping).
• By default, TFS will restrict the allowed values for Assigned To to a specific list of user names.
• TeamPulse allows any value to be entered in the Assigned To field but the drop-down list will only contain a list of the members of the TeamPulse project.
• User display name formats:
  • TeamPulse always displays users using the format '{First Name} {Last Name}' (i.e. first name space last name).
  • The format of users in TFS should be the same as the user's display name in Active Directory (or if the user account is local to a machine, it uses the display name of the windows account).

Syncing Assigned To values from TeamPulse to TFS

When syncing an Assigned To value from TeamPulse to TFS, TeamPulse will pass to TFS the value displayed in the TeamPulse drop-down and this value will be in the format '{First Name} {Last Name}'.  In most cases, TFS requires that the value being passed be an exact match to one of the user names displayed in its own Assigned To drop-down list.  If an exact match is not found, a sync error can occur.

Because user names in TFS are formatted according to Active Directory/Windows rules, it is possible that the user 'John Doe' in TeamPulse appears as 'Doe, John' in TFS.  To handle this common formatting mismatch, if a match is not found for a user in the standard '{First Name} {Last Name}' format, the sync system will also check for a user with the format '{Last Name}, {First Name}'.  If this results in a match, then syncing will proceed with the re-formatted name.

If a matching user in TFS cannot be found and a sync error occurs, there are generally two courses of action:

1. Change the value in TeamPulse to a value that does match a valid TFS user.
2. Use a value mapping to map the value TeamPulse is using for the user display name to the value TFS is using for the display name.  This technique is explained below.

Syncing Assigned To values from TFS to TeamPulse

When syncing an Assigned To value from TFS to TeamPulse, TFS will pass to TeamPulse the value displayed in the TFS drop-down and the format of the value will be determined by Active Directory/Windows.  TeamPulse allows any value to be entered in the Assigned To field, however, many application features (i.e. My Perspective and user specific reports) require an assignment to actual TeamPulse user in order to function properly.

If the value from TFS does not match an existing TeamPulse user in the standard '{First Name} {Last Name}' format, the sync system will check if the value from TFS matches a TeamPulse user in the '{Last Name}, {First Name}' format.  If a match is found then the item will be synced and assigned correctly to the matched TeamPulse user.

If a matching user in TeamPulse cannot be found, there are generally two courses of action:

1. Change the value in TFS to a value that does match an existing TeamPulse user.
2. Use a value mapping to map the value TeamPulse is using for the user display name to the value TFS is using for the display name.  This technique is explained below.

Using a value mapping with the Assigned To field

In some cases the sync system will not be able to automatically determine the value to use for the Assigned To field in TeamPulse or TFS.  Examples of where this may occur is when TeamPulse and TFS use completely different formats for the display names of users or when a user exists in one system but not in the other.  In these cases it may be possible to use a value mapping to correct the synchronization errors.

To add a value mapping for the Assigned To field:

1. Open your project in TeamPulse and navigate to the Edit Synchronization Mappings screen (for more information, see the section entitled Editing the Synchronization Mappings).
2. In the <ValueMappings> element, add a new value mapping similar to the following (if no <ValueMappings> element exists, add one within the <SyncConfiguration> element:
    
   
   <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>
   
   
3. Reference the new mapping in any applicable <FieldMapping> element:
    
   
   <FieldMapping TeamPulseFieldName="AssignedTo" TeamPulseFieldType="string" DestinationFieldName="System.AssignedTo" DestinationFieldDisplayName="Assigned To" DestinationFieldType="string" ValueMappingName="AssignedToMapping" />
   
   
4. Save the changes to the synchronization mappings XML by clicking the Save button.