Articles in this section

2. Learn

Updated

Learn covers the main migration features and how to use them. We also 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 ShareGate Migrate.

Index

Connection

ShareGate Migrate 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.

Though ShareGate connects to your environment and performs actions as if it were you, your network can still identify that it's an app running these actions. As such, you can still get connection errors with your username and password if you have certain restrictions on your network.

Review our connection section to learn more about general guidelines and troubleshooting connection issues.

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

Copy options

You have several options for performing your migration. Once you are connected to your environments, you can access your copy options from the migration screen.

The available copy options depend on your migration scenario. This guide covers the options relevant to its subjects.

For more information, see Copy options.

SharePoint site migrations

ShareGate was created to move SharePoint sites from one Microsoft environment to another.

Multiple site collections

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

Single site collection

If your highest permission level is site collection admin at the source and destination, you can connect directly to your source and destination sites. Then, you can 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

ShareGate Migrate replicates 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).

To find out 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 only, Import from file share, Import from Google Drive and Import from Box.com in ShareGate Migrate.

These features give you more flexibility over your content and metadata migration. Content migrations are focused on a single destination library, allowing the app 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, set defaults or ignore values for certain properties in your copy options, and use Excel to modify your values.

You can find these methods with the links below:

Content level permissions

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

It is not recommended to have many items in a list or library with custom permissions. This can become very difficult to manage and slow down SharePoint when accessing the list or library.

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

To find out more about how the permissions are handled, see the appropriate permission article below:

Tip: If you have a library with many items with custom permissions, you can migrate these items without their permissions 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 in 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. Then your are 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 library's permissions 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.

Tip: Import from file share can migrate data from an unsupported source to SharePoint. If you can export your content to a file share or mapped drive, you can use the import from file share feature to bring that content to SharePoint. You can 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).

For your migration, you might need to impersonate the owner of the box account. 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 planning a migration from Box.com to OneDrive for business, see Import from Box.com to OneDrive for Business with PowerShell.

Teams migration 

ShareGate Migrate supports copying Microsoft Teams. You can migrate your team's channels and message history along with their associated SharePoint site collections and files.

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

Note: Teams migrations have limitations. For more information, see Copy teams - Limitations.

Mailbox migration

Copy exchange mailboxes from tenant to tenant.

Requires the Pro package (I asked if the addon is still available on the essential package, but that doesn't seem to be the case).

Link to overview, limitations, and best practices.

Performance is getting worked on, read on our best practices.

App permissions are required and can be consented to when connecting the tenant for the first time.

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: When you migrate a site, list, or library, the setting will only affect your content. List items and documents that already exist in the destination and were not modified in the source are skipped while your entire structure is re-copied.

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

Considerations

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 turned off when you use Copy content. If you do not want your content affected by a workflow you have to turn it off in your destination first.

Simultaneous migrations

ShareGate Migrate 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 ShareGate Migrate 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 ShareGate Migrate. 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