Create a user mapping from a CSV file

Use PowerShell to generate a ShareGate Migrate user mapping file (SGUM) from a CSV file.

You can use the SGUM file in the Migrate app or a PowerShell script.

Note: The application automatically maps your users. ShareGate Migrate will map any users you do not add to your mapping file.

Prerequisites

Access to your users' information or your Active Directory/Microsoft Entra ID.

Create your CSV

You can create the CSV manually or get a list of users from your Active Directory. You will need a final CSV file with two columns: SourceValue and DestinationValue. You can use email, username, display name, or full name.

The file should look like this in Excel:

Tip: We recommend using email addresses, which are usually unique and include the domain.

Create your script

Copy and paste the following script into the PowerShell application of your choice.

# Import the ShareGate module
Import-Module Sharegate

# Define the path to the CSV file containing user and group mappings
$csvFile = "C:\CSVfile.csv"

# Import the CSV file into a table variable, specifying the delimiter as a comma
$table = Import-CSV $csvFile -Delimiter ","

# Create a new mapping settings object to store user and group mappings
$mappingSettings = New-MappingSettings

# Loop through each row in the imported CSV table
foreach ($row in $table) {
    # Set user and group mappings for each row in the CSV file
    $results = Set-UserAndGroupMapping -MappingSettings $mappingSettings -Source $row.SourceValue -Destination $row.DestinationValue
    
    # Output the source value for each row (for debugging or tracking purposes)
    $row.SourceValue
}

# Export the user and group mappings to a file
Export-UserAndGroupMapping -MappingSettings $mappingSettings -Path "C:\FolderName\FileName"

Adjust your script so that it will work for you. Here are a few guidelines:

$csvFile: Adjust the path so the script calls your CSV file.
$table: The delimiter is the symbol your CSV uses to separate your column items. Ensure your script uses the same delimiter as your file (a quick way to verify this is by opening the CSV in Notepad).
foreach: Loops through the values in your CSV file. You can learn more here.
$results: The results are stored in a results variable instead of getting printed in your PowerShell window to avoid performance issues.
$row.sourcevalue: Prints the source value, so you can track your progress.
Export-UserAndGroupMapping: Adjust the path to save the new ShareGate Migrate user mapping file (SGUM) to your desired location with the name of your choice.

Using the SGUM file

You can import the SGUM file in a migration script with the following line:

$mappingSettings = Import-UserAndGroupMapping -Path "C:\FolderName\FileName.sgum"

Then, call the mapping on your Copy line (it will work with all the copy options such as Copy-Site and Copy-Content). Add the following on the same line as your copy command:

-MappingSettings $mappingSettings

You can also Import the SGUM file with the ShareGate Migrate migration option in Copy by clicking the Import button in the Map users and groups menu.