Migrations can be run through either the "Run" tab in MigrationConfig.exe or by running a console application named MigrationConsole.exe and passing in the name of the configuration file that was created in the Configuration section to tell MigrationConsole.exe what you want to migrate.
The "Run" tab in MigrationConfig.exe is useful for interactively configuring and testing a migration while MigrationConsole.exe can be scheduled as a Windows job to periodically resync a repository while moving development teams over to the new system.
As the migration runs, general status is written to a console including information about each of the file or label/tags that are being processed and whether the migration is in the analysis or migration phase. Within each phase, files will usually be processed first followed by labels/tags.
Between the analysis and migrations phases, the migration attempts to map users in the origin source database with users in the target source database. Whenever there is a discrepancy between the two, the migration will pause and force the user mappings to be reconciled before it will continue. If the user mappings are not reconciled the session will abort. The details surrounding the configuration file is discussed later in the User Mapping section.
For the MigrationConfig.exe "Run" tab session status will look like:
For MigrationConsole.exe session status will look like:
When dealing with various source control systems, it is likely that the other source control system is not tied into Active Directory or over time employees will come and go, so the accounts that exist in your source history do not correspond to active accounts on the destination server.
To deal with these situations, a mapping file will be used to translate accounts from the original source control system to the destination.
During the analysis phase, the mapping file will be built up as each change in the origin source control system is examined and new users are encountered. At the end of the analysis phase the mappings will be written out to a file named <Session Id>UserMappings.xml.
Then before the migration phase starts, the mapping file will be validated to see if any user names are new or if the accounts have been deactivated since the last session run. For new users, the migration will attempt to map users in the file to users in the destination.
For TFVC destinations, if the user is found in the Azure DevOps server or in the Active Directory Domain, the mapped user name will be updated to be the Windows account for that user. If not, the user name will be added as the mapped name so that the system will create an audit read only account to attribute the changes to.
For Git destinations, if the user name format appears to be an Active Directory format, the email address will attempt to be looked up from Active Directory. If one can not be found, the DefaultUserEmailDomain setting will be used to default the mapped name to the Active Directory user name with that setting.
In either case, the mapping file will have that user's entry flagged as "Needs Review". If there is an entry flagged as "Needs Review", the migration phase will display a dialog to allow you to verify that mapping makes sense and set the "Needs Review" flag to false.
Let’s take the following example:
John and Jane Doe once both worked at Timely Development and contributed to code. John was forgetful and stopped being able to remember his password, so he created a second account for himself. This resulted in the johndoe login being attributed to the domain account, while johndoe2 was assigned a default audit read-only account. Since both johndoe and johndoe2 accounts were for the same person, the "MappedName" attribute for johndoe2 should be updated to reflect the domain account. As we are using a domain account for John, we should leave the "Active User" flag as true so that if the account is no longer usable we will be notified of the change and can remap the two accounts.
As for Jane, when the migration occurred, Jane no longer worked at Timely Development and a domain login for her did not exist. Because of this she was assigned an audit read-only account. Since that account will never validate to a domain account we can set the "Active User" flag to false.
After making these changes the mapping file should look like this: