Compare-M365CFVConfigSnapshot.ps1

<#
    .SYNOPSIS
    Compares two M365 voice configuration snapshots and shows what changed.

    .DESCRIPTION
    Author:             Patrik Lleshaj (https://github.com/realgarit)
    Version:            1.0.0
    Changelog:          .\Changelog.md

    Takes two JSON snapshots generated by Invoke-M365CFVConfigAudit.ps1 -SaveSnapshot
    and produces a diff report showing added, removed, and modified Auto Attendants,
    Call Queues, and Resource Accounts.

    .PARAMETER BaselinePath
    Path to the older (baseline) snapshot JSON file.

    .PARAMETER CurrentPath
    Path to the newer (current) snapshot JSON file. If not provided, fetches live data from the tenant.

    .PARAMETER ExportMarkdown
    Export the diff report as a Markdown file.

    .PARAMETER CustomFilePath
    Directory where the report files will be saved.

    .EXAMPLE
    .\Compare-M365CFVConfigSnapshot.ps1 -BaselinePath ".\Output\audit\2026-03-20\ConfigSnapshot_20260320_140000.json" -CurrentPath ".\Output\audit\2026-03-25\ConfigSnapshot_20260325_140000.json"

    .EXAMPLE
    .\Compare-M365CFVConfigSnapshot.ps1 -BaselinePath ".\Output\audit\2026-03-20\ConfigSnapshot_20260320_140000.json" -ExportMarkdown
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)][String]$BaselinePath,
    [Parameter(Mandatory = $false)][String]$CurrentPath,
    [Parameter(Mandatory = $false)][Switch]$ExportMarkdown,
    [Parameter(Mandatory = $false)][String]$CustomFilePath = ".\Output\audit\$(Get-Date -Format 'yyyy-MM-dd')"
)

# ========================================
# LOAD SNAPSHOTS
# ========================================

if (-not (Test-Path -Path $BaselinePath)) {
    Write-Host "Baseline snapshot not found: $BaselinePath" -ForegroundColor Red
    exit
}

Write-Host "Loading baseline snapshot..." -ForegroundColor Cyan
$baseline = Get-Content -Path $BaselinePath -Raw | ConvertFrom-Json

