The PowerShell mapping commands replicate the mapping options you can use in the ShareGate migration tool and give you more control over your migration.
- Mapping behaviors
- Mapping types
- Mapping commands
When you set your own mappings in the ShareGate migration tool, 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.
You can map a number of elements with the ShareGate migration tool. The mapping types are:
- Users and groups
- Permission levels
- Properties (Used with Copy-Content only)
- Content types (Used with Copy-Content only)
- Site templates (Used with Copy-Site only)
There are six PowerShell commands you can use for each mapping type. You will find a set of articles for each mapping type by clicking the mapping type of your choice in the Mapping types section above. These commands are:
- Set mapping: Create new mappings in your script.
- Export mapping: Export your mappings as a the ShareGate migration tool mapping file.
- Import mapping: Import your mappings from a the ShareGate migration tool 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.
Find how you can generate a mapping file, and how you can create a script with different mapping commands. The examples show User and group mappings since it is a common scenario. You can use the same principles with all the mapping types.
Export a mapping file from the UI
- Open the ShareGate migration tool.
- Select Copy in the menu bar.
- Select Copy structure.
- Connect to your source and destination site.
- Click on Mappings.
- Map your users.
- Click .
- Save the SGUM file on your drive.
Tip: You can refer to the Create a User Mapping from a CSV File article to create a complex, or company-wide user mapping file.
Use mappings in a PowerShell script
Import-Module Sharegate $mappings = New-MappingSettings $mappings = Import-UserAndGroupMapping -MappingSettings $mappings -Path "C:\MyMappings\MyUserAndGroupMappingsFileName.sgum" $mappings = Set-UserAndGroupMapping -MappingSettings $mappings -UnresolvedUserOrGroup -Destination "Inactive users group" $mappings = Set-UserAndGroupMapping -MappingSettings $mappings -Source "John Smith" -Destination "John Doe" $mappings = Remove-UserAndGroupMapping -MappingSettings $mappings -Source "John Smith" $srcSite = Connect-Site -Url "http://myfarm1/sites/mysourcesite" $dstSite = Connect-Site -Url "http://myfarm1/sites/mydestinationsite" Copy-Site -Site $srcSite -DestinationSite $dstSite -MappingSettings $mappings -Merge -Subsites
- New-MappingSettings: This command overrides any mappings you might 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.