SharePoint Migration with Metalogix – lessons learned

Jan 2, 2018 | Blog, SharePoint, SharePoint Upgrades | 0 comments

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 Content and Code take no responsibility for any issues that may occur in the running of this script.

Happy migrating!!

About our author

Lee Palmer

Solutions Consultant | Content and Code

Lee is a Solutions Consultant working in the Enterprise Solutions Architects team. Although his primary focus has been SharePoint – previously on-premise deployments with Microsoft, and now SharePoint Online for the past 3 years; he has evolved to help clients build solutions across the products in the Office 365 stack, including Microsoft Teams. Lee has helped a number of clients with migrations from older versions of SharePoint, BPOS, and file shares in to SharePoint Online. He is also accredited with Metalogix and Nintex, who Content and Code work very closely with.


Submit a Comment

Your email address will not be published. Required fields are marked *


Announcement: Content and Code will be joining IT Lab

Today we're delighted to announce that Content and Code will be joining IT Lab. The coming together of these two great companies represents an amazing opportunity for our clients. We've always been about changing the way the world works. Helping our clients digitally...

read more

Ignite Announcements: Modern SharePoint, Teams, Search

Continuing with our top announcements from Ignite, we saw again Microsoft focus on the improvements around Modern Teamwork capabilities and a renewed effort to improve the modern SharePoint experience. We mentioned in our first Ignite announcements post that Microsoft...

read more

Day 1 – Microsoft Ignite Keynotes and Announcements

We’re excited to have a dedicated team from across Content and Code in attendance at this year’s Microsoft Ignite in Orlando, Florida. We were very keen to ensure that we covered all basis this time round. To ensure that we can add value to each and every one of our...

read more