Articles in this section

See more

Use mappings in PowerShell

Updated

The PowerShell mapping commands replicate the mapping options you can use in ShareGate Migrate and give 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:

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

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

  1. Open ShareGate Migrate.
  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 the Export user and group mappings icon
  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.

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.

Related articles