Advania UK logo  Advania UK logo compact

SharePoint Migration with Metalogix – lessons learned

Advania - SharePoint site migration
Posted On
Written by
Duration of read
4  min
Share Article
Subscribe via email
I just wanted to share some lessons learned from a recent SharePoint migration project we have undertaken using both the Metalogix Essentials and Content Matrix tools. In this post, I will share some potential pitfalls so that hopefully you can rectify these complications in your own migration scenarios.


I had a client wanting to migrate their WSS 3.0 environment, and some old BPOS sites, in to SharePoint Online. While carrying out the migration of the BPOS sites and preparing for the WSS 3.0 migration, a few issues arose that needed to be rectified so that the migration of both BPOS and WSS 3.0 sites would go as smoothly as possible.

Unfortunately, there was a time-lapse between the initial work being carried out in BPOS and the next phase of the migration, however, this mainly meant looking at an incremental migration instead of a full migration.

Lessons learned from the SharePoint migration project

The following lessons were learned from the issues that were experienced during this SharePoint migration:

User mappings

In the Metalogix Essentials tool, there can be times when it is intuitive and if the user UPN is in a similar format e.g. then it can map the users for the created/modified by attributes. However, this does not always work and so results in content being labelled with the user that is logged in while doing the migration. A migration service account can be used; however, this needs to exist in both the source and target environments to map correctly.

Essentials uses a CSV file to map old user credentials to new user credentials

This allows for the correct created/modified by name to be used when content is copied. However, if a mapping file is not used when content is originally copied, and then you try to use a delta migration to update the attributes afterwards, this does not work. It sees the file in the target environment as up to date and so does not change it. A full migration or recopy with metadata using a CSV would be required to change the values. Please note that doing a copy with metadata takes considerably longer to complete.

Getting a list of users from AD is best done using the Microsoft gallery for PowerShell scripts

Although Essentials can be used to export site users from connected environments, the reports are on a Site Collection basis and so to retrieve all users it is better to connect to AD and retrieve the users in a CSV format. Remember, this is only the first part of the process as you need to get the users from Azure AD using an export or PowerShell before being mapped. The display name can normally be used with VLOOKUP formulae in Excel to match the old and new accounts, even if the format needs to be tweaked slightly.

The user mapping file for Essentials cannot be used in Content Matrix as it does not use a CSV for user mappings

This either means manually mapping all user accounts, which is no good in time critical projects, or when clients are being billed; or you can use an XML file instead. After having to switch from using Metalogix Essentials to Content Matrix after the license timed out, I had to find a way to create an XML file.

I wrote a small PowerShell script to create the XML file from a CSV file, and with some assistance from a colleague I completed the script after an issue was rectified. The script creates a “well-formed” XML file from the values that are mapped in the CSV file Metalogix have a great article for further information.

The PowerShell script that I have created is shared below and can be copied in to a file or Windows PowerShell ISE window:

#Import user mappings from existing CSV file - change the path and filename accordingly
$Import = Import-Csv -Path "C:\Users\<User>\Documents\Import_CSV_Mappings.csv"

#Create well-formed XML including the CSV mappings and add to the variable
$xmlData = “<Mappings>”

for($i=0; $i -lt $Import.length; $i++) {
$xmlData += “<Mapping Source=’$($Import[$i].Column1)’ Target=’$($Import[$i].Column2)’ />”

$xmlData += “</Mappings>”

#Output XML in variable to a file – change path and filename accordingly
$xmlData | Out-File “C:\Users\<User>\Documents\Export_XML_Mappings.xml”

Note: the above script is shared as an example and Advania take no responsibility for any issues that may occur in the running of this script.

Happy migrating!!

Sign up to receive insights from our experts

Get the latest news and developments from Advania delivered to your inbox

Other blog articles that might interest you

Driven by client success

We’re proud to work with the some of the most ambitious and innovative organisations.


Sign up to receive insights from our experts

Get the latest news and developments from Advania delivered to your inbox.