When running the VSS to TFS converter (VSSConverter.exe) one of the most common questions I hear is how to create a UserMap.xml file for users who are no longer with the company or have had their accounts renamed.

 

My first suggestion is that any customer who has to deal with this issue (or any user mapping issues – or users in a workgroup configuration) should start by getting the hotfix provided in KB 928828.  This can be gotten through your CSS (support) contact.

 

This hotfix changes the way that user authentication is done and is an important fix.  It is compatible with both RTM and SP1 however it was not included in SP1 (it was made after the SP1 cut-off date and does include all the VSSconverter fixes already in SP1). 

 

That said - what I’m going to describe is the same in both the RTM and SP1 versions as well as in KB 928828.

 

The correct way to deal with the users may be as simple as doing nothing.  Let me give you an example.

 

To test this out I created a sample VSS repository and added two users “User1” and “User2”.  These were in addition to the default users of “rhorvick” (me) and “Admin”.

 

I connected as “User1” and created some content.  Then as “User2” and created more.  And finally as “rhorvick” and created even more.

 

I then ran the converter in analyze mode.  This created the following UserMap.xml file:

 

<?xml version="1.0" encoding="utf-8"?>

<UserMappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <!--

This file is automatically created by VSS Converter. You can optionally use the file to map

a VSS user to a Team Foundation user. For example, <UserMap From="Jane" To="MyDomain\Janep"></UserMap>

This mapping causes all actions logged by VSS user “Jane” to be changed to Team

Foundation user “ MyDomain\Janep ” during migration.

-->

  <UserMap From="USER1" To="" />

  <UserMap From="RHORVICK" To="" />

  <UserMap From="USER2" To="" />

  <UserMap From="ADMIN" To="" />

</UserMappings>

 

At this point I just ran the conversion – I did not change the mapping file in any way.  Please note that User1 and User2 are NOT existing accounts on my TFS server.

 

With the QFE the conversion created the following history in TFS:

 

Changeset User          Date       Comment

--------- ------------- ---------- --------------------------------------------

10837     rhorvick      1/4/2007   {1/4/2007 3:47:26 PM}added by rhorvick---- D

10836     rhorvick      1/4/2007   {1/4/2007 3:47:22 PM}added by rhorvick

10835     rhorvick      1/4/2007   {1/4/2007 3:47:14 PM}

10834     User2         1/4/2007   {1/4/2007 3:47:00 PM}added by user2

10833     User2         1/4/2007   {1/4/2007 3:46:18 PM}

10832     User1         1/4/2007   {1/4/2007 3:46:00 PM}user 1

10831     User1         1/4/2007   {1/4/2007 3:45:12 PM}added by user1

10830     User1         1/4/2007   {1/4/2007 3:43:52 PM}created by user1

10829     rhorvick      1/4/2007   ----------------VSSConverter Project Mapping

 

So the migration did properly migrate the changes and attributed them to the proper authors.  I don’t know that I’m explaining this correctly – perhaps someone from Admin/Ops can explains it better – but when a checkin occurs and the author the change is being attributed to (which is not necessarily the account making the checkin call) is a non-existing user and the account is not a domain name or a TFS account/group name then a special identity is created which can only be used for the purpose of attributing changesets to (i.e. an audit-only account, not one that can be logged in as).

 

Now – had I wanted to attribute the changes to a real user I could have altered the mapping file like so:

 

<?xml version="1.0" encoding="utf-8"?>

<UserMappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <!--

This file is automatically created by VSS Converter. You can optionally use the file to map

a VSS user to a Team Foundation user. For example, <UserMap From="Jane" To="MyDomain\Janep"></UserMap>

This mapping causes all actions logged by VSS user “Jane” to be changed to Team

Foundation user “ MyDomain\Janep ” during migration.

-->

  <UserMap From="USER1" To="northamerica\rhorvick" />

  <UserMap From="RHORVICK" To="northamerica\rhorvick" />

  <UserMap From="USER2" To="northamerica\rhorvick" />

  <UserMap From="ADMIN" To="northamerica\rhorvick" />

</UserMappings>

 

And this time when I migrated I see the following history:

 

Changeset User          Date       Comment

--------- ------------- ---------- --------------------------------------------

10846     rhorvick      1/4/2007   {1/4/2007 3:47:26 PM}added by rhorvick---- D

10845     rhorvick      1/4/2007   {1/4/2007 3:47:22 PM}added by rhorvick

10844     rhorvick      1/4/2007   {1/4/2007 3:47:14 PM}

10843     rhorvick      1/4/2007   {1/4/2007 3:47:00 PM}added by user2

10842     rhorvick      1/4/2007   {1/4/2007 3:46:18 PM}

10841     rhorvick      1/4/2007   {1/4/2007 3:46:00 PM}user 1

10840     rhorvick      1/4/2007   {1/4/2007 3:45:12 PM}added by user1

10839     rhorvick      1/4/2007   {1/4/2007 3:43:52 PM}created by user1

10838     rhorvick      1/4/2007   ----------------VSSConverter Project Mapping