Using Mappings in PowerShell

The PowerShell mapping commands replicate the mapping options you can use in the application and give you more control over your migration.

Index

• Mapping behaviors
• Mapping types
• Mapping commands
• Examples
  • Exporting a mapping file from the UI
  • Using mappings in a PowerShell script

Mapping behaviors

Setting your own mappings in ShareGate Desktop preserves them automatically for any future operations using the same source and destination.

Users and groups, Permission levels, and Site templates mappings are saved at the source and destination 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 source and destination list level.

Mapping types

You can map a number of elements with ShareGate Desktop. 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)

Mapping commands

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 ShareGate Desktop mapping file.
• Import mapping: Import your mappings from a ShareGate Desktop 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

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.

Exporting a mapping file from the UI

1. Open ShareGate Desktop.
2. Select Copy in the menu bar.
3. Select Copy structure.
4. Connect to your source and destination site.
5. Click on .
6. Map your users.
7. Click .
8. 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.

Using 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.