How to Run SharePoint Migration Tool PowerShell Cmdlets as a Job

When migrating massive file shares or on-premises server data to Microsoft 365, keeping a PowerShell console open and actively monitored is highly inefficient. System administrators need asynchronous execution to free up the terminal and prevent accidental interruptions during long transfers. running SharePoint Migration Tool PowerShell Cmdlets as a Job allows you to execute these heavy workloads in the background, either as parallel tasks in your current session or as scheduled, unattended operations during off-peak hours.

Preparing the Migration Script for Background Execution

Before implementing the techniques for running SharePoint Migration Tool PowerShell Cmdlets as a Job, your base migration script must be fully configured to run without interactive prompts. Background jobs cannot request user input; any prompt for credentials or confirmations will cause the job to hang indefinitely.

First, ensure the SharePoint Migration Tool (SPMT) is installed and the PowerShell module is imported. Your script file must include the authentication block, the task definition, and the execution command. Use the Register-SPMTMigration cmdlet with saved credentials or app-based authentication. Next, define your source and destination using Add-SPMTTask. Finally, include the Start-SPMTMigration cmdlet. Save this complete sequence as a local file, such as C:\Scripts\SPMT_Migration.ps1. Verify that executing this script directly in a standard PowerShell window completes the process without asking you to press any keys or enter passwords.

Executing Asynchronously Using the Start-Job Cmdlet

The standard administrative approach for running SharePoint Migration Tool PowerShell Cmdlets as a Job is utilizing the native Start-Job cmdlet. This method runs your migration in a separate, invisible background runspace, allowing you to continue using your primary PowerShell console for other administrative tasks.

To initiate the migration, open an elevated PowerShell prompt. Use the Start-Job cmdlet combined with the -FilePath parameter pointing to the script you created earlier. Type Start-Job -FilePath "C:\Scripts\SPMT_Migration.ps1" and press Enter. PowerShell will immediately return a job object displaying an ID, Name, and a state of "Running".

Because the migration is running in the background, you will not see the typical SPMT progress bars. To verify the operation, use the Get-Job cmdlet to check if the state remains "Running" or has changed to "Completed" or "Failed". Once the state shows as completed, type Receive-Job -Id [YourJobID] to retrieve the console output and confirm the files were successfully mapped and uploaded to your SharePoint Online environment.

Scheduling Unattended Migrations via Task Scheduler

If your goal for running SharePoint Migration Tool PowerShell Cmdlets as a Job is to schedule the migration for a weekend or late-night window, Windows Task Scheduler is the appropriate mechanism. This ensures the job triggers exactly when network bandwidth is most available, without requiring an administrator to be awake and logged in.

Press the Windows key, type Task Scheduler, and open the application. In the right-hand Actions pane, click Create Basic Task. Name the task "SPMT Nightly Migration" and proceed to the Trigger step to specify your desired date and time. In the Action step, select Start a program. In the "Program/script" field, type powershell.exe. In the "Add arguments" field, you must bypass the default execution policy and point to your script. Enter exactly: -NoProfile -ExecutionPolicy Bypass -File "C:\Scripts\SPMT_Migration.ps1".

On the final summary screen, check the box that says "Open the Properties dialog for this task when I click Finish". In the properties window, select Run whether user is logged on or not and check Run with highest privileges. Click OK and enter your administrator credentials. To verify the setup, right-click the new task in the task library and select Run, then monitor your target SharePoint site to confirm the data begins appearing.

Reviewing Migration Logs and Reports with WPS Office

WPS Office cannot change Microsoft-side settings or directly execute PowerShell modules; the SPMT framework is entirely controlled by Microsoft 365 environments and Windows administration. However, anyone working to run SharePoint Migration Tool PowerShell cmdlets as a job will immediately face a secondary challenge: handling the massive CSV log files and generating stakeholder reports once the automated migration finishes. This is where a realistic WPS Office workflow becomes valuable.

SPMT generates detailed item-level reporting in CSV format, often containing tens of thousands of rows detailing successful transfers and skipped files. You can use WPS Spreadsheet to efficiently audit these results.

• Open WPS Office and launch the Spreadsheet module.
• Navigate to Menu > Open, locate the SPMT log directory (typically under %appdata%\Microsoft\MigrationTool), and select the ItemReport.csv file.
• Use the Data tab and click AutoFilter. Filter the "Status" column to show only "Failed" or "Skipped" items. This instantly isolates the files you need to remediate.
• Once your audit is complete, transition to the Writer module to draft a migration summary for your management team. You can insert the filtered data tables directly into your document to highlight remediation efforts.
• Finally, click Export to PDF in the top toolbar to create a secure, uneditable report that can be distributed to department heads, ensuring everyone knows the data migration phase is complete.

Use Word, Excel, and PPT for FREE

Free Download

Frequently Asked Questions

How do I handle authentication when running the migration in the background?

When running as a background job, interactive browser-based logins will fail. You must configure your SPMT script to use Azure Active Directory (Entra ID) App-Only authentication. This involves creating an application registration in Azure, generating a client secret or certificate, and passing those credentials directly into the Register-SPMTMigration cmdlet parameters within your script.

Where can I find the error logs if my background job fails silently?

If your Get-Job status shows "Failed" but Receive-Job provides no output, the error likely occurred within the SPMT engine itself rather than the PowerShell wrapper. SPMT automatically generates comprehensive logs regardless of how it was launched. Navigate to C:\Users\[YourUsername]\AppData\Roaming\Microsoft\MigrationTool\[TenantName]\[TaskID]\Report. Check the FailureLog.csv or Trace.log files to identify the exact cause of the termination.

Can I run multiple SPMT migration jobs simultaneously?

Yes, but it is limited by your local machine's resources and Microsoft 365 throttling limits. You can use Start-Job to launch multiple distinct `.ps1` scripts, provided each script maps to a different source and destination pair. However, Microsoft recommends using the SPMT agent-based infrastructure if you need high-concurrency, enterprise-scale migrations across multiple servers rather than stacking multiple local background jobs.

Why does my scheduled task say it completed, but no files migrated?

This usually happens due to permission contexts. If Task Scheduler is set to "Run whether user is logged on or not", it executes in a non-interactive session. If your script relies on mapped network drives (e.g., a Z: drive) for the source data, those drives do not exist in the background session. You must update your SPMT script to use absolute UNC paths (e.g., \\ServerName\ShareName) instead of drive letters.