Tutorial: SharePoint Migration with SPMT¶

# Download SPMT from Microsoft
# https://aka.ms/spmt-ga-page
# Or install via winget:
winget install Microsoft.SharePointMigrationTool

# Install the SPMT PowerShell module for scripted migrations
Install-Module -Name Microsoft.SharePoint.MigrationTool.PowerShell -Scope CurrentUser

# Verify installation
Get-Module -Name Microsoft.SharePoint.MigrationTool.PowerShell -ListAvailable

Import-Module Microsoft.SharePoint.MigrationTool.PowerShell

# Initialize SPMT session
$spoCredential = Get-Credential -Message "Enter M365 admin credentials"

Register-SPMTMigration `
    -SPOUrl "https://contoso.sharepoint.com" `
    -SPOCredential $spoCredential `
    -Force

# Configure migration settings
$globalSettings = @{
    MigrateFileVersionHistory                    = $true
    KeepAllVersions                              = $false
    NumberOfVersionToMigrate                     = 10
    EnableIncremental                            = $true
    PreserveUserPermissionsForDocumentLibrary     = $true
    PreserveUserPermissionsForLists               = $true
    MigrateHiddenItems                           = $true
    AzureActiveDirectoryLookup                   = $true
    UserMappingCSVFile                           = "C:\Migration\user-mapping.csv"
    FilterOutPathSpecialCharacters               = $true
    MigrateOneNoteNotebook                       = $true
    SkipListWithAudienceEnabled                  = $false
    CustomAzureAccessKey                         = ""  # Use default Azure storage
    CustomAzureStorageAccount                    = ""  # Use default Azure storage
}

# Add a migration task (scan only)
Add-SPMTTask `
    -SharePointSourceSiteUrl "https://sp2016.contoso.com/sites/finance" `
    -TargetSiteUrl "https://contoso.sharepoint.com/sites/finance" `
    -MigrateAll

# Review scan results before starting migration
# SPMT displays warnings and blockers in the task list

# SMAT provides more detailed assessment than SPMT pre-scan
# Download from https://www.microsoft.com/download/details.aspx?id=53598

.\SMAT.exe -SiteURL https://sp2016.contoso.com `
    -OutputFolder C:\SMAT-Results `
    -Verbose

# Review reports in C:\SMAT-Results\
# Key reports:
# - ScanSummary.csv -- overview of all findings
# - LargeListFiles.csv -- lists exceeding thresholds
# - CheckedOutFiles.csv -- files checked out by users
# - CustomizedFiles.csv -- unghosted (customized) pages
# - WorkflowAssociations2010.csv -- SP 2010 workflow inventory
# - WorkflowAssociations2013.csv -- SP 2013 workflow inventory
# - InfoPathForms.csv -- InfoPath form inventory
# - SandboxSolutions.csv -- sandbox solution inventory

# Single site migration
Add-SPMTTask `
    -SharePointSourceSiteUrl "https://sp2016.contoso.com/sites/finance" `
    -TargetSiteUrl "https://contoso.sharepoint.com/sites/finance" `
    -MigrateAll

# Start migration
Start-SPMTMigration

# Monitor progress
# SPMT writes logs to %APPDATA%\Microsoft\MigrationTool\Logs\

# Define multiple migration tasks
$tasks = @(
    @{
        Source = "https://sp2016.contoso.com/sites/finance"
        Target = "https://contoso.sharepoint.com/sites/finance"
    },
    @{
        Source = "https://sp2016.contoso.com/sites/hr"
        Target = "https://contoso.sharepoint.com/sites/hr"
    },
    @{
        Source = "https://sp2016.contoso.com/sites/legal"
        Target = "https://contoso.sharepoint.com/sites/legal"
    },
    @{
        Source = "https://sp2016.contoso.com/sites/marketing"
        Target = "https://contoso.sharepoint.com/sites/marketing"
    }
)

