How to migrate the documents

Here you find instructions on how to migrate documents from a file share or from a SharePoint 2010/2013 environment using the SharePoint Migration Tool.

  1. Start the Migration tool (click on Windows start menu and search for “SharePoint”):
    Start the Migration tool
  2. As the application is regularly updated, quite often during the application launch, you will be prompted with a request to update the tool:
    Update the Migration tool
    Our recommendation is to always use the latest version of the tool, so click on the “OK” button.
  3. Login to the tool. The account that you login with needs to have “site collection administrator” rights on the workspace/site where you will migrate the documents to. If it is the first time that you run the tool or if you have not saved any previous jobs, you will get to this welcome page:
    The Migration Tool's welcome page
    Click on the “Start your first migration” button.
  4. In the “Where’s your content” step, select the location for the source files and click on the “Next” button:
    Define where’s your content
    The options to select are:

    1. SharePoint Server 2010 or 2013, see details in point 5 below.
    2. File Share, see details in point 6 below.
    3. JSON or CSV file for bulk migration (to use this option you need to have created a JSON/CSV file for migration
  5. If you selected the “SharePoint Server 2013 or 2013” option:
    1. In the “Select a source” step, paste the path to the site where the documents are located. You will now have to login to the site and the account that you login with should have “site collection administrator” rights on the site, giving you access to the whole site and its resources. If the site has subsites, you can choose to as well migrate the subsites. Then choose whether you want to migrate all lists, libraries, pages and web parts or if you only want to migrate a specific list/library. In the case of migrating documents to MetaShare, you probably just want to select a specific document library. When done, click on the “Next” button:
      Select a source
    2. In the “Select a destination” step, paste the path to the site where the documents will be migrated to. Also enter the display name of the library where the documents should be migrated to. When done, click on the “Next” button:
      Select a destination
    3. In the “Review migration” step, review the information on the screen. Optionally you can run multiple jobs by adding other sources, once you are done click on the “Next” button:
      Review the migration
  6. If you selected the “File Share” option:
    1. In the “Select a source” step, paste the path to the folder where the documents are located, or click on the “Choose folder” button to navigate to the folder. When done, click on the “Next” button:
      Select a source
    2. Select “SharePoint team site”
      Where do you want to move it to
    3. In the “Select a destination” step, paste the path to the site where the documents will be migrated to. After validating the path, select a library where the documents will be migrated to, in the case of a MetaShare workspace, select “Documents”. When done, click on the “Next” button:
      Select a destination
    4. In the “Review migration” step, review the information on the screen. Optionally you can run multiple jobs by adding other sources, once you are done click on the “Next” button:
      Review the migration
  7. Choose the settings options and when done, click on the “Migrate” button. The available options are:
    1. Only perform scanning:
      Only perform scanning
      This option will not conduct any migration, unless you select the option to “Start migrating automatically, if no issues were found”. Before migrating, the recommendation is to first either only conduct a scanning, as this will give you a report of any possible issues before you actually run the real migration or to conduct a test migration to a test site.
    2. Preserve file share or SharePoint permissions:
      Preserve file share permissions
      Preserve SharePoint permissions
      If the destination document library inherits permissions from the site (which is the default setting), the migration tool will, in the beginning of the migration, break this permission inheritance and remove all permissions to the library. During the migration it will however add whatever permissions the source root folder has, but only if the folder does not inherit permissions from its parent folder. Migrated documents without any specific permission in the source will inherit the permissions from the target library. Migrated files with unique permissions in the source will carry over these permissions to the source, as unique. Read this page for more information about the outcome of the file permissions, when using this setting. To keep the same permissions on the document library’s root folder, as are defined in the site, a recommendation is to stop the permission inheritance for the library before migrating the documents. The library will still get the same permissions as are set on the site:

      1. The “Owners” SharePoint group will still have “Administrate” permissions on the site
      2. The “Members” SharePoint group will still have “Contribute” permissions on the site
      3. The “Visitors” SharePoint group will still have “Read” permissions on the site

      This is how you stop inhering the permissions on the document library:

      1. If you want to restrict the Members from adding or editing documents in the migrated workspace and you haven’t already performed step 4 in these instructions, How to prepare MetaShare for migration, then do this first, before you continue with the next steps below.
      2. Open the workspace’s SharePoint site.
      3. Open the document library’s settings by clicking on “Site contents” on the left navigation, then clicking on the ellipsis (three vertical dots) and selecting the “Settings” option:
        Open the document library's settings
      4. Under the “Permissions and Management” section, click on the “Permissions for this document library” link:
        Click on the "Permissions for this document library" link
      5. On the ribbon, click now on the “Stop Inheriting Permissions” function
        Click on "Stop Inheriting Permissions"
        You will be asked to confirm that you want to create unique permissions for the folder, click on the “OK” button:
        Confirm that you want to create unique permissions for the folder
    3. Migrate file version history:
      Migrate file version history
      This option is only applicable for migrations from SharePoint Server 2013, even if it is shown as an option when migrating a file server. If you select this option, you will also be able to define if you want to keep all versions and if not, how many versions you want to keep:
      Define if you want to keep all versions
    4. Azure Active Directory lookup:
      Azure Active Directory lookup
      If you select this option, the recommendation is to check that the documents’ “Created by” and “Modified by” columns will be linked to known users. If they are broken, you probably need to create and define a “User mapping file“:
      Define a user mapping file
      If you choose to use a custom user mapping file and want to preserve user permissions, turn off Azure Active Directory lookup. By doing so, if a user isn’t found in the mapping file, the tool won’t look it up in AAD.
    5. Migrate hidden files:
      Migrate hidden files
      The recommendation is that the setting is set to Off, disabling hidden system files to be migrated.
    6. Define to only migrate documents that are created or modified after a specific date:
      Define to only migrate documents that are created or modified after a specific date
      A recommendation is to maybe only migrate documents that have been modified the last 10 years. Older documents than this might maybe not need to be migrated.
    7. Do not migrate files with these extensions:
      Do not migrate files with these extensions
      Typically, these file extensions are excluded: .ds_store, .db, .ini, .tmp, .exe and .dll.
      Each file-extension should be separated with a colon, and the input-string would then look like this:
      :ds_store :db :ini :tmp :exe :dll
    8. Migrate files and folders with invalid characters:
      Migrate files and folders with invalid characters
      The recommendation is that the setting is set to “Off”, not allowing migration of files and folders with invalid characters, as it also will improve performance during migration.
    9. Migrate OneNote folders as OneNote notebooks:
      Migrate OneNote folders as OneNote notebooks
      This option is only applicable for migration from file share. We do not see any reason why not to allow migration of OneNote folders.
    10. Options only available for migration from SharePoint:
      1. Decide if you want to not include any subsites, lists and content types:
        Decide if you want to not include any subsites, lists and content types
      2. Skip lists with audience targeting:
        Skip lists with audience targeting
      3. Migrate all site fields and content types:
        Migrate all site fields and content types
        If you select this option, all the source site’s site columns and content types will be created as site columns/site content types in the destination site and the columns used in the source site’s document library will also be added to the destination site’s library.
      4. Migrate managed metadata:
        Migrate managed metadata
        If you select the option to “Migrate managed metadata”, then all term sets in the source site’s term store will be migrated to the destination site’s term store.
      5. Migration of web parts and pages:
        Migration of web parts and pages
        For a typical migration to MetaShare, there’s no reason for this option.
    11. Migration auto re-run:
      Migration auto re-run
      You can set the tool to run up to 5 times, looking for any changes or additions, since the migration job was started.
  8. Once the migration has completed you will see a summary report of the migration, with the option to open the log files (there are several log files out of which the migration error log file, FailureSummaryReport.csv, is the most important).
  9. After a migration task has completed you will also be asked if you want to save the migration job so that you at a later time can rerun the migration, allowing you to migrate only new or updated files in the source location.
  10. If your migrated workspace has more than 5 000 documents, you might want to index the columns that you will be presenting in these workspaces (document filters and/or view-columns), so that these columns can be filterable and/or sortable. Something to know about large workspaces is that you cannot change the permissions on the library if it has more than 100 000 documents. If you need to change permissions you will first have to delete documents so you have less than 100 000, change permissions and then restore the documents from the recycle bin.

Tips and tricks when using the tool

  1. Too long file paths:
    The solution to the “too long” messages, when files have longer paths than 260 characters, is to run the migration tool on a Windows Server 2016 or Windows 10 operating system with the HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled registry setting to 1 and use .NET framework version 4.6.2 or above. Keep in mind, however, that the maximum file-path in SharePoint is 400 characters.
  2. OneNote notebooks:
    OneNote notebooks will not be migrated unless you have Microsoft Visual C++ 2015 Redistributable installed on the computer that runs the migration and under advanced options specify that you want to migrate OneNote folders.