Chat now with support
Chat with Support

Metalogix Content Matrix 8.9 - SharePoint Edition User Guide

Introduction Entering the License Key Content Matrix Console End User Interface Enabling Advanced Mode Connecting to SharePoint Migrating to O365 Using the Azure Pipeline/SPO Containers Preparing for a Migration How Content Matrix Handles Various SharePoint Components Initiating a Migration Configuring Copying Options Saving or Running a Migration Action Copying SharePoint Objects as a Separate Action Self-Service Migration Incremental Migration Log Files Using PowerShell with Content Matrix
Configuring PowerShell for Use with Content Matrix
Registering Metalogix Command DLL Files Adding PowerShell Snap-Ins for the Application Framework Content Matrix PowerShell Commandlet List
Metalogix.System.Commands Metalogix.SharePoint.Commands Metalogix.Jobs.Reporting.Commands Metalogix.SharePoint.Migration.Commands
Modifying Content Matrix Configuration and Settings Configuring Content Matrix for Distributed and Self-Service Migration Frequently Asked Questions
DB_Owner Permission Migrating with the Fabulous 40 Templates Item Count Discrepancies Keyboard Shortcuts License Key Troubleshooting Determining the Status of a Migration Running in the Background MySite and User Profile Migration Issues Optimal Setup for Best Performance Using Proxies, Load Balancing or Alternate Access Mappings Troubleshooting the Extensions Web Service Installing the Extensions Web Service on Specific Systems Extensions Web Service Installation Files Using Older Versions of the Extensions Web Service Preserving IDs when Migrating a Custom List as a Folder Migrating JavaScript Migrating Site Variations Migrating with SharePoint Document IDs Changing a Job Configuration for Multiple Files SharePoint 2003 Version Migration Limitations SharePoint 2013 and Later Site Collection Creation Issue Job List Database fails to Load After Upgrade Customized Wiki Page Web Part Zones Not Being Migrated Preserving SharePoint List Item IDs with a CSOM Connection Type Retrying Failed Document Copies to O365 CSOM Connections Migrating Content When the Source Custom List Template is Missing Are SharePoint Online Migrations Throttled? What to Expect when Migrating with StoragePoint on the Target Migration Error Message 'There was an Error Reading from the Pipe: The Pipe has been Ended (109, 0xd6)' How do I Remove Items from My Azure Blob Storage Account? Azure Batches Getting Stuck "Error, the batch will be resubmitted" Message Displays When Using Azure Item Count at Target is Increased When Migrating Using the Azure Pipeline Custom Lists with Versioning Enabled Not Being Migrated When Using the Azure Pipeline Supported Nintex Actions for SPO Migration "Insufficient Credentials" Message Connecting to Modern Team Site Using Web Browser Authentication Error Making a Browser-Based Connection with PowerShell Console Open
About Us

Distributed and Self-Service Migration Components

Distributed Migration and Self-Service Migration rely on the following three components:

Controller (or Host)

This is the primary Metalogix Content Matrix Console that manages agents and workstations, the Distributed Database, and the migration jobs.  Distributed Migration and Self-Service Migration are configured to share the same Controller.

Distributed Database

This is a SQL Server database that contains the repository or queue of migration job definitions which the agents and/or workstations can execute. As with the Controller, Distributed Migration and Self-Service Migration configurations share the same Distributed Database.

NOTE:  The Distributed Database cannot be a SQL CE database.

Agents and Workstations

Agents are physical or virtual machines remote from the Controller machine used to handle Distributed Migration workload, while workstations are end-user machines from which Self-Service Migrations are run.

Once connected, the Controller will push an installation of the Metalogix Content Matrix Console onto the agent machine or workstation  For Distributed Migration, the agent is then configured to execute the migration jobs that are sent from the Controller. For Self-Service Migration, the workstation is configured with a simplified set of options to allow end users to run migration jobs remotely.   That is, Self-Service Migration jobs are run from the workstation, but the actual job is run on either:

·agent machines (if Distributed Migration is also configured and agents are available)


·the Controller machine (if Distributed Migration is not configured or agents are not available).

Any logging information would then be sent to the Distributed Database.

When an agent or workstation is executing a migration job, any interaction with the agent or workstation, such as changing a configuration setting, is not recommended.

Distributed and Self-Service Migration System Requirements

Requirements for the Controller (Host) machine

·Metalogix Content Matrix Console must be installed and set up on the Controller machine. For details on this, please see the Metalogix Content Matrix Console Advanced Installation Guide.  

·The account used to connect from the Controller to agent machines and workstations requires Local Administrator permissions on both the Controller machine and all of the agent machines and workstations.

·An X.509 Certificate must be created for the Controller.  This certificate will be stored in the Distributed Database for use by agent machines and workstations. You do not need to create multiple X.509 certificate files. For more information about creating an X.509 certificate, please see Creating an X.509 Security Certificate for Distributed and Self-Service Migration. For more information about installing an X.509 certificate, please see Installing an X.509 Security Certificate for Remote Agents and Workstations.

·The default Metabase settings for Metalogix Content Matrix must be reconfigured to use SQL Server and not a SQL CE database. For more information about configuring the Metabase settings, see Configuring Metabase Settings.

·The Controller Console must remain open during job execution.

Requirements for the Distributed Database

·The Distributed Database must use SQL Server 2008 or later.

·The Distributed Database can reside on the Controller machine or any other machine in network, provided that the Controller and all agents/workstations have access to that machine.

·The Distributed Database should be created from the Metalogix Content Matrix Console.

NOTE: It is recommended that SQL Server Authentication be used to connect to the Distributed Database, as it will allow for cross-domain connections. It will also allow Self-Service users to connect to the Distributed Database without requiring additional explicit permissions.

Requirements for an Agent Machine/Workstation

·An agent machine or workstation should have 1 GB of free RAM, plus double the size of the largest file being migrated in free RAM.

NOTE:  An agent machine or workstation can be a physical or virtual machine.

·The operating system can be Windows 7, 8, 8.1, 10 or Microsoft Windows Server 2008 R2 or later.

·Microsoft .NET Framework 4.6 or higher must be installed on the machine.

·The agent machine or workstation must meet all the prerequisites as specified in the Metalogix Content Matrix Console Advanced Installation Guide.

·The requirements for non-admin user accounts connecting to the Distributed Database from a Self-Service workstation depends on the authentication used:

§If Windows Authentication will be used, any non-admin user account connecting from the  workstation requires db_datareader and db_datawriter permissions for the Distributed Database. These permissions need to be given to each non-admin user account that will be using the Self-Service workstation.

§If SQL Authentication will be used, no additional explicit permissions are required for any non-admin users connecting from the workstation.

·The machine must allow remote connections to itself.

NOTE: It is recommended that the agent or workstation be in the same network as the Controller.

·All instances of Windows PowerShell must be closed.

·An X.509 Security certificate must be created for use by all agents and workstations. For more information about creating and installing an X.509 Security certificate, please see Installing an X.509 Security Certificate for Remote Agents and Workstations.

·The following services must be started:

§Remote Registry

§Server Service

§Workstation Service

Also note that when connecting to an agent machine or workstation the Controller will try to install a copy of Metalogix Content Matrix Console on that machine. In order to do this Metalogix Content Matrix (on the Controller machine) will look at the following folder location (local to itself) "C:\ProgramData\Metalogix" to see if a copy of the install file is present. It will look for the installer file using the naming convention: Metalogix_Content_Matrix_Console_Setup_[version].exe. If the file is found, then the installer will be copied to the machine and deployed. If the file is NOT found, then Metalogix Content Matrix will try to copy the installer from the Quest website, rename the download when it completes, then copy that file to the machine.

Using Wizards to Set Up Distributed and Self-Service Migration

You can set up Distributed Migration and/or Self-Service Migration via the Metalogix Content Matrix Console using a wizard designed to help streamline the process of setting up both the Controller and individual agents or workstations.

Alternatively, you can set up Distributed and Self-Service Migration manually.

Before setting up Distributed or Self Service Migration:

Make sure your Controller (Host) machine, Distributed Database, and agent machines/workstations meet Distributed and Self-Service Migration System Requirements.

To use the Distributed Migration or Self-Service Migration Wizard:

1.Use the information in the following table to determine the appropriate action to take.

If you are setting up ....

Then ...

Distributed Migration

from the ribbon, choose Connection > Configure Distributed Migration.

Configure Distributed Migration Ribbon Option

Self-Service Migration

from the ribbon, choose Connection > Configure Self-Service.

Configure Self-Service Migration Ribbon Option

NOTE:  If your Metalogix Content Matrix license does not include Self-Service Migration functionality, Self-Service options will be disabled.

Self Service Options Disabled

The remaining steps are the same for both Distributed and Self-Service Migration.


§You will be prompted to configure agents for Distributed Migration and workstations for Self-Service Migration.

§Since they share the same Controller, Distributed database and Metabase (which is used to store metadata during migration), if you are setting up both Distributed and Self Service Migration, you will only be prompted to configure these components for the first set up.  For the other, you will  be prompted to configure agents or workstations only.

Distributed Migration Wizards Both

NOTE:  If you configured Distributed Migration prior to version 8.7 and are now configuring Self-Service Migration, the existing Agent database will be used.

2.Click [Next>].

3.If you are configuring Distributed or Self-Service migration for the first time, read and accept the terms of the third-party License Agreement, then click [Next>].

4.To Provision Distributed Database, either:

§Enter the address of the SQL server where the database is located


§Use the [Browse] button by the SQL Server field to browse for servers on the local system and on the network, then click [OK] to return to the Provision Distributed Database dialog.

SQL Server BrowserCONTEN~1_img193Provision

5.Enter the name of an existing SQL database in the SQL Database field, or click [Browse] to view the databases located on the chosen SQL server. To create a new database, select [New Database] in the Browse window, and enter a name for it.

Provision Distribution DB CREATE

6.If specific authentication credentials are required in order to log in to the SQL server, enter them in the appropriate fields.

NOTE:  If any agents and/or workstations are in a different domain than the Controller, be sure to use SQL Server Authentication to allow all agents and workstations to access the database.  

7.Click [Next>].

8.To Configure Metabase, choose a SQL server and database to use for the Metabase database (which is used by Metalogix Content Matrix to store metadata during the migration process) just as you chose a server and Distributed Database in the previous steps.

NOTE:  As with the Distributed Database, if any agents and/or workstations are in a different domain than the Controller, be sure to use SQL Server Authentication.

Distributed Migration SP_FS Metabase

9.If specific authentication credentials are required in order to log in to the SQL server, enter them in the appropriate fields. Then click [Next>].

The Wizard will now enable you to copy application, environment, and user mapping settings files from the Controller machine to the Distributed Database to be used in place of the default settings on the agent machines or workstations. Please see the Updating an Agent or Workstation for more details.

Distributed Migration SP_FS Mappings

10.Select Copy Settings to copy UserSettings.xml, EnvironmentSettings.xml, and ApplicationSettings.xml from the local system to the Distributed Database.

A confirmation displays after the settings have been successfully copied.

NOTE:  After these settings have been copied to the Distributed Database and the Console has been restarted, Metalogix Content Matrix will no longer look in local settings files for configuration information. This means that changing local settings files will have no effect on the Console's operations.

If changes need to be made to settings after copying them over to the Distributed Database, make the necessary changes to configuration files on the local system, and then copy those files over to the Distributed Database using the Wizard.

11.Click [Next>].

12.For Create Certificate, select an existing certificate to use, or create a new one via the [Generate New Certificate] button.

Distributed Migration Create Certificate

When creating a new certificate, make sure to use a certificate name that does not contain any spaces. Also use a robust password that you will remember, and export the certificate to a folder where it can be found again in the future.

NOTE:  Metalogix Content Matrix utilizes security certificates in Distributed and Self-Service migrations to maintain secure communication between the Controller and agent machines/workstations. This certificate will automatically be used for the Controller machine where the Wizard is currently running from, whether or not it was generated now or at a previous time.  Please see Installing an X.509 Certificate for Use with Remote Agents and Workstations for more details.  

13.Click [Next>].

14.For Download Installer, select [Download Installer] to download a new copy of the installer to that system.

Please see Distributed and Self-Service Migration System Requirements for more details.

Distributed Migration SP_FS Download Installer

An indicator will appear at the bottom of the Wizard indicating that the download is in progress. Click [Next>] when the button becomes available after the download operation has completed.

15.For Configure Agents or Configure Workstations, enter the Name of the agent or workstation computer to find it by name, or select [Browse...] to browse for it in the network. The IP address of the system can also be used to locate and connect to it.

REMINDER:  It is recommended that the agent or workstation be on the same network as the Controller.

Distributed Migration SP_FS Configure Agent

NOTE:  Make sure to enter the correct user name and password for the system before proceeding.

16.Click [Next>].

Distributed Migration SP_FS Prerequisites

NOTE:  If the Wizard finds that any of the services are not running, click [Enable Missing Services] to have the Wizard attempt to enable those services remotely.

Windows Server 2008 R2 or later is the recommended minimum Operating System to be used for agent machines an workstations. If a machine does not meet this requirement, the Wizard will throw a warning message, but it will allow you to proceed so long as the above services are available.

17.When all services are enabled and you are ready to proceed, click [Next >].

18.For Deploy Certificate, click [Deploy Certificate] to deploy the certificate configured above to the agent or workstation.

Distributed Migration SP_FS Deploy Certificate

A confirmation message displays, confirming successful deployment.

19.Click [Next>].

20.For Install Agent or Install Workstation, select [Deploy Metalogix Content Matrix] to begin the deployment procedure. An indicator displays at the bottom of the Wizard indicating that the deployment is in progress.

Distributed Migration SP_FS Install Agent

The Summary windows shows the configuration options that have been selected for deployment, and the status of the deployment to the specified agent or workstation.

Distributed Migration SP_FS Summary

20.To add additional agents or workstations, click [Deploy New]. The Wizard will then return to the Configure Agents or Configure Workstations screen where the last step can be repeated for the additional agent or workstation.

21.Click [Finish] at the bottom of the Summary screen to close the Wizard.

22.Close the Console and start it up again to make use of the new settings.

Setting Up Distributed and Self-Service Migration Manually

(Alternatively, you can use the Wizard to set up Distributed or Self-Service Migration.)

Before setting up Distributed or Self-Service Migration:

Make sure your Controller (Host) machine, Distributed Database, and agent machines or workstations machines meet Distributed Migration and Self-Service System Requirements.

Manual Distributed or Self-Service Migration Setup Tasks

To manually set up Distributed or Self-Service Migration, you must perform the following tasks:

A.Install X.509 Certificates for use with remote agents and workstations.

B.Open the Metalogix Content Matrix Console application on your Controller (Host) machine, and perform the following:

§Create/Connect to the Distributed Database.

§Add Agents or Workstations.

Related Documents