Collect Device Diagnostics

<#
.TITLE
    Collect Device Diagnostics

.SYNOPSIS
    Triggers remote diagnostics collection on Windows devices and downloads the resulting log packages.

.DESCRIPTION
    This script starts the Intune "Collect diagnostics" remote action on one or more
    Windows devices (by device name or Entra ID group), waits for the collection to
    complete, and downloads the resulting diagnostic ZIP packages to a local folder.
    It can also list and download previously completed collection requests without
    triggering a new one. This replaces clicking through the portal for every device
    when troubleshooting at scale.

.TAGS
    Diagnostics,Devices

.MINROLE
    Intune Administrator

.PERMISSIONS
    DeviceManagementManagedDevices.ReadWrite.All,GroupMember.Read.All

.EXECUTION
    LocalOnly

.AUTHOR
    Ugur Koc

.VERSION
    1.2

.CHANGELOG
    1.2 - Added Azure Automation contract validation, portal-safe boolean parameters, beta Graph endpoints, and terminating paging errors
    1.1 - Azure Automation now records script progress, outcomes, and summaries in job history
    1.0 - Initial release

.LASTUPDATE
    2026-07-30

.EXAMPLE
    .\collect-device-diagnostics.ps1 -DeviceNames "PC-001","PC-002"
    Triggers diagnostics collection on two devices and downloads the packages when ready

.EXAMPLE
    .\collect-device-diagnostics.ps1 -GroupName "Support - Troubleshooting" -OutputPath "C:\DeviceLogs"
    Collects diagnostics from all Windows devices in the group and saves packages to C:\DeviceLogs

.EXAMPLE
    .\collect-device-diagnostics.ps1 -DeviceNames "PC-001" -DownloadExisting "true"
    Skips triggering a new collection and downloads the most recent completed package instead

.NOTES
    - Requires Microsoft.Graph.Authentication module
    - Collect diagnostics is only supported on Windows 10/11 devices; other platforms are skipped
    - The device must be online to receive the action; collection typically completes within minutes but the script stops waiting after -TimeoutMinutes
    - Listing and creating log collection requests requires DeviceManagementManagedDevices.ReadWrite.All (Graph rejects read-only scopes for this surface)
    - Uses beta Graph endpoints for the log collection surface
    - Local interactive sign-in uses the MgGraphCommunity module to avoid the Graph SDK's mandatory WAM broker on Windows
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory = $false, HelpMessage = "Device names to collect diagnostics from")]
    [ValidateNotNullOrEmpty()]
    [string[]]$DeviceNames,

    [Parameter(Mandatory = $false, HelpMessage = "Entra ID group whose Windows devices get diagnostics collected")]
    [ValidateNotNullOrEmpty()]
    [string]$GroupName,

    [Parameter(Mandatory = $false, HelpMessage = "Folder where diagnostic packages are saved")]
    [string]$OutputPath = ".",

    [Parameter(Mandatory = $false, HelpMessage = "Download the latest existing completed package instead of triggering a new collection")]
    [ValidateSet("true", "false", "1", "0", '$true', '$false')]
    [string]$DownloadExisting,

    [Parameter(Mandatory = $false, HelpMessage = "Minutes to wait for collections to complete")]
    [ValidateRange(1, 120)]
    [int]$TimeoutMinutes = 15,

    [Parameter(Mandatory = $false, HelpMessage = "Force module installation without prompting")]
    [ValidateSet("true", "false", "1", "0", '$true', '$false')]
    [string]$ForceModuleInstall
)

# Normalize the local module-install override for Azure Automation parameter binding.
$forceModuleInstallRaw = [string]$ForceModuleInstall
Remove-Variable -Name ForceModuleInstall
if ([string]::IsNullOrWhiteSpace($forceModuleInstallRaw)) {
    $ForceModuleInstall = $false
}
elseif ($forceModuleInstallRaw.Trim().ToLowerInvariant() -in @("true", "1", '$true')) {
    $ForceModuleInstall = $true
}
elseif ($forceModuleInstallRaw.Trim().ToLowerInvariant() -in @("false", "0", '$false')) {
    $ForceModuleInstall = $false
}
else {
    throw "Parameter 'ForceModuleInstall' accepts only true, false, 1, 0, $true, or $false."
}

