Monitor, Recover, and Reconcile Executions

Track an execution from submission to delivery. After a timeout or interrupted connection, check what already ran or arrived before deciding whether to submit another execution.

Before you begin

Complete Authentication and Token Management. The PowerShell examples use $AtrsBaseUrl and $AtrsHeaders from that guide. Run the steps in order in the same PowerShell session. Use your installation’s address and identifiers in place of the examples.

Complete the Quick Start. Keep execution records in an application-controlled location and keep credentials out of those records.

Record the submission

Before sending work, record the installation, operation, schedule ID, family, UTC submission time, intended destinations and your application’s operation ID. Mark the operation as awaiting a response.

Your operation ID helps prevent repeated button clicks in your application. It is not an ATRS idempotency key and does not prevent duplicate execution inside ATRS.

Record an accepted execution

After Quick Start submission returns $AtrsExecutionId, save a separate record for that run:

$AtrsJournalPath = Join-Path (Get-Location) ("atrs-execution-" + [guid]::NewGuid() + ".json")
@{
    BaseUrl = $AtrsBaseUrl
    ScheduleId = $AtrsScheduleId
    ScheduleType = $AtrsScheduleType
    SubmittedAtUtc = $AtrsSubmittedAtUtc
    ExecutionId = $AtrsExecutionId
} | ConvertTo-Json | Set-Content -LiteralPath $AtrsJournalPath -Encoding UTF8 -ErrorAction Stop
Write-Host "Execution record: $AtrsJournalPath"

If saving fails, retain the printed execution ID and investigate. Do not submit again merely because the local record was not saved.

Monitor the same execution

Use GetExecutionStatus with ExecutionId. Apply bounded polling, check the returned ID and parse the populated ResultJson separately. The Quick Start polling and result steps provide a complete example.

Resume monitoring after a restart

Select the record for the intended run. Authenticate to that recorded installation first, then load the record and retrieve status:

$AtrsJournalPath = Read-Host "Path to the intended execution record"
$AtrsJournal = Get-Content -LiteralPath $AtrsJournalPath -Raw -ErrorAction Stop | ConvertFrom-Json
if ([string]::IsNullOrWhiteSpace($AtrsJournal.ExecutionId)) { throw "Record has no execution ID" }
if ($AtrsJournal.BaseUrl.TrimEnd('/') -ne $AtrsBaseUrl.TrimEnd('/')) {
    throw "Authenticate to the installation recorded for this execution"
}
$AtrsExecutionId = [string]$AtrsJournal.ExecutionId
$AtrsEncodedId = [uri]::EscapeDataString($AtrsExecutionId)
$AtrsStatus = Invoke-RestMethod -Method Get `
    -Uri "$AtrsBaseUrl/api/Schedule/GetExecutionStatus?ExecutionId=$AtrsEncodedId" `
    -Headers $AtrsHeaders -TimeoutSec 30
$AtrsStatus | ConvertTo-Json -Depth 50

Confirm the returned execution ID. Resume the Quick Start’s polling/result steps with this same ID if the run is still active. If it cannot be found, use the queue, history and output checks below.

Recover when submission returned no execution ID

A request can be accepted before its response is lost. Inspect activity rather than repeating submission:

$AtrsScheduleId = [long](Read-Host "Schedule ID from the submission record")
$AtrsQueue = Invoke-RestMethod -Method Get `
    -Uri "$AtrsBaseUrl/api/Schedule/GetExecutionQueue" -Headers $AtrsHeaders -TimeoutSec 30
$AtrsActive = Invoke-RestMethod -Method Get `
    -Uri "$AtrsBaseUrl/api/SystemMonitor/GetCurrentlyExecuting" -Headers $AtrsHeaders -TimeoutSec 30
$AtrsHistory = Invoke-RestMethod -Method Get `
    -Uri "$AtrsBaseUrl/api/Scheduleinfo/GetScheduleHistory?id=$AtrsScheduleId&page=1&pageSize=50" `
    -Headers $AtrsHeaders -TimeoutSec 30
$AtrsQueue | ConvertTo-Json -Depth 50
$AtrsActive | ConvertTo-Json -Depth 50
$AtrsHistory | ConvertTo-Json -Depth 50

The operations are GetExecutionQueue, GetCurrentlyExecuting and GetScheduleHistory.

Compare installation, schedule, family, submission time and destinations. A matching name alone is insufficient. If you identify the run, record its execution ID and monitor it. History does not provide a guaranteed execution-ID join; new records can arrive during pagination. Retrieve additional history pages when needed using the documented page and pageSize parameters.

Check actual files and mail as well. If the evidence cannot distinguish the original run from another run, keep the outcome unresolved for review.

Verify delivery and partial output

Open expected files or test mail and verify content, recipients and output count. For packages, check every member. For data-driven work, check each intended record and recipient mapping.

An empty queue does not prove no work ran. The API queue is not a durable archive. Keep identifiers, results and delivery evidence externally when long-term history is required.

For package outcomes, use the retained execution ID, its status and delivery evidence. LastRunResult with a package selector is not a substitute for that workflow.

Cancel or terminate deliberately

For a confirmed execution ID, CancelExecution attempts to terminate its associated process:

$AtrsCancelId = [uri]::EscapeDataString($AtrsExecutionId)
Invoke-RestMethod -Method Get -Uri "$AtrsBaseUrl/api/Schedule/CancelExecution?ExecutionId=$AtrsCancelId" `
    -Headers $AtrsHeaders -TimeoutSec 30

It can fail for a waiting entry without a live process. Read status again and inspect output after the request.

For a process-level action, confirm the current process, schedule and server before using TerminateSchedule:

$AtrsProcessId = [int](Read-Host "Confirmed current process ID on this API server")
Invoke-RestMethod -Method Get -Uri "$AtrsBaseUrl/api/Schedule/TerminateSchedule?ProcessId=$AtrsProcessId" `
    -Headers $AtrsHeaders -TimeoutSec 30

Process IDs can be reused and are not globally unique across servers. Recheck the process monitor afterward. Both operations change state despite using GET, and neither rolls back files or recalls mail. Do not assume cancelling a parent stops every child or delegated run.

Decide whether to retry

A fresh run can use changed report data, schedule settings or driver records. Confirm that it still meets the original requirement. See Errors, Execution States, and Limits for result types and timing behavior.