Articles in this section

2. Learn

Updated
Follow

Learn goes over the main migration features and how to use them. We cover different scenarios and general subjects that could affect your migration.

Tip: Set a sandbox environment to start testing and learning how to use the features in the ShareGate migration tool.

Index

Connection

The ShareGate migration tool requires that you connect to your environment when you launch a migration. Added layers of enterprise security, custom authentication, proxy connections, and more can cause issues when you try to establish a connection.

The ShareGate migration tool impersonates you in order to connect to the environment and perform actions. Your network identifies this as an application performing actions and not you directly. As a result, you might still get an error when connecting in the app with the same username and password you would normally use to connect directly to your environment.

For more information, review our connection section for general guidelines and troubleshooting.

Note: We do not recommend using an app password. For more information see App password.

Copy options

There are several options you can use to perform your migration. You can access these from the migration screen once you are connected to your environments.

The available copy options depend on your migration scenario. We will cover the options relevant to the subjects in this guide.

For more information, see Copy options.

Site migrations

Most migration jobs will consist of moving site collections from a SharePoint environment to another.

The basic steps for a site migration can be found in the article, Copy structure and content.

Multiple site collections

To migrate multiple site collections, connect to your Central admin or Admin center URL at the source and the destination. This way you will be able to select multiple site collections to migrate.

A single site collection

If the highest permission level you have is site collection administrator at the source and destination, you can connect directly to a source and destination site. You can then use Merge in your copy options to migrate your source site into a new destination site.

Note: To use Merge, you will need a site collection at the destination. The application will try to replicate the source site in the destination site as much as possible. This means that site settings, pages, and more will get updated based on the source in this scenario.

Subsites

You can connect directly to the URL of a subsite for your migration.

If you connect to the parent site or site collection, you can also copy multiple subsites.

When you get to the migration screen, double-click on the site collection you previously selected in the connection process to reveal the subsites. You can then select multiple subsites to move to the destination.

Site permissions

The ShareGate migration tool will replicate your permissions as closely as possible when you migrate a site. Your permissions will be handled differently when you migrate a site collection as a subsite (demote) or a subsite as a site collection (promote).

Find more about how the permissions are handled, see Copy structure and content - Permissions.

Note: Permissions are migrated alongside the object they are applied to. You cannot migrate permissions independently.

Content migrations

Content migrations include Copy content, Import from file share, Import from Google Drive and Import from Box.com in the ShareGate migration tool.

You get more flexibility over the content and metadata with these features. This is because content migrations are focused on a single destination library (and source if you are migrating content from SharePoint), allowing the application to work with your columns and library settings.

You can find links to the basic steps for each migration type below:

Note: Content migrations can only be performed one list or library at a time since they rely on the list settings and columns available at the destination.

Metadata

There are a few ways you can handle Metadata. You can map metadata values from one property to another, you can set defaults or ignore values for certain properties in your copy options, and you can use Excel to modify your values.

You can find these methods with the links below:

Content level permissions

Your list items and documents permissions are migrated as part of the items.

Having many items in a list or library with custom permissions is not recommended. It can become very difficult to manage, and it will slow down SharePoint when accessing that list or library.

You can migrate content without migrating the permissions by unchecking Custom permissions in your copy options.

Find more about how the permissions are handled, see Copy content - Permissions.

Tip: If you have a library with a lot of items that have custom permissions, you can migrate these items without their permissions and settings, and then set the permissions at the library level. Alternatively, you can reorganize them into folders, where you can then apply new custom permissions.

Copy content from SharePoint

You can copy content from a SharePoint list or library with Copy content. This operation requires a source and destination list or library.

You will need the same columns available at the destination to preserve the metadata values in all your columns.

Tip: You can create an empty copy of your source list or library at the destination for your content migration. Use Copy structure and from Lists and libraries in the left panel, select the source list or library you want to copy. Then click on Options in the top right corner, and uncheck List content. This will copy that list or library without content.

Import from Google Drive

A migration can only be performed for Google Drive users that are part of a G Suite organization. The connection is made with your Google email and you can use administrator mode to migrate multiple user accounts in your G Suite.

