Using Mappings in PowerShell

Find how you can use mappings in your PowerShell scripts.

Index

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

Mapping behaviors

When you use mappings in the application, the mappings you save are preserved for the source and destination combination automatically.

If you run a new PowerShell migration with the same source and destination combination, the mapping you saved in the application will be used.

Users and groups, Permission levels, and Site templates mappings are saved for the source and destination site collection combination, even if you are connected at a subsite or list when you save your mappings.

Properties and Content types mappings are saved for the source and destination list combination.

Mapping types

The PowerShell mapping commands will replicate the mapping options you can use in the application. 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 is 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 combination.
• Save mapping: Save your mappings for a source and destination combination.
• 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 combination. Use the Save mapping command to keep these mappings for your source and destination combination.

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 Mappings.
6. Map your users.
7. Click Export.
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 combination.
• $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.