Revised on August 12, 2010.
The Lookup Service has been floating around as part of the TFS Integration Platform tools for some time, but has not received much attention to date. After it has been thoroughly tested and is adding value at one of our proof-of-concepts, it is time to let the service our of the binary bucket.
Quotation from Bob, Visual Studio ALM Ranger, who is running one of our CQ—>TFS proof of concepts: “ClearQuest uses an “open user name format” and so it would be very difficult to develop a standardized algorithm to covert CQ user names to the AD display names used by TFS. However, CQ does maintain the AD alias (account ID) for each user. The LookupService enables us to take the user account for each CQ user, look up the display name in the AD and use that when populating user fields in TFS work items. This means we have out of the box, 100% reliability of mapping user names for our CQ to TFS migration.”
So, what is it and why should we care?
The service is intended to assist us with the translation of the source user information to the target user information, in scenarios where we are dealing with different environments such as ClearQuest on the source and TFS on the target, or cross domain migrations.
During the first phase the TFS Integration Platform will ask the source adapter for more information, such as email address, display name or domain name. For example, migrating from CQ, we only have the users alias or account name, from information stored in a record field.
The second phase is performed by the UserIdentityLookupService in the platform to perform string replacements, string concatenations and formatting. It is basically the user information transformation phase, excluding validation of the user account. The transformation is done during the “Analysis” phase of the migration pipeline and the adapters are not involved.
- “Validation and Population”
Phase three performs the target user validation, by talking to Team Foundation Server (TFS), Active Directory (AD) or another custom target lookup provider. It essentially validates the target user information and populates the target system information.
- Should all adapters implement support for this service?
- There is out of box support for AD, CQ and TFS 2010 (see UserIdentityLookupService.cs and TFS2010UserIdLookupAdapter.cs for details).
- The lookup service is an add-in, which means the adapters do not have to implement anything. Instead we “add-in” the functionality through configuration and the add-in at run-time.
- Why not just use value mapping rules in the configuration?
- The Lookup Service provides additional validation and retrieval of additional run-time information.
- User information stored with an artefacts (Changes, WIT) only contains display name, which would force us to make a lot of assumptions.
Here is an example configuration file (extracts) that configures the service for a migration from ClearQuest to TFS. Let us briefly explore the contents:
- Lines 7-9 … we configure the TFS Active Directory User Id Lookup Service addin.
- Lines 14-16 … we configure the CQ migration source user identity lookup to use the addin.
- Lines 29-31 … we configure the TFS migration source user identity lookup to use the addin as well.
- Lines 60 - 67 … we configure stage 1 lookup information. In this case we need to lookup the alias for the owner on CQ side and the DisplayName for the AssignedTo on the TFS side.
- Lines 103 – 111 …we configure stage 2, the transformation, using SimpleReplacement in this example.
NOTE 2011-10-26: The UserIdLookupEnabled attribute has been deprecated and replaced with a more readanble EnableValidation attribute with the build dated June 2010.
Note the DefaultUserIdProperty (line 22) and DomainMappings (lines 51-53) configuration elements, which are different from the previous example.
A bit more information on some of the configuration elements
MappingRules (enum) Description DisplayName Users display name, which specific to TFS WIT migration sources Domain Users domain name. Alias Users alias name. DomainAlias Users fully qualified domain alias name, which specific to TFS VC migration sources EmailAddress Users email address. UniqueId Users security identifier (SID). QualifiedName Users distinguished name. (CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=COM)
MappingRules (enum) Description SimpleReplacement Simply replace the field value as shown in our example configuration file. Note that Line 109, without a wildcard, takes precedence over line 109, replacing all fields with no value in the source with testuser on the target. FormatStringComposition See What is the Lookup Service? Q&A-27 Errata 1 FormatStringDecomposition See What is the Lookup Service? Q&A-27 Errata 1 Ignore Ignore the field and perform no mapping.
NOTE: We recommend that you refer to the latest documentation that is included with the TFS Integration Platform for the latest configuration features and rules.