For more information on Google Drive migrations, see Walkthrough - Import from Google Drive.

Import from file share 

There is no connection screen for your file share in the application. You have to map your drive to your system and have proper permissions on the file share (at least Read and Read permissions).

When you select Import from file share you must connect to your destination library, and you are then asked to select the drive you want to migrate in the migration window.

Your file share permissions are migrated along with the folders or documents selected. When you migrate documents in a SharePoint library, the permissions of the library are not updated based on the permissions of the file share. Only the permissions attached to the folders or documents you migrate are copied.

For more information on importing documents to SharePoint from a file share, see Walkthrough - Import from file share.

For more information on your file share permissions, see Import from file share - Permissions.

Tip: Import from file share can be used to migrate data from an unsupported source to SharePoint. If you can export your content to a file share or mapped drive, then you can use the import from file share feature to bring that content to SharePoint. Take this further by using Excel or CSV to add and modify your metadata in the process.

Import from Box.com

You can only migrate from box.com with PowerShell (we cover PowerShell later in this section).

You might need to impersonate the owner of the box account for your migration. For more information, see Impersonate an owner for Box.com migration.

You can find some basic Box.com script examples in the Import from Box.com article.

If you are migrating your box accounts to OneDrive for Business, you can find a complete walkthrough in the Import from Box.com to OneDrive for Business with PowerShell article.

Teams migration 

The ShareGate migration tool supports migrating Teams. You can migrate your public channels and message history.

For information on migrating Teams, see Walkthrough - Copy teams.

Note: There is a number of limitations for Teams migrations. For more information, see Copy teams - Limitations.

Incremental migration

In your copy options, you will find a copy mode called Copy if newer (incremental). This mode allows you to update the content of your lists and libraries without having to migrate every single list item or document. To do this, the application compares your items between the source and destination, then only copies newly created items and items with a newer modified date from the source.

Note: Only your content will be affected by the setting if you migrate a site or site collection. List items and documents that already exist in the destination and were not modified in the source are skipped while your entire structure is copied.

For more information, see Copy if newer (incremental).

When you run a migration

Here we cover a few subjects that can impact you when you run your migrations.

Pre-check

You can run a Pre-check before launching your migration to detect any errors and warnings you might encounter. This can help you solve potential issues before running your actual migration.

Though running a pre-check is faster than a migration, it can still take some time if the operation is larger or more complex. This is because the pre-check simulates your migration and performs a lot of the operations the app would do during a regular migration.

For more information, see Run pre-check.

Workflows

Workflows are not disabled when you use Copy content. If you do not want your content affected by a workflow you have to disable it in the destination first.

Simultaneous migrations

The ShareGate migration tool allows you to run multiple migrations at the same time.

Though it can help you streamline your migration project, running simultaneous migrations can create a bottleneck which might slow things down considerably.

Migrations send many requests to the servers and require several operations to be made on all the machines involved. Running a second migration means you are effectively doubling the impact on your servers and workstations.

You might experience throttling if you send too many requests to Microsoft 365 with the app.

How many simultaneous migrations you can run depends on hardware, content complexity, bandwidth, network, and so on. 

To run simultaneous migrations, we recommend that you test thoroughly to determine at which point your migrations start slowing down. Add migration instances progressively and monitor the effect of each new instance to determine how many you can run before migration time is affected.

Ultimately, it is faster to run a single migration instance that runs at a stable pace than to run multiple instances that start slowing each other down.

Note: You could have performance issues during a migration with multiple instances even after you tested it. Reduce the number of simultaneous migrations if you start to see any kind of performance issues.

Throttling

Throttling can happen when you run a migration to Microsoft 365. The servers will slow down your connection in an effort to keep the service healthy for all users.

For more information, read the Microsoft 365 throttling article if you plan to migrate to Microsoft 365.

Large lists and libraries

There are challenges to migrating large lists and libraries with thousands of items and added complexity (like custom permissions, lookup columns and more).

Such lists and libraries can cause a site migration to fail with a server or Azure error, and set your migration project back.