if ($CurrentPath) {
    if (-not (Test-Path -Path $CurrentPath)) {
        Write-Host "Current snapshot not found: $CurrentPath" -ForegroundColor Red
        exit
    }
    Write-Host "Loading current snapshot..." -ForegroundColor Cyan
    $current = Get-Content -Path $CurrentPath -Raw | ConvertFrom-Json
}
else {
    Write-Host "No current snapshot provided. Fetching live data..." -ForegroundColor Cyan

    . .\Functions\Connect-M365CFV.ps1
    . .\Functions\Get-AllVoiceAppsAndResourceAccounts.ps1
    . .\Functions\Format-PhoneNumber.ps1

    . Connect-M365CFV

    $CacheResults = $false
    . Get-AllVoiceAppsAndResourceAccounts

    # Build a live snapshot object matching the saved format
    $current = [PSCustomObject]@{
        Timestamp        = (Get-Date -Format 'o')
        TenantName       = (Get-CsTenant).DisplayName
        TenantId         = (Get-CsTenant).TenantId
        AutoAttendants   = $allAutoAttendants | ForEach-Object {
            [PSCustomObject]@{
                Identity              = $_.Identity
                Name                  = $_.Name
                LanguageId            = $_.LanguageId
                TimeZoneId            = $_.TimeZoneId
                VoiceResponseEnabled  = $_.VoiceResponseEnabled
                VoiceId               = $_.VoiceId
                Operator              = $_.Operator
                DefaultCallFlow       = $_.DefaultCallFlow
                CallFlows             = $_.CallFlows
                Schedules             = $_.Schedules
                CallHandlingAssociations = $_.CallHandlingAssociations
                DialByNameResourceId  = $_.DialByNameResourceId
                DirectoryLookupScope  = $_.DirectoryLookupScope
                ApplicationInstances  = $_.ApplicationInstances
            }
        }
        CallQueues       = $allCallQueues | ForEach-Object {
            [PSCustomObject]@{
                Identity                     = $_.Identity
                Name                         = $_.Name
                RoutingMethod                = $_.RoutingMethod
                PresenceBasedRouting         = $_.PresenceBasedRouting
                ConferenceMode               = $_.ConferenceMode
                AllowOptOut                  = $_.AllowOptOut
                AgentAlertTime               = $_.AgentAlertTime
                LanguageId                   = $_.LanguageId
                OverflowThreshold            = $_.OverflowThreshold
                OverflowAction               = $_.OverflowAction
                OverflowActionTarget         = $_.OverflowActionTarget
                TimeoutThreshold             = $_.TimeoutThreshold
                TimeoutAction                = $_.TimeoutAction
                TimeoutActionTarget          = $_.TimeoutActionTarget
                Agents                       = $_.Agents | ForEach-Object {
                    [PSCustomObject]@{
                        ObjectId = $_.ObjectId
                        OptIn    = $_.OptIn
                    }
                }
                DistributionLists            = $_.DistributionLists
                ChannelId                    = $_.ChannelId
                ApplicationInstances         = $_.ApplicationInstances
                IsCallbackEnabled            = $_.IsCallbackEnabled
                UseDefaultMusicOnHold        = $_.UseDefaultMusicOnHold
                MusicOnHoldAudioFileId       = $_.MusicOnHoldAudioFileId
            }
        }
        ResourceAccounts = $allResourceAccounts | ForEach-Object {
            [PSCustomObject]@{
                ObjectId            = $_.ObjectId
                DisplayName         = $_.DisplayName
                UserPrincipalName   = $_.UserPrincipalName
                ApplicationId       = $_.ApplicationId
                PhoneNumber         = $_.PhoneNumber
            }
        }
    }
}

Write-Host ""
Write-Host "Baseline: $($baseline.TenantName) @ $($baseline.Timestamp)" -ForegroundColor Gray
Write-Host "Current:  $($current.TenantName) @ $($current.Timestamp)" -ForegroundColor Gray

# Verify same tenant
if ($baseline.TenantId -ne $current.TenantId) {
    Write-Host "`nThese snapshots are from different tenants. Can't compare." -ForegroundColor Red
    Write-Host "Baseline: $($baseline.TenantId)" -ForegroundColor Red
    Write-Host "Current:  $($current.TenantId)" -ForegroundColor Red
    exit
}

# ========================================
# DIFF FUNCTIONS
# ========================================

$changes = [System.Collections.ArrayList]::new()

function Add-Change {
    param(
        [string]$ChangeType, # Added, Removed, Modified
        [string]$ResourceType,
        [string]$ResourceName,
        [string]$ResourceId,
        [string]$Details
    )

    [void]$changes.Add([PSCustomObject]@{
        ChangeType   = $ChangeType
        ResourceType = $ResourceType
        ResourceName = $ResourceName
        ResourceId   = $ResourceId
        Details      = $Details
    })
}

function Compare-Properties {
    param(
        [PSCustomObject]$Old,
        [PSCustomObject]$New,
        [string]$ResourceType,
        [string]$ResourceName,
        [string]$ResourceId,
        [string[]]$PropertiesToCompare
    )

    foreach ($prop in $PropertiesToCompare) {
        $oldVal = $Old.$prop
        $newVal = $New.$prop

        # Convert to JSON for deep comparison of complex objects
        $oldJson = ($oldVal | ConvertTo-Json -Depth 10 -Compress) 2>$null
        $newJson = ($newVal | ConvertTo-Json -Depth 10 -Compress) 2>$null

        if ($oldJson -ne $newJson) {
            # Format the values for display
            $oldDisplay = if ($null -eq $oldVal) { "(empty)" } elseif ($oldVal -is [string] -or $oldVal -is [bool] -or $oldVal -is [int]) { "$oldVal" } else { "(complex object)" }
            $newDisplay = if ($null -eq $newVal) { "(empty)" } elseif ($newVal -is [string] -or $newVal -is [bool] -or $newVal -is [int]) { "$newVal" } else { "(complex object)" }

            Add-Change -ChangeType "Modified" -ResourceType $ResourceType `
                -ResourceName $ResourceName -ResourceId $ResourceId `
                -Details "$prop changed: '$oldDisplay' -> '$newDisplay'"
        }
    }
}