foreach ($task in $tasks) {
    Add-SPMTTask `
        -SharePointSourceSiteUrl $task.Source `
        -TargetSiteUrl $task.Target `
        -MigrateAll
    Write-Host "Added task: $($task.Source) -> $($task.Target)"
}

# Start all tasks
Start-SPMTMigration
Write-Host "Migration started. Monitor progress in SPMT GUI or log files."

# Migrate specific document libraries only
Add-SPMTTask `
    -SharePointSourceSiteUrl "https://sp2016.contoso.com/sites/finance" `
    -SharePointSourceDocumentLibraryName "Shared Documents" `
    -TargetSiteUrl "https://contoso.sharepoint.com/sites/finance" `
    -TargetDocumentLibraryName "Shared Documents"

Add-SPMTTask `
    -SharePointSourceSiteUrl "https://sp2016.contoso.com/sites/finance" `
    -SharePointSourceDocumentLibraryName "Policies" `
    -TargetSiteUrl "https://contoso.sharepoint.com/sites/finance" `
    -TargetDocumentLibraryName "Policies"

Start-SPMTMigration

# SPMT log location
$logPath = "$env:APPDATA\Microsoft\MigrationTool\Logs"

# Key log files:
# - StatusReport.csv -- Overall migration status per task
# - ItemReport.csv -- Per-item migration status
# - ScanReport.csv -- Pre-scan findings
# - FailureReport.csv -- Failed items with error details
# - WarningReport.csv -- Items migrated with warnings

# Review failures
$failures = Import-Csv "$logPath\<session>\FailureReport.csv"
$failures | Group-Object -Property ErrorMessage | Sort-Object Count -Descending |
    Select-Object Count, Name | Format-Table -AutoSize

# Connect to target SPO site
Connect-PnPOnline -Url "https://contoso.sharepoint.com/sites/finance" -Interactive

# Compare document counts
$targetLibraries = Get-PnPList | Where-Object {
    $_.BaseType -eq "DocumentLibrary" -and -not $_.Hidden
}

$targetLibraries | ForEach-Object {
    [PSCustomObject]@{
        Library   = $_.Title
        ItemCount = $_.ItemCount
        SizeMB    = [math]::Round($_.ParentWeb.Usage.Storage / 1MB, 2)
    }
} | Format-Table -AutoSize

# Spot-check specific documents
$testDoc = Get-PnPFile -Url "/sites/finance/Shared Documents/Budget2026.xlsx" -AsListItem
Write-Host "Title: $($testDoc['FileLeafRef'])"
Write-Host "Created: $($testDoc['Created'])"
Write-Host "Modified: $($testDoc['Modified'])"
Write-Host "Created By: $($testDoc['Author'].Email)"
Write-Host "Modified By: $($testDoc['Editor'].Email)"

# Verify site permissions
Get-PnPSiteGroup | ForEach-Object {
    [PSCustomObject]@{
        Group    = $_.Title
        Members  = $_.Users.Count
        Roles    = ($_.Roles | Select-Object -ExpandProperty Name) -join ", "
    }
} | Format-Table -AutoSize

# Verify site collection administrators
Get-PnPSiteCollectionAdmin | Select-Object Title, Email | Format-Table -AutoSize

# Re-run migration to capture failed items and new changes
# SPMT automatically runs incrementally -- only processes changed/failed items

Register-SPMTMigration `
    -SPOUrl "https://contoso.sharepoint.com" `
    -SPOCredential $spoCredential `
    -Force

Add-SPMTTask `
    -SharePointSourceSiteUrl "https://sp2016.contoso.com/sites/finance" `
    -TargetSiteUrl "https://contoso.sharepoint.com/sites/finance" `
    -MigrateAll

Start-SPMTMigration
# Only failed/changed items will be processed

# Use PnP PowerShell to convert classic pages to modern
Connect-PnPOnline -Url "https://contoso.sharepoint.com/sites/finance" -Interactive

# Convert a single page
ConvertTo-PnPPage -Identity "Home.aspx" -Overwrite

# Convert all pages in a site
$pages = Get-PnPListItem -List "Site Pages" |
    Where-Object { $_["ContentType"].Name -ne "Site Page" }

foreach ($page in $pages) {
    try {
        ConvertTo-PnPPage -Identity $page["FileLeafRef"] -Overwrite
        Write-Host "Converted: $($page['FileLeafRef'])" -ForegroundColor Green
    } catch {
        Write-Warning "Failed to convert: $($page['FileLeafRef']) - $($_.Exception.Message)"
    }
}

# Add URL redirect from old site to new site
# Option 1: IIS URL Rewrite on on-premises web servers
# Option 2: DNS redirect
# Option 3: SharePoint redirect page

# Create a redirect page on the old site
$oldWeb = Get-SPWeb "https://sp2016.contoso.com/sites/finance"
$oldWeb.AllProperties["__RedirectUrl__"] = "https://contoso.sharepoint.com/sites/finance"
$oldWeb.Update()

# Lock the source site collection after migration is validated
Set-SPSite -Identity "https://sp2016.contoso.com/sites/finance" -LockState ReadOnly