If you have a library that causes this kind of issue during a site migration, you can try migrating the site without content first (uncheck List content in the copy options), then from the Copy structure and content screen, select Lists and libraries in the left column to migrate all the other lists and libraries with their content.

You can then migrate the large list or library by itself.

If the list or library migration fails again, use Copy content to migrate the list or library content in batches.

You can split your content with the time range filter in the copy options, or with SharePoint views that you can create to filter your content in the application.

Troubleshooting

Migration report

For each migration task you complete, a migration report is generated. You can find all your migration reports in the Tasks screen of the app.

Your migration report tells you what was migrated, where the content is located, at what time it was migrated, what failed, and what might require your attention.

You get errors in the report when potentially critical content failed to migrate.

You get warnings in the report if your content was migrated, but could not be copied exactly as it is at the source.

You can find some details about errors and warnings in your migration report.

Your errors usually come with a Help me solve this link that brings you to an article that explains it. In most cases, the article suggests a solution or workaround for the issue.

Tip: To review a larger migration report, export your migration report to Excel. In Excel, select the first line (the headers for all the columns), then type CTRL+SHIFT+L on your keyboard to add filter buttons on all the columns. This way it becomes very easy to filter the Status column to reveal only errors and/or warnings. You can then further filter these errors for a specific site, list, or library.

Support

If you have an issue you can't overcome, our support team can help you.

For a faster resolution, we strongly recommend that you export your complete Migration report and attach it in your request.

Sometimes the errors you experience might seem like they can be easily resolved with basic information, but unexpected issues often require our team to analyze the many parameters of your migration (source, destination, app version, other error messages, etc.).

For information on reaching our support team, see Contacting our technical support team.

Automate with PowerShell (recommended for advanced users)

You can automate your migrations with PowerShell when you are dealing with a large and/or complex migration project.

Here we cover a few guidelines and resources to help you get started with our PowerShell commands.

If you are new to PowerShell we recommend using PowerShell ISE as it has a useful script editor to modify and run your scripts from.

Note: You must run your scripts on a machine with the ShareGate migration tool installed for the commands to work.

Migration commands

You can find articles with script examples for each available PowerShell command in our help center. You can copy/paste and adjust these script examples for your specific needs.

You can find the basic migration commands below:

Note: Site collections cannot be provisioned during a migration with PowerShell. If you are not migrating to an existing site collection you must create a new one to migrate to.

PowerShell connection

You might have to adapt the connection method in your script based on the requirements of your environment. We suggest trying to connect directly in the application and reproducing the connection method that works for you in your PowerShell script.

For more information, and some examples on connecting with PowerShell, see Connect Site.

Copy options in PowerShell

You can limit versions, change the copy mode, or use any of the copy options available in the application with PowerShell.

For more information on replicating your copy options with PowerShell, please refer to the Replicate Copy Options guide.

Copying multiple objects from an Excel or CSV list in PowerShell

If you are comfortable with the basics, you can create a more complex script with a foreach loop. With foreach, you can migrate different site collections to different locations.

To learn how you can use a foreach loop in your script, see Copy to and from multiple destinations with a foreach loop statement and a CSV file in PowerShell.

OneDrive for Business PowerShell walkthroughs

OneDrive for Business migrations can only be done one OneDrive at a time in the ShareGate migration tool. For this reason, using PowerShell is recommended if you need to migrate a complete list of users' OneDrives.

OneDrive PowerShell migrations are covered for almost every scenario in our help center. You will find all the examples in the OneDrive PowerShell help center section.

Reporting

Reports can help you find important information for your migrations. You can use a number of pre-made reports in the Reporting screen of the application, and you can create custom reports to pinpoint important information about your environments.

You can find articles for the general pre-made reports in the All Reports help center section, and articles on the pre-made security reports in the Security help center section.

For more information on creating custom reports, see Create a custom report.

Training videos

Explore our ShareGate training video library for quick and informative capsules on how to migrate, govern, and future-proof your SharePoint and Microsoft Teams environment using industry best practices.

For more info, see ShareGate Training.

Next

Related articles