# Azure Automation supplies portal parameter values as strings. Normalize the
# public boolean parameters once so local and runbook execution use real booleans.
foreach ($runbookBooleanParameter in @('DownloadExisting')) {
    $runbookBooleanRaw = [string](Get-Variable -Name $runbookBooleanParameter -ValueOnly)
    Remove-Variable -Name $runbookBooleanParameter

    if ([string]::IsNullOrWhiteSpace($runbookBooleanRaw)) {
        Set-Variable -Name $runbookBooleanParameter -Value $false
        continue
    }

    switch ($runbookBooleanRaw.Trim().ToLowerInvariant()) {
        { $_ -in @("true", "1", '$true') } {
            Set-Variable -Name $runbookBooleanParameter -Value $true
        }
        { $_ -in @("false", "0", '$false') } {
            Set-Variable -Name $runbookBooleanParameter -Value $false
        }
        default {
            throw "Parameter '$runbookBooleanParameter' accepts only true, false, 1, 0, $true, or $false."
        }
    }
}

$selectedTargets = @(
    if (@($DeviceNames).Count -gt 0) { 'ByDevice' }
    if (-not [string]::IsNullOrWhiteSpace($GroupName)) { 'ByGroup' }
)
if ($selectedTargets.Count -ne 1) {
    throw "Specify exactly one target: DeviceNames or GroupName."
}
$TargetMode = $selectedTargets[0]

# ============================================================================
# ENVIRONMENT DETECTION AND SETUP
# ============================================================================

function Initialize-RequiredModule {
    param(
        [string[]]$ModuleNames,
        [bool]$IsAutomationEnvironment,
        [bool]$ForceInstall = $false
    )

    foreach ($ModuleName in $ModuleNames) {
        Write-Verbose "Checking module: $ModuleName"

        $module = Get-Module -ListAvailable -Name $ModuleName | Select-Object -First 1

        if (-not $module) {
            if ($IsAutomationEnvironment) {
                throw "Module '$ModuleName' is not available in Azure Automation"
            }
            else {
                Write-Information "Module '$ModuleName' not found. Installing..." -InformationAction Continue

                if (-not $ForceInstall) {
                    $response = Read-Host "Install module '$ModuleName'? (Y/N)"
                    if ($response -notmatch '^[Yy]') {
                        throw "Module '$ModuleName' is required but installation was declined."
                    }
                }

                try {
                    $isAdmin = ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")
                    $scope = if ($isAdmin) { "AllUsers" } else { "CurrentUser" }

                    Install-Module -Name $ModuleName -Scope $scope -Force -AllowClobber -Repository PSGallery
                    Write-Information "✓ Successfully installed '$ModuleName'" -InformationAction Continue
                }
                catch {
                    throw "Failed to install module '$ModuleName': $($_.Exception.Message)"
                }
            }
        }

        Import-Module -Name $ModuleName -Force -ErrorAction Stop
    }
}

# Detect execution environment
$IsAzureAutomation = $null -ne $PSPrivateMetadata.JobId.Guid

# Initialize required modules
$RequiredModules = @("Microsoft.Graph.Authentication")

# MgGraphCommunity gives WAM-free interactive sign-in for local runs
if (-not $IsAzureAutomation) {
    $RequiredModules += "MgGraphCommunity"
}

try {
    Initialize-RequiredModule -ModuleNames $RequiredModules -IsAutomationEnvironment $IsAzureAutomation -ForceInstall $ForceModuleInstall
    Write-Verbose "✓ All required modules are available"
}
catch {
    Write-Error "Module initialization failed: $_"
    exit 1
}

# ============================================================================
# AUTHENTICATION
# ============================================================================

try {
    if ($IsAzureAutomation) {
        Write-Output "Connecting to Microsoft Graph using Managed Identity..."
        Connect-MgGraph -Identity -NoWelcome -ErrorAction Stop
    }
    else {
        Write-Output "Connecting to Microsoft Graph..."
        $Scopes = @(
            "DeviceManagementManagedDevices.ReadWrite.All",
            "GroupMember.Read.All"
        )
        Connect-MgGraphCommunity -Scopes $Scopes -NoWelcome -ErrorAction Stop
    }
    Write-Output "✓ Successfully connected to Microsoft Graph"
}
catch {
    Write-Error "Failed to connect to Microsoft Graph: $($_.Exception.Message)"
    exit 1
}

# ============================================================================
# HELPER FUNCTIONS
# ============================================================================

