The PowerShell mapping commands replicate the mapping options you can use in ShareGate Migrate, giving you more control over your migration.
Index
Mapping behaviors
When you set your own mappings in ShareGate Migrate, it preserves them automatically for future migrations you perform with the same source and destination.
Users and groups, Permission levels, and Site templates mappings are saved at a site collection level, even if you are connected at a subsite or list level when you save your mappings.
Properties and Content types mappings are saved at a list level.
Mapping types
You can map a number of elements with ShareGate Migrate. The mapping types are:
Properties (Used with Copy-Content only)
Content types (Used with Copy-Content only)
Site templates (Used with Copy-Site only)
Mapping commands
There are six PowerShell commands you can use for each mapping type. These commands are:
Set mapping: Create new mappings in your script.
Export mapping: Export your mappings as a ShareGate Migrate mapping file.
Import mapping: Import your mappings from a ShareGate Migrate mapping file.
Get mapping: Get the mappings saved for another source and destination.
Save mapping: Save your mappings for a source and destination.
Remove mapping: Remove specific mapping items from the existing mappings.
Note: Setting mappings in a PowerShell script does not save them automatically for your source and destination. Use the Save mapping command to keep these mappings for future migrations.
Example
See how to generate a mapping file and create a script with different mapping commands. The examples show User and group mappings, which is a common scenario, but you can use the same principles with all the mapping types.
Export a mapping file from the UI
Open ShareGate Migrate.
Select Copy in the menu bar.
Select Copy structure.
Connect to your source and destination site.
Click Mappings.
Click the Export user and group mappings icon.
Save the SGUM file on your drive.
Tip: See the Create a User Mapping from a CSV File article to learn how to create a complex or company-wide user mapping file.
Use mappings in a PowerShell script
Import-Module Sharegate
# Create a new mapping settings object
$mappings = New-MappingSettings
# Import user and group mappings from an external file
$mappings = Import-UserAndGroupMapping -MappingSettings $mappings -Path "C:\MyMappings\MyUserAndGroupMappingsFileName.sgum"
# Set mapping for unresolved users or groups to be assigned to the 'Inactive users group'
$mappings = Set-UserAndGroupMapping -MappingSettings $mappings -UnresolvedUserOrGroup -Destination "Inactive users group"
# Set mapping for a specific user from 'John Smith' to 'John Doe'
$mappings = Set-UserAndGroupMapping -MappingSettings $mappings -Source "John Smith" -Destination "John Doe"
# Remove a specific mapping for 'John Smith'
$mappings = Remove-UserAndGroupMapping -MappingSettings $mappings -Source "John Smith"
# Connect to the source site
$srcSite = Connect-Site -Url "http://myfarm1/sites/mysourcesite"
# Connect to the destination site
$dstSite = Connect-Site -Url "http://myfarm1/sites/mydestinationsite"
# Copy the source site to the destination site using mapping settings, enabling merge and subsites
Copy-Site -Site $srcSite -DestinationSite $dstSite -MappingSettings $mappings -Merge -Subsites
New-MappingSettings: This command overrides any mappings you have previously saved for the source and destination.
$mappings: We repeat this variable, adding -MappingSettings $mappings on each line to add or remove elements from the mappings.
Import-UserAndGroupMapping: This imports a user mapping file. The file can contain many user mappings.
Set-UserAndGroupMapping: Adds a new user mapping. In this case, it adds a mapping to the mappings you established with Import-UserAndGroupMapping.
-Source and -Destination: Set the value you want to map with -Source and set the new value with -Destination.
-UnresolvedUserOrGroup: You can replace -source by -UnresovedUserOrGroup when you want to map all the orphaned users to another user account or security (active directory) group.
Remove-UserAndGroupMapping: Removes a user mapping. In this case it subtracts a user mapping from the mappings you established in the previous $mappings lines.
Copy Site: The command to copy a site. Add -MappingSettings $mappings to apply the mappings you established in the $mappings variable.