Site Collection Migration Guide¶

# Run SMAT against the entire farm
.\SMAT.exe -SiteURL https://sharepoint.contoso.com -OutputFolder C:\SMAT-Results

# SMAT generates reports for:
# - Checked-out files
# - Customized pages (unghosted)
# - Large lists (> 5,000 items)
# - External BCS connections
# - InfoPath forms
# - Sandbox solutions
# - Custom web parts
# - Locked sites
# - Workflow associations

# On-premises: Get all site collections with key metrics
Add-PSSnapin Microsoft.SharePoint.PowerShell

Get-SPSite -Limit All | ForEach-Object {
    [PSCustomObject]@{
        Url                = $_.Url
        ContentDatabase    = $_.ContentDatabase.Name
        StorageMB          = [math]::Round($_.Usage.Storage / 1MB, 2)
        SiteCount          = $_.AllWebs.Count
        LastModified       = $_.LastContentModifiedDate
        Owner              = $_.Owner.LoginName
        Template           = $_.RootWeb.WebTemplate + "#" + $_.RootWeb.Configuration
        LockState          = $_.WriteLocked
        CompatibilityLevel = $_.CompatibilityLevel
        CustomSolutions    = ($_.Solutions | Measure-Object).Count
    }
} | Export-Csv -Path "C:\Migration\site-inventory.csv" -NoTypeInformation

# Connect to SPO tenant
Connect-PnPOnline -Url https://contoso-admin.sharepoint.com -Interactive

# Create a hub site
$hubSite = New-PnPSite -Type CommunicationSite `
    -Title "Finance Department" `
    -Url "https://contoso.sharepoint.com/sites/finance" `
    -Description "Finance department hub"

Register-PnPHubSite -Site "https://contoso.sharepoint.com/sites/finance"

# Create team sites and associate to hub
$teamSites = @(
    @{ Title = "Finance - Accounts Payable"; Url = "finance-ap" },
    @{ Title = "Finance - Accounts Receivable"; Url = "finance-ar" },
    @{ Title = "Finance - Budget Planning"; Url = "finance-budget" }
)

foreach ($site in $teamSites) {
    New-PnPSite -Type TeamSite `
        -Title $site.Title `
        -Alias $site.Url

    Add-PnPHubSiteAssociation `
        -Site "https://contoso.sharepoint.com/sites/$($site.Url)" `
        -HubSite "https://contoso.sharepoint.com/sites/finance"
}

Import-Module Microsoft.SharePoint.MigrationTool.PowerShell

# Initialize SPMT session
Register-SPMTMigration -SPOUrl "https://contoso.sharepoint.com" `
    -SPOCredential (Get-Credential) `
    -Force

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

# Start migration
Start-SPMTMigration

# Register and run batch migration
Register-SPMTMigration -SPOUrl "https://contoso.sharepoint.com" `
    -SPOCredential (Get-Credential) -Force

Add-SPMTTask -SharePointMigrationSourceCSV "C:\Migration\batch-sites.csv"

Start-SPMTMigration

# Configure SPMT settings before adding tasks
$settings = @{
    MigrateFileVersionHistory    = $true
    KeepAllVersions              = $false
    NumberOfVersionToMigrate     = 10       # Last 10 versions per file
    EnableIncremental            = $true     # Support incremental runs
    PreserveUserPermissionsForDocumentLibrary = $true
    PreserveUserPermissionsForLists = $true
    MigrateHiddenItems           = $true
    MigrateItemsCreatedAfter     = "2020-01-01" # Optional: filter by date
    MigrateItemsModifiedAfter    = "2020-01-01" # Optional: filter by date
    SkipListWithAudienceEnabled  = $false
    FilterOutPathSpecialCharacters = $true
    AzureActiveDirectoryLookup   = $true     # Map on-prem users to Entra
    UserMappingCSVFile           = "C:\Migration\user-mapping.csv"
}

# Find large lists across all site collections
Get-SPSite -Limit All | ForEach-Object {
    $site = $_
    $_.AllWebs | ForEach-Object {
        $web = $_
        $_.Lists | Where-Object { $_.ItemCount -gt 5000 } | ForEach-Object {
            [PSCustomObject]@{
                SiteUrl   = $site.Url
                WebUrl    = $web.Url
                ListTitle = $_.Title
                ItemCount = $_.ItemCount
                SizeMB    = [math]::Round(($_.Items | Measure-Object -Property File.Length -Sum).Sum / 1MB, 2)
                Template  = $_.BaseTemplate
            }
        }
    }
} | Export-Csv -Path "C:\Migration\large-lists.csv" -NoTypeInformation

# Estimate version storage impact for a document library
$web = Get-SPWeb "https://sp2016.contoso.com/sites/finance"
$list = $web.Lists["Shared Documents"]

$versionStats = $list.Items | ForEach-Object {
    $item = $_
    [PSCustomObject]@{
        FileName      = $item.File.Name
        CurrentSizeMB = [math]::Round($item.File.Length / 1MB, 2)
        VersionCount  = $item.File.Versions.Count
        TotalSizeMB   = [math]::Round(
            ($item.File.Length + ($item.File.Versions | Measure-Object -Property Size -Sum).Sum) / 1MB, 2
        )
    }
}

$totalCurrentMB = ($versionStats | Measure-Object -Property CurrentSizeMB -Sum).Sum
$totalWithVersionsMB = ($versionStats | Measure-Object -Property TotalSizeMB -Sum).Sum
$versionOverhead = [math]::Round(($totalWithVersionsMB - $totalCurrentMB) / $totalCurrentMB * 100, 1)

Write-Host "Current size: $totalCurrentMB MB"
Write-Host "With versions: $totalWithVersionsMB MB"
Write-Host "Version overhead: $versionOverhead%"

# Migrate each subsite to a separate SPO site collection
$subsites = @(
    @{
        Source = "https://sp2016.contoso.com/sites/finance/ap"
        Target = "https://contoso.sharepoint.com/sites/finance-ap"
    },
    @{
        Source = "https://sp2016.contoso.com/sites/finance/ar"
        Target = "https://contoso.sharepoint.com/sites/finance-ar"
    }
)

foreach ($subsite in $subsites) {
    Add-SPMTTask `
        -SharePointSourceSiteUrl $subsite.Source `
        -TargetSiteUrl $subsite.Target `
        -MigrateAll
}

# Enable incremental migration in SPMT
Register-SPMTMigration -SPOUrl "https://contoso.sharepoint.com" `
    -SPOCredential (Get-Credential) -Force

# Same task definition as initial run -- SPMT detects incremental
Add-SPMTTask `
    -SharePointSourceSiteUrl "https://sp2016.contoso.com/sites/finance" `
    -TargetSiteUrl "https://contoso.sharepoint.com/sites/finance" `
    -MigrateAll

Start-SPMTMigration
# SPMT will only migrate items changed since the last successful run

# Validate permissions on target site
Connect-PnPOnline -Url "https://contoso.sharepoint.com/sites/finance" -Interactive

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

# Check for broken inheritance
Get-PnPList | ForEach-Object {
    [PSCustomObject]@{
        ListTitle          = $_.Title
        HasUniquePerms     = $_.HasUniqueRoleAssignments
        ItemCount          = $_.ItemCount
    }
} | Where-Object { $_.HasUniquePerms } | Format-Table -AutoSize