Public/Get-ECMA2ConnectorSyncJob.ps1

function Get-ECMA2ConnectorSyncJob {
    <#
    .SYNOPSIS
        Gets Microsoft Entra cloud provisioning synchronization job details for a service principal.

    .DESCRIPTION
        Retrieves one or all synchronization jobs for the given service principal
        (enterprise application), including schedule and status - including whether
        the job's last run is still in progress, any active quarantine, and the
        number of escrowed entries (object-level errors being retried).
        Use this to confirm the correct servicePrincipalId/jobId, and current state,
        before calling Restart-ECMA2ConnectorSyncJob.

        IsRunning is true when the last execution has started but has no end time
        after its start time (and the job isn't paused). LastExecutionState is the
        result Graph reports for that execution and can read Failed or Succeeded
        while a run is still in progress.

        Timestamps are returned as DateTime values in the system's local time zone,
        including currentBegan, nextAttempt and seriesBegan inside Quarantine.
        EscrowCount and EscrowCountRaw come from the job's last execution;
        EscrowCountRaw also includes system-generated escrows.

        Requires a prior Connect-ECMA2Graph with Synchronization.Read.All or
        Synchronization.ReadWrite.All.

    .PARAMETER ServicePrincipalId
        The object ID of the service principal (enterprise application) the job belongs to.

    .PARAMETER JobId
        The synchronization job identifier. Omit to list all jobs for the service principal.

    .PARAMETER ApiVersion
        The Microsoft Graph API version to call. Defaults to v1.0.

    .EXAMPLE
        Get-ECMA2ConnectorSyncJob -ServicePrincipalId $spId -JobId $jobId

    .EXAMPLE
        Get-ECMA2ConnectorSyncJob -ServicePrincipalId $spId
        Lists all synchronization jobs for the service principal.
    #>

    [CmdletBinding()]
    param(
        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [string]$ServicePrincipalId,

        [Parameter(ValueFromPipelineByPropertyName)]
        [string]$JobId,

        [Parameter()]
        [ValidateSet('v1.0', 'beta')]
        [string]$ApiVersion = 'v1.0'
    )

    process {
        try {
            $baseUri = "https://graph.microsoft.com/$ApiVersion/servicePrincipals/$ServicePrincipalId/synchronization/jobs"
            $uri = if ($JobId) { "$baseUri/$JobId" } else { $baseUri }

            Write-Verbose "Getting synchronization job(s) from $uri"
            $response = Invoke-ECMA2GraphRequest -Method GET -Uri $uri

            $jobs = if ($JobId) { @($response) } else { $response.value }

            if (-not $jobs) {
                Write-Warning "No synchronization job(s) found for service principal '$ServicePrincipalId'"
                return
            }

            foreach ($job in $jobs) {
                $status = $job.status
                $lastExecution = $status.lastExecution
                $timeBegan = ConvertTo-ECMA2LocalDateTime -Value $lastExecution.timeBegan
                $timeEnded = ConvertTo-ECMA2LocalDateTime -Value $lastExecution.timeEnded

                # Graph's lastExecution.state only ever reports a result (Succeeded, Failed,
                # EntryLevelErrors), so it can't be used on its own to tell a run is in
                # progress. A run is in progress when it has a start time but no end time
                # after it - the same comparison the Entra portal shows as "In progress".
                # Compare the UTC instants, not the local values: during the daylight-saving
                # fall-back hour a later instant can have an earlier local clock time.
                $timeBeganUtc = ConvertTo-ECMA2LocalDateTime -Value $lastExecution.timeBegan -AsUtc
                $timeEndedUtc = ConvertTo-ECMA2LocalDateTime -Value $lastExecution.timeEnded -AsUtc
                $hasOpenExecution = $timeBeganUtc -and (-not $timeEndedUtc -or $timeEndedUtc -lt $timeBeganUtc)
                $isRunning = ($lastExecution.state -in @('InProgress', 'Pending')) -or
                    ($hasOpenExecution -and $status.code -notin @('Paused', 'NotConfigured'))

                # Quarantine details keep Graph's property names; only the timestamps are
                # converted to local time
                $quarantine = $status.quarantine
                if ($quarantine) {
                    $quarantineProperties = [ordered]@{}
                    foreach ($property in $quarantine.PSObject.Properties) {
                        $quarantineProperties[$property.Name] = if ($property.Name -in @('currentBegan', 'nextAttempt', 'seriesBegan')) {
                            ConvertTo-ECMA2LocalDateTime -Value $property.Value
                        }
                        else {
                            $property.Value
                        }
                    }
                    $quarantine = [PSCustomObject]$quarantineProperties
                }

                [PSCustomObject]@{
                    PSTypeName                 = 'ECMA2Host.SyncJob'
                    Id                          = $job.id
                    TemplateId                  = $job.templateId
                    ServicePrincipalId          = $ServicePrincipalId
                    ScheduleState               = $job.schedule.state
                    ScheduleInterval            = $job.schedule.interval
                    StatusCode                  = $status.code
                    IsRunning                   = [bool]$isRunning
                    LastExecutionState          = $lastExecution.state
                    LastExecutionTime           = $timeBegan
                    LastExecutionEndTime        = $timeEnded
                    LastSuccessfulExecutionTime = ConvertTo-ECMA2LocalDateTime -Value $status.lastSuccessfulExecution.timeEnded
                    SteadyStateLastAchievedTime = ConvertTo-ECMA2LocalDateTime -Value $status.steadyStateLastAchievedTime
                    Quarantine                  = $quarantine
                    EscrowCount                 = $lastExecution.countEscrowed
                    EscrowCountRaw              = $lastExecution.countEscrowedRaw
                    EscrowsPruned               = $status.escrowsPruned
                    ApiVersion                  = $ApiVersion
                }
            }
        }
        catch {
            Write-Error "Failed to get synchronization job for service principal '$ServicePrincipalId': $_"
        }
    }
}