function Get-MgGraphAllPage {
    param(
        [string]$Uri,
        [int]$DelayMs = 100
    )

    $allResults = @()
    $nextLink = $Uri

    do {
        try {
            if ($allResults.Count -gt 0) {
                Start-Sleep -Milliseconds $DelayMs
            }

            $response = Invoke-MgGraphRequest -Uri $nextLink -Method GET

            if ($null -ne $response.value) {
                $allResults += $response.value
            }
            else {
                $allResults += $response
            }

            $nextLink = $response.'@odata.nextLink'
        }
        catch {
            if ($_.Exception.Message -like "*429*") {
                Write-Information "Rate limit hit, waiting 60 seconds..." -InformationAction Continue
                Start-Sleep -Seconds 60
                continue
            }
            throw "Error fetching data: $($_.Exception.Message)"
        }
    } while ($nextLink)

    return $allResults
}

function Get-TargetDevice {
    # Resolves the requested devices to Intune Windows managed devices
    $devices = [System.Collections.Generic.List[Object]]::new()

    if ($TargetMode -eq "ByDevice") {
        foreach ($deviceName in $DeviceNames) {
            $escapedName = $deviceName -replace "'", "''"
            $found = Get-MgGraphAllPage -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices?`$filter=deviceName eq '$escapedName'&`$select=id,deviceName,operatingSystem,lastSyncDateTime"

            if (@($found).Count -eq 0) {
                Write-Warning "Device '$deviceName' not found in Intune"
                continue
            }
            foreach ($device in $found) {
                $devices.Add($device)
            }
        }
    }
    else {
        $escapedGroup = $GroupName -replace "'", "''"
        $groups = Get-MgGraphAllPage -Uri "https://graph.microsoft.com/beta/groups?`$filter=displayName eq '$escapedGroup'&`$select=id,displayName"
        if (@($groups).Count -ne 1) {
            throw "Expected exactly one group named '$GroupName', found $(@($groups).Count)"
        }

        $members = Get-MgGraphAllPage -Uri "https://graph.microsoft.com/beta/groups/$(@($groups)[0].id)/members?`$select=id,displayName,deviceId"
        foreach ($member in $members) {
            if (-not $member.deviceId) { continue }

            # Group members are Entra device objects; map to Intune managed devices
            $managed = Get-MgGraphAllPage -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices?`$filter=azureADDeviceId eq '$($member.deviceId)'&`$select=id,deviceName,operatingSystem,lastSyncDateTime"
            foreach ($device in $managed) {
                $devices.Add($device)
            }
        }
    }

    # Collect diagnostics is a Windows-only action
    $windowsDevices = @($devices | Where-Object { $_.operatingSystem -eq "Windows" })
    $skipped = @($devices).Count - $windowsDevices.Count
    if ($skipped -gt 0) {
        Write-Warning "Skipped $skipped non-Windows device(s) - collect diagnostics only supports Windows"
    }

    return $windowsDevices
}

function Save-DiagnosticPackage {
    param(
        [object]$Device,
        [object]$Request
    )

    try {
        $downloadResponse = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices/$($Device.id)/logCollectionRequests/$($Request.id)/createDownloadUrl" -Method POST
        $downloadUrl = $downloadResponse.value

        if (-not $downloadUrl) {
            Write-Warning "No download URL returned for '$($Device.deviceName)'"
            return $false
        }

        $timestamp = Get-Date -Format "yyyy-MM-dd_HH-mm-ss"
        $zipPath = Join-Path $OutputPath "DeviceDiagnostics_$($Device.deviceName)_$timestamp.zip"

        # The download URL is a pre-authenticated Azure Storage link from Graph,
        # so a plain web request (not Invoke-MgGraphRequest) is correct here
        Invoke-WebRequest -Uri $downloadUrl -OutFile $zipPath
        Write-Information "✓ Downloaded: $zipPath" -InformationAction Continue
        return $true
    }
    catch {
        Write-Warning "Failed to download package for '$($Device.deviceName)': $($_.Exception.Message)"
        return $false
    }
}

# ============================================================================
# MAIN SCRIPT LOGIC
# ============================================================================

