TFS Integration Tools – How do I define user mappings for version control using the SVN adapter?

On TFS Iteration Automation we have two FAQs that are related to this query, namely #27-1: What is the Lookup Service? and #27-2: What is the Lookup Service? Errata 1.
image

This post is more specific and is focused on the following question we picked up on the MSDN forum: “How I can configure a mapping of SVN users to TFS users.
My SVN users are not in the Active Directory or configured as Windows users.

Two important points to take note of:

  1. Users are not in the Active Directory or configured as Windows users, which means that the DomainMapping feature is not an option.
  2. SVN (Subversion) is a version control solution and therefore we are talking about a version control (VC), not work item tracking (WIT) migration.

The TFS Integration Tools team and author of the Subversion adapter (Thorsten Dralle) have come up with the following solution:

    1: <UserIdentityMappings EnableValidation="false">
    2:       <UserIdentityLookupAddins />
    3:       <DisplayNameMappings DirectionOfMapping="LeftToRight">
    4:         <DisplayNameMapping Left="svnuser1" Right="domain\user1" MappingRule="SimpleReplacement" />
    5:         <DisplayNameMapping Left="svnuser2" Right="domain\user2" MappingRule="SimpleReplacement" />
    6:       </DisplayNameMappings>
    7: </UserIdentityMappings>

Let’s dig into the configuration to ensure we understand each setting

  • EnableValidation = false … When enabled (true) the service will search for the user in the target system to determine that the user account is valid and to raise an exception if the validation fails. When disabled (false), the User Identity Lookup Service only performs a static transformation specified in the UserIdentityMappings section.

  • UserIdentityLookupAddins … defines which custom lookup add-in to use for the session. In this case we are relying solely on the TFS Integration Platform and adapters.

  • DisplayNameMappings … Looking at the current documentation the DefaultUserIdProperty DisplayName is specific to TFS WIT migration sources, whereas DomainAlias is to TFS VC migration sources.

    • So why are we using displayname in this case then? Thanks to Bill Barnett we have a great explanation:

      The DomainAlias type mapping really is the correct thing to use when both of the VC servers involved use a username in the Windows “<domain>\<alias>” form to identify users. That’s not true for SVN and probably for other environments such as hosted TFS. The “DisplayNameMapping” type should be used whenever one or both of the VC servers don’t use “domain\alias” to identify users checking in changes

  • MappingRule=”SimpleReplacement” … implies that we simply replace the field value as shown in our example configuration file below. A configuration without wildcards, takes precedence over configuration with wildcards.

How do I configure this feature?

  • Determine if the custom adapter supports the UserIdentityMappings feature. All of the adapters that ship with the TFS Integration Tools support this feature, which includes TFS, Rational and SVN, through base and custom add-ins.
  • Create a migration session configuration using the TFS Integration Tools admin shell.
  • Edit the configuration file XML in the admin shell.
  • Find the UserIdentityMappings element.
  • Add the DisplayMappings to the UserIdentityMappings element.
  • Save the configuration to the database.

For more information, please refer to the configuration documentation and the hands-on walk-through labs as documented in Where Can Find Documentation?