# ========================================
# COMPARE AUTO ATTENDANTS
# ========================================

Write-Host "`nComparing Auto Attendants..." -ForegroundColor Cyan

$baselineAAIds = $baseline.AutoAttendants | ForEach-Object { $_.Identity }
$currentAAIds = $current.AutoAttendants | ForEach-Object { $_.Identity }

# Added AAs
foreach ($aa in $current.AutoAttendants) {
    if ($baselineAAIds -notcontains $aa.Identity) {
        Add-Change -ChangeType "Added" -ResourceType "Auto Attendant" `
            -ResourceName $aa.Name -ResourceId $aa.Identity `
            -Details "New Auto Attendant created"
    }
}

# Removed AAs
foreach ($aa in $baseline.AutoAttendants) {
    if ($currentAAIds -notcontains $aa.Identity) {
        Add-Change -ChangeType "Removed" -ResourceType "Auto Attendant" `
            -ResourceName $aa.Name -ResourceId $aa.Identity `
            -Details "Auto Attendant deleted"
    }
}

# Modified AAs
foreach ($currentAA in $current.AutoAttendants) {
    $baselineAA = $baseline.AutoAttendants | Where-Object { $_.Identity -eq $currentAA.Identity }
    if (-not $baselineAA) { continue }

    # Compare simple properties
    Compare-Properties -Old $baselineAA -New $currentAA `
        -ResourceType "Auto Attendant" -ResourceName $currentAA.Name -ResourceId $currentAA.Identity `
        -PropertiesToCompare @("Name", "LanguageId", "TimeZoneId", "VoiceResponseEnabled", "VoiceId", "DirectoryLookupScope")

    # Compare call flows (deep)
    $oldDefaultFlow = $baselineAA.DefaultCallFlow | ConvertTo-Json -Depth 15 -Compress
    $newDefaultFlow = $currentAA.DefaultCallFlow | ConvertTo-Json -Depth 15 -Compress
    if ($oldDefaultFlow -ne $newDefaultFlow) {
        Add-Change -ChangeType "Modified" -ResourceType "Auto Attendant" `
            -ResourceName $currentAA.Name -ResourceId $currentAA.Identity `
            -Details "Default call flow changed (greetings, menu options, or routing)"
    }

    # Compare additional call flows
    $oldCallFlows = $baselineAA.CallFlows | ConvertTo-Json -Depth 15 -Compress
    $newCallFlows = $currentAA.CallFlows | ConvertTo-Json -Depth 15 -Compress
    if ($oldCallFlows -ne $newCallFlows) {
        Add-Change -ChangeType "Modified" -ResourceType "Auto Attendant" `
            -ResourceName $currentAA.Name -ResourceId $currentAA.Identity `
            -Details "After-hours or holiday call flows changed"
    }

    # Compare schedules
    $oldSchedules = $baselineAA.Schedules | ConvertTo-Json -Depth 15 -Compress
    $newSchedules = $currentAA.Schedules | ConvertTo-Json -Depth 15 -Compress
    if ($oldSchedules -ne $newSchedules) {
        Add-Change -ChangeType "Modified" -ResourceType "Auto Attendant" `
            -ResourceName $currentAA.Name -ResourceId $currentAA.Identity `
            -Details "Business hours or holiday schedules changed"
    }

    # Compare call handling associations
    $oldAssoc = $baselineAA.CallHandlingAssociations | ConvertTo-Json -Depth 15 -Compress
    $newAssoc = $currentAA.CallHandlingAssociations | ConvertTo-Json -Depth 15 -Compress
    if ($oldAssoc -ne $newAssoc) {
        Add-Change -ChangeType "Modified" -ResourceType "Auto Attendant" `
            -ResourceName $currentAA.Name -ResourceId $currentAA.Identity `
            -Details "Call handling associations changed (after-hours or holiday mappings)"
    }

    # Compare resource account assignments
    $oldInstances = ($baselineAA.ApplicationInstances | Sort-Object) -join ","
    $newInstances = ($currentAA.ApplicationInstances | Sort-Object) -join ","
    if ($oldInstances -ne $newInstances) {
        Add-Change -ChangeType "Modified" -ResourceType "Auto Attendant" `
            -ResourceName $currentAA.Name -ResourceId $currentAA.Identity `
            -Details "Resource account assignments changed"
    }
}