try {
    $null = New-Item -Path $OutputPath -ItemType Directory -Force

    Write-Output "Resolving target devices..."
    $targetDevices = Get-TargetDevice

    if (@($targetDevices).Count -eq 0) {
        throw "No Windows devices found to collect diagnostics from"
    }
    Write-Output "✓ Targeting $(@($targetDevices).Count) Windows device(s)"

    $downloaded = 0
    $failed = 0
    $pendingRequests = @{}

    if ($DownloadExisting) {
        # Download the newest completed package per device without triggering anything
        foreach ($device in $targetDevices) {
            $requests = Get-MgGraphAllPage -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices/$($device.id)/logCollectionRequests"
            # The response entity carries receivedDateTimeUTC (not receivedDateTime)
            $latestCompleted = @($requests | Where-Object { $_.status -eq "completed" } | Sort-Object -Property @{ Expression = {
                        $timestamp = if ($_.receivedDateTimeUTC) { $_.receivedDateTimeUTC } else { $_.requestedDateTimeUTC }
                        if ($timestamp) { [DateTime]::Parse($timestamp.ToString()) } else { [DateTime]::MinValue }
                    } } -Descending) | Select-Object -First 1

            if (-not $latestCompleted) {
                Write-Warning "No completed log collection exists for '$($device.deviceName)' - run without -DownloadExisting to trigger one"
                $failed++
                continue
            }

            if (Save-DiagnosticPackage -Device $device -Request $latestCompleted) { $downloaded++ } else { $failed++ }
        }
    }
    else {
        # Trigger a new collection on every device
        foreach ($device in $targetDevices) {
            try {
                # The action parameter is a nested deviceLogCollectionRequest object,
                # not a flat string (Graph rejects { templateType = "predefined" })
                $body = @{ templateType = @{ templateType = "predefined" } } | ConvertTo-Json
                $request = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices/$($device.id)/createDeviceLogCollectionRequest" -Method POST -Body $body -ContentType "application/json"
                $pendingRequests[$device.id] = @{ Device = $device; RequestId = $request.id }
                Write-Output "✓ Collection triggered on '$($device.deviceName)'"
            }
            catch {
                Write-Warning "Failed to trigger collection on '$($device.deviceName)': $($_.Exception.Message)"
                $failed++
            }
        }

        # Poll until requests complete or the timeout is reached
        if ($pendingRequests.Count -gt 0) {
            Write-Output "Waiting for $($pendingRequests.Count) collection(s) to complete (timeout: $TimeoutMinutes minutes)..."
            $deadline = (Get-Date).AddMinutes($TimeoutMinutes)

            while ($pendingRequests.Count -gt 0 -and (Get-Date) -lt $deadline) {
                Start-Sleep -Seconds 30

                foreach ($deviceId in @($pendingRequests.Keys)) {
                    $entry = $pendingRequests[$deviceId]
                    try {
                        $status = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/beta/deviceManagement/managedDevices/$deviceId/logCollectionRequests/$($entry.RequestId)" -Method GET

                        if ($status.status -eq "completed") {
                            if (Save-DiagnosticPackage -Device $entry.Device -Request $status) { $downloaded++ } else { $failed++ }
                            $pendingRequests.Remove($deviceId)
                        }
                        elseif ($status.status -eq "failed") {
                            Write-Warning "Collection failed on '$($entry.Device.deviceName)'"
                            $failed++
                            $pendingRequests.Remove($deviceId)
                        }
                    }
                    catch {
                        Write-Verbose "Status check pending for '$($entry.Device.deviceName)': $($_.Exception.Message)"
                    }
                }
            }

            foreach ($deviceId in @($pendingRequests.Keys)) {
                $entry = $pendingRequests[$deviceId]
                Write-Warning "Collection on '$($entry.Device.deviceName)' did not complete within $TimeoutMinutes minutes - the device may be offline. Re-run later with -DownloadExisting to fetch the package."
            }
        }
    }

    # Summary
    Write-Output "`n========================================"
    Write-Output "Diagnostics Collection Summary"
    Write-Output "========================================"
    Write-Output "Devices targeted:  $(@($targetDevices).Count)"
    Write-Output "Packages saved:    $downloaded"
    Write-Output "Failures/timeouts: $($failed + $pendingRequests.Count)"
    Write-Output "Output folder:     $OutputPath"
    Write-Output "========================================"
}
catch {
    Write-Error "Script execution failed: $($_.Exception.Message)"
    exit 1
}
finally {
    try {
        $null = Disconnect-MgGraph
        Write-Output "✓ Disconnected from Microsoft Graph"
    }
    catch {
        Write-Verbose "Graph disconnection completed"
    }
}