Content Matrix 9.12 - File Share Edition User Guide

Running a PowerShell Script

Once a PowerShell script has been created, you can run it from the PowerShell console.

To run the PowerShell script:

NOTES:

· If you have more than one edition of Content Matrix, only one edition can be run per PowerShell session.

·If Content Matrix settings  is changed, in order to apply new settings all PowerShell sessions must be restarted.  

To add the PowerShell cmdlets for the application framework:

1.Open a Powershell ISE or PowerShell console session.

2.Run the Add-PSSnapin command and by pasting in the following text:

if( $PsVersionTable.PSVersion.Major -lt 3 ) { Write-Host "Windows PowerShell Version 3.0 or later needs to be installed in order to run Content Matrix PowerShell scripts."; exit; }if ( (Get-PSSnapin -Name Metalogix.System.Commands -ErrorAction SilentlyContinue) -eq $null ) { add-pssnapin Metalogix.System.Commands | out-null }if ( (Get-PSSnapin -Name Metalogix.File.Commands -ErrorAction SilentlyContinue) -eq $null ) { add-pssnapin Metalogix.File.Commands | out-null }if (Get-Command Set-MetalogixJobPrerequisites -ErrorAction SilentlyContinue){ Set-MetalogixJobPrerequisites -Value "Content Matrix Console - File Share Edition" }

2.Set the directory to the location where the PowerShell script is located.

3.Enter the name and extension of the PowerShell Script (at its specified location), and the script will run.

In the case that you are running a script from the same directory you would use the format: .\[ScriptName].ps1. So if your PowerShell scrip was named "ResourceScript.ps1" then you would enter: .\ResourceScript.ps1 into the window, and the script would run.

If the script is in a different directory, you would enter the location of that directory relative to your current location, followed by the script name. For example, if your prompt is at the "C:\" drive and your PowerShell script, named "ResourceScript.ps1" is on the desktop you would enter: C:\Users\[User]\Desktop\ResourceScript.ps1, and the script would run.

NOTE:  In some cases the Execution Policy may prevent you from running a PowerShell script. In this case you will likely see the message: [Script].ps1 cannot be loaded because the execution of scripts is disabled on this system. Please see "get-help about_signing" for more details. In this case, running the command: set-executionpolicy RemoteSigned should change the existing script policy to allow you to run these scripts for your location. It is advised that you check with your System Administrators before doing this to ensure that no Company Policies are being broken by this action. If this is an action you need to take, you should only need to run this command once.

The migration will begin, and any warnings and/or errors that are encountered in running the script will be displayed in the PowerShell window.

Scheduling a PowerShell Script to Run as a Windows Scheduled Task

Once a PowerShell script has been created, you can run any migration job as a scheduled task on the system that the client application is installed on. This can be any migration action that exists in the Job List section, whether it's a migration job that was saved or a job that was previously run.

The Generate PowerShell Script option saves configurations for the selected job(s) as a PowerShell script. After the script has been saved, you must create a Windows Scheduled task directly in the Windows Task Scheduler.

Once these jobs have been created as scheduled tasks they can no longer be viewed (as scheduled tasks) in Content Matrix.  If you want to make any other modifications or remove the task you can do so directly in the Windows Task Scheduler. If a task has been scheduled, the system will be able to run the task at the appointed time(s), regardless of whether Content Matrix client application is open.

To schedule a PowerShell script to run via the Windows Task Scheduler:

1.On the system where the scheduled task will run, open the Windows Task Scheduler.

2.Choose Actions > Create Task.

3.Enter a task Name and Description.

4.In the General tab, go to Security options and specify the user account that the task should be run under. Change the settings so the task will run regardless of whether the user is logged in.

5.Select the Triggers tab, and click [New] to add a new trigger for the scheduled task. This new task should use the On a schedule option. The start date can be set to a desired time, and the frequency and duration of the task can be set based on your specific needs. Click [OK] when your desired settings are entered.

6.Select the Actions tab and click [New] to set the action for this task to run. Set the Action to Start a program.

7.In the Program/script box enter "PowerShell."

8.In the Add arguments (optional) box enter the value ".\[Your PowerShell Script Name]." For example, if your PowerShell Script is named "Migration1.ps1" then you would enter ".\Migration1.ps1" as the value.

9.In the Start in (optional) box, add the location of the folder that contains your PowerShell script.

NOTE:  The location used in the Start in box will also be used for storing the scheduled task run times, the job history for the copies, and any additional logging that may occur.

10.When all the desired settings are made, click [OK].

11.Set any other desired settings in the Conditions and Settings tabs.

12.Once all the desired actions have been made (or added), click [OK].

The task will be immediately set, and is ready to run.

After the scheduled task has run, a new entry will be added to Content Matrix's Job List section.

Triggering a Job in the Content Matrix Console to Run Using PowerShell

As an alternative to generating a PowerShell script, you can use PowerShell to trigger jobs that have been created in the Content Matrix Console.

To access the PowerShell cmdlets for triggering jobs to run:

Open a PowerShell or PowerShell ISE session and add the PowerShell snap-ins for the application framework.

The following cmdlets for running jobs are now available:

·Get-MLJobs

·Invoke-MLJob

To retrieve information about jobs in the Console:

1.Select (from the PowerShell ISE Command Window) or enter Get-MLJobs.

2.(Optional) Enter one or more of the following parameters if you want to filter jobs:

·JobNameOrTitle

·JobStatus

·Source

·Target

NOTE:  If you do not apply filters, all jobs in the Console will be retrieved.

3.Run the cmdlet.

Example scripts:

Get-MLJobs

To run one or more jobs:

1.Select (from the PowerShell ISE Command Window) or enter Invoke-MLJob.

2.Select or enter additional parameters.  Use the information in the following table for guidance.

3.Run the cmdlet.

Example Scripts

Invoke-MLJob -JobId '92416012-4b69-4d4e-b3c2-984cde279909'

Invoke-MLJob -JobStatus Failed

Run multiple jobs using the PowerShell pipeline variable:

Invoke-MLJob -JobID 'c8176dd1-f1fd-484c-bc66-c002f5406f05' -RunRemotely
'5ca0d97f-4d1d-445f-a6d9-3292abe89a6f', '0a2e0874-a759-46f4-b459-bb98ec2991ad' | Invoke-MLJob '30bf6d71-0a28-4012-b612-2d22562b5b46', '0b094765-46e0-4919-8922-cc5fe841e1f5' | Invoke-MLJob -Quiet

Monitoring and Managing Microsoft 365 Jobs that use the Import Pipeline

For migrations to SharePoint Online that use the Import Pipeline, you can monitor the progress of the job, including Microsoft-side processing, via the Microsoft 365 Migration Jobs window.  This window is available in SharePoint Edition and File Share Edition.

NOTE:  This window is used to monitor Objects and Actions Supported Using the Import Pipeline only.  Any components of a migration that use CSOM can be monitored via Log Item Details.

To launch the Microsoft 365 Migration Jobs window:

1.In the Job List, select the migration job you want to monitor/manage.

2.Right-click and choose Manage Microsoft 365 Jobs.  

NOTE:  This option is available only if the Use Import Pipeline option was selected on the Configure Copy Options - List Content tab, and the window can be open for only one job at a time.

Status Messages

The following are the status messages that display in the Microsoft 365 Migration Jobs window.  

NOTE:  By default, every run of each batch displays in this window. If you want to show only the latest status of each batch, check the Hide previous batch runs box.

·Processing - Content Matrix is preparing batches for upload to the Import Pipeline.

·Queued - The batch is awaiting upload to the Import Pipeline.

·Running - The batch has been uploaded to the Import Pipeline and is being processed by Microsoft.

·Success - The batch has been processed successfully.

·Warning - The batch has been processed with one or more issues.

·Failed - Microsoft-side batch processing has failed.

To view batch details:

1.Select the batch whose details you want to view.

2.In the ribbon menu, click View Job.

NOTE:  The identifying URIs (Manifest, Blob Storage, and Azure Queue) are generated by Microsoft and can be used by Support for troubleshooting purposes.

While the job is running, you can view the progress in the Logs section of the window.  

EXCEPTION:  The progress of a running job cannot be viewed if it was configured using PowerShell.

Once the job has finished processing (or if the job was configured using PowerShell), the [Download Job Log] button becomes enabled, and you can view complete job details.

Job List Upload Duration Column

The column Upload Duration in the Job List displays the time it took for the job to upload via the Import Pipeline.  If the migration was done with CSOM only, or the target was SharePoint on premises, the field will be blank.

Retrying Failed Batches

Content Matrix automatically retries a failed batch up to five times by default.  (This can be changed via the EnvironmentSettings.xml MaxAzureBatchRetryCount key.)  You can also manually retry batches directly from the Microsoft 365 Migration Jobs  window. Highlight each batch you want to retry and click Retry Job in the ribbon menu.

TIP:  You can filter the Status column to display only failed batches.  

Stopping Batches

You can stop any queued or running batch.

NOTE: Stopping multiple jobs at once is not supported. To stop multiple jobs, open each job individually and complete the steps below.

To stop a batch:

1.In the job list, select the migration job that includes the batch you want to stop.

2.Right-click and select Manage Microsoft 365 Jobs.

3.In the Manage Microsoft 365 Jobs window, select the relevant queued or running batch.

4.In the ribbon menu, click Stop Job.

5.In the pop-up asking you to confirm you want to stop the job, select Yes.

NOTE: After the confirmation, Content Matrix sends a stop request to Azure to stop the job. Azure processes the request based on its queue and priority. Since Azure controls this process, if the stop request is not prioritized, the batch may continue running or even complete.

The status of the batch will change from Running to Cancelled.

NOTE: A cancelled job can be retried only after the current Content Matrix migration process is fully complete.

Note About Expired Azure SAS URLs

You can retry job batches any time before the Azure SAS URL for the job expires (which is 30 days for private containers and a number of days determined by Microsoft for SharePoint Online provided Azure containers).  If you want to resubmit a job after this time period, you will need to re-create the migration job.

Creating an API Support Zip File to Send to Quest Support for Troubleshooting

To assist Quest Support with troubleshooting, you can generate a zip file, which includes several xml files, a log file and a Summary file, for all batches that used the Import Pipeline.

NOTE:  A standard Support zip file includes the same content, but only for batches with a status of Failed or Warning so that Quest Support may provide more efficient troubleshooting.

1.Select the batches for which you want to create the zip file. Note that you can multi-select to create a separate zip file for each batch.

2.In the ribbon menu, click API Support Zip.

3.Save the zip files and send them to Quest Support for troubleshooting.

By default, a zip file's name is its SPO Job ID. You can, however, rename it.

NOTE:  If the Azure SAS URL has expired, only the log file and Summary file will be included in the zip file. (A full API Support zip file may be generated between the time that the Azure SAS URL expires and Microsoft destroys a container.)