# ========================================
# COMPARE CALL QUEUES
# ========================================

Write-Host "Comparing Call Queues..." -ForegroundColor Cyan

$baselineCQIds = $baseline.CallQueues | ForEach-Object { $_.Identity }
$currentCQIds = $current.CallQueues | ForEach-Object { $_.Identity }

# Added CQs
foreach ($cq in $current.CallQueues) {
    if ($baselineCQIds -notcontains $cq.Identity) {
        Add-Change -ChangeType "Added" -ResourceType "Call Queue" `
            -ResourceName $cq.Name -ResourceId $cq.Identity `
            -Details "New Call Queue created"
    }
}

# Removed CQs
foreach ($cq in $baseline.CallQueues) {
    if ($currentCQIds -notcontains $cq.Identity) {
        Add-Change -ChangeType "Removed" -ResourceType "Call Queue" `
            -ResourceName $cq.Name -ResourceId $cq.Identity `
            -Details "Call Queue deleted"
    }
}

# Modified CQs
foreach ($currentCQ in $current.CallQueues) {
    $baselineCQ = $baseline.CallQueues | Where-Object { $_.Identity -eq $currentCQ.Identity }
    if (-not $baselineCQ) { continue }

    # Compare simple properties
    Compare-Properties -Old $baselineCQ -New $currentCQ `
        -ResourceType "Call Queue" -ResourceName $currentCQ.Name -ResourceId $currentCQ.Identity `
        -PropertiesToCompare @(
            "Name", "RoutingMethod", "PresenceBasedRouting", "ConferenceMode",
            "AllowOptOut", "AgentAlertTime", "LanguageId",
            "OverflowThreshold", "OverflowAction", "OverflowActionTarget",
            "TimeoutThreshold", "TimeoutAction", "TimeoutActionTarget",
            "IsCallbackEnabled", "UseDefaultMusicOnHold", "MusicOnHoldAudioFileId"
        )

    # Compare agents (normalize to strings for consistent comparison across JSON/live objects)
    $oldAgentList = @($baselineCQ.Agents | Where-Object { $_ -and $_.ObjectId })
    $newAgentList = @($currentCQ.Agents | Where-Object { $_ -and $_.ObjectId })
    $oldAgents = ($oldAgentList | ForEach-Object { "$([string]$_.ObjectId):$([string]$_.OptIn)".ToLower() } | Sort-Object) -join ","
    $newAgents = ($newAgentList | ForEach-Object { "$([string]$_.ObjectId):$([string]$_.OptIn)".ToLower() } | Sort-Object) -join ","
    if ($oldAgents -ne $newAgents) {
        $oldAgentIds = $oldAgentList | ForEach-Object { $_.ObjectId }
        $newAgentIds = $newAgentList | ForEach-Object { $_.ObjectId }

        $addedAgents = $newAgentIds | Where-Object { $oldAgentIds -notcontains $_ }
        $removedAgents = $oldAgentIds | Where-Object { $newAgentIds -notcontains $_ }

        $details = "Agents changed"
        if ($addedAgents.Count -gt 0) { $details += " (+$($addedAgents.Count) added)" }
        if ($removedAgents.Count -gt 0) { $details += " (-$($removedAgents.Count) removed)" }

        # Check for opt-in changes
        $optInChanges = 0
        foreach ($newAgent in $newAgentList) {
            $oldAgent = $oldAgentList | Where-Object { $_.ObjectId -eq $newAgent.ObjectId }
            if ($oldAgent -and $oldAgent.OptIn -ne $newAgent.OptIn) {
                $optInChanges++
            }
        }
        if ($optInChanges -gt 0) { $details += " ($optInChanges opt-in status changes)" }

        Add-Change -ChangeType "Modified" -ResourceType "Call Queue" `
            -ResourceName $currentCQ.Name -ResourceId $currentCQ.Identity `
            -Details $details
    }

    # Compare distribution lists
    $oldDLs = (@($baselineCQ.DistributionLists | Where-Object { $_ }) | Sort-Object) -join ","
    $newDLs = (@($currentCQ.DistributionLists | Where-Object { $_ }) | Sort-Object) -join ","
    if ($oldDLs -ne $newDLs) {
        Add-Change -ChangeType "Modified" -ResourceType "Call Queue" `
            -ResourceName $currentCQ.Name -ResourceId $currentCQ.Identity `
            -Details "Distribution list assignments changed"
    }

    # Compare resource account assignments
    $oldInstances = ($baselineCQ.ApplicationInstances | Sort-Object) -join ","
    $newInstances = ($currentCQ.ApplicationInstances | Sort-Object) -join ","
    if ($oldInstances -ne $newInstances) {
        Add-Change -ChangeType "Modified" -ResourceType "Call Queue" `
            -ResourceName $currentCQ.Name -ResourceId $currentCQ.Identity `
            -Details "Resource account assignments changed"
    }
}

# ========================================
# COMPARE RESOURCE ACCOUNTS
# ========================================

Write-Host "Comparing Resource Accounts..." -ForegroundColor Cyan

$baselineRAIds = $baseline.ResourceAccounts | ForEach-Object { $_.ObjectId }
$currentRAIds = $current.ResourceAccounts | ForEach-Object { $_.ObjectId }

# Added RAs
foreach ($ra in $current.ResourceAccounts) {
    if ($baselineRAIds -notcontains $ra.ObjectId) {
        Add-Change -ChangeType "Added" -ResourceType "Resource Account" `
            -ResourceName "$($ra.DisplayName) ($($ra.UserPrincipalName))" -ResourceId $ra.ObjectId `
            -Details "New Resource Account created"
    }
}

# Removed RAs
foreach ($ra in $baseline.ResourceAccounts) {
    if ($currentRAIds -notcontains $ra.ObjectId) {
        Add-Change -ChangeType "Removed" -ResourceType "Resource Account" `
            -ResourceName "$($ra.DisplayName) ($($ra.UserPrincipalName))" -ResourceId $ra.ObjectId `
            -Details "Resource Account deleted"
    }
}

# Modified RAs
foreach ($currentRA in $current.ResourceAccounts) {
    $baselineRA = $baseline.ResourceAccounts | Where-Object { $_.ObjectId -eq $currentRA.ObjectId }
    if (-not $baselineRA) { continue }

    Compare-Properties -Old $baselineRA -New $currentRA `
        -ResourceType "Resource Account" -ResourceName "$($currentRA.DisplayName) ($($currentRA.UserPrincipalName))" -ResourceId $currentRA.ObjectId `
        -PropertiesToCompare @("DisplayName", "UserPrincipalName", "PhoneNumber", "ApplicationId")
}

# ========================================
# OUTPUT
# ========================================

$addedCount = ($changes | Where-Object { $_.ChangeType -eq "Added" }).Count
$removedCount = ($changes | Where-Object { $_.ChangeType -eq "Removed" }).Count
$modifiedCount = ($changes | Where-Object { $_.ChangeType -eq "Modified" }).Count

Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "  CONFIGURATION DIFF RESULTS" -ForegroundColor Cyan
Write-Host "========================================" -ForegroundColor Cyan
Write-Host ""
Write-Host "  Baseline: $(([datetime]$baseline.Timestamp).ToString('yyyy-MM-dd HH:mm'))"
Write-Host "  Current:  $(([datetime]$current.Timestamp).ToString('yyyy-MM-dd HH:mm'))"
Write-Host ""

if ($addedCount -gt 0) { Write-Host "  ADDED:    $addedCount" -ForegroundColor Green }
else { Write-Host "  ADDED:    0" -ForegroundColor Gray }

if ($removedCount -gt 0) { Write-Host "  REMOVED:  $removedCount" -ForegroundColor Red }
else { Write-Host "  REMOVED:  0" -ForegroundColor Gray }

if ($modifiedCount -gt 0) { Write-Host "  MODIFIED: $modifiedCount" -ForegroundColor Yellow }
else { Write-Host "  MODIFIED: 0" -ForegroundColor Gray }

Write-Host ""
Write-Host "========================================`n" -ForegroundColor Cyan

if ($changes.Count -gt 0) {

    Write-Host "DETAILED CHANGES:" -ForegroundColor Cyan
    Write-Host ""

    foreach ($changeType in @("Added", "Removed", "Modified")) {

        $typeChanges = $changes | Where-Object { $_.ChangeType -eq $changeType }
        if ($typeChanges.Count -eq 0) { continue }

        $changeColor = switch ($changeType) {
            "Added" { "Green" }
            "Removed" { "Red" }
            "Modified" { "Yellow" }
        }

        $changeSymbol = switch ($changeType) {
            "Added" { "+" }
            "Removed" { "-" }
            "Modified" { "~" }
        }

        Write-Host "--- $($changeType.ToUpper()) ---" -ForegroundColor $changeColor

        foreach ($c in $typeChanges) {
            Write-Host "  [$changeSymbol] [$($c.ResourceType)] $($c.ResourceName)" -ForegroundColor $changeColor
            Write-Host "      $($c.Details)"
            Write-Host ""
        }
    }
}
else {
    Write-Host "No changes detected between the two snapshots." -ForegroundColor Green
}

# ========================================
# MARKDOWN EXPORT
# ========================================

if ($ExportMarkdown) {

    if (!(Test-Path -Path $CustomFilePath)) {
        New-Item -Path $CustomFilePath -ItemType Directory | Out-Null
    }

    $mdPath = "$CustomFilePath\ConfigDiff_$(Get-Date -Format 'yyyyMMdd_HHmmss').md"

    $mdContent = @"
# M365 Voice Configuration Diff Report

**Tenant:** $($current.TenantName)
**Baseline:** $(([datetime]$baseline.Timestamp).ToString('yyyy-MM-dd HH:mm'))
**Current:** $(([datetime]$current.Timestamp).ToString('yyyy-MM-dd HH:mm'))

## Summary

| Change Type | Count |
|-------------|-------|
| Added | $addedCount |
| Removed | $removedCount |
| Modified | $modifiedCount |

## Changes

"@

    foreach ($changeType in @("Added", "Removed", "Modified")) {
        $typeChanges = $changes | Where-Object { $_.ChangeType -eq $changeType }
        if ($typeChanges.Count -eq 0) { continue }

        $changeSymbol = switch ($changeType) {
            "Added" { "+" }
            "Removed" { "-" }
            "Modified" { "~" }
        }

        $mdContent += "`n### $changeType ($($typeChanges.Count))`n`n"

        foreach ($c in $typeChanges) {
            $mdContent += "- **[$changeSymbol] [$($c.ResourceType)] $($c.ResourceName)**`n"
            $mdContent += "  - $($c.Details)`n`n"
        }
    }

    if ($changes.Count -eq 0) {
        $mdContent += "No changes detected.`n"
    }

    $mdContent += "`n---`n*Generated by M365 Call Flow Visualizer Config Diff*`n"

    Set-Content -Path $mdPath -Value $mdContent -Encoding UTF8 -Force
    Write-Host "Markdown diff report saved to: $mdPath" -ForegroundColor Green
}