Quick Start: Execute and Monitor a Schedule

Run an existing Tableau report schedule, monitor its execution and check that the expected report reaches its destination.

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.

Choose a single-report schedule that already runs successfully in ATRS. Confirm its report, parameters and test destination. Running it through the API can generate files and send mail.

1. Identify the schedule

Find the numeric ID through folder discovery, or use an ID already recorded for this installation.

This example uses report. To run an existing package, use package and its package-level ID as described in Create and Manage Report Packages.

2. Prepare the request

Enter the intended single-report schedule ID:

$AtrsScheduleId = [long](Read-Host "Working single-report schedule ID")
if ($AtrsScheduleId -le 0) { throw "Enter a positive schedule ID" }
$AtrsScheduleType = "report"
$AtrsSubmittedAtUtc = [DateTime]::UtcNow.ToString("o")
$AtrsBody = @{
    ScheduleType = $AtrsScheduleType
    UniqueId = $AtrsScheduleId
    RunBy = "API"
} | ConvertTo-Json

3. Submit once and save the execution ID

Send POST /api/Schedule/ExecuteScheduleAsync:

$AtrsAccepted = Invoke-RestMethod -Method Post `
    -Uri "$AtrsBaseUrl/api/Schedule/ExecuteScheduleAsync" `
    -Headers $AtrsHeaders -ContentType "application/json" `
    -Body $AtrsBody -TimeoutSec 60
if ([string]::IsNullOrWhiteSpace($AtrsAccepted.ExecutionId)) {
    throw "No execution ID returned. Check activity before submitting again."
}
$AtrsExecutionId = [string]$AtrsAccepted.ExecutionId
Write-Host "ExecutionId: $AtrsExecutionId"

The response contains ExecutionId. Save it immediately with the installation, schedule ID, family and submission time. It lets you monitor this run even if your application restarts. The recovery guide provides a file-based example.

If submission times out or returns no ID, inspect activity before sending another execution. Work may already have started.

4. Monitor the execution

Use the returned ID with GET /api/Schedule/GetExecutionStatus:

$AtrsDeadline = [DateTime]::UtcNow.AddMinutes(10)
$AtrsFinished = $false
$AtrsEncodedId = [uri]::EscapeDataString($AtrsExecutionId)
while ([DateTime]::UtcNow -lt $AtrsDeadline) {
    $AtrsStatus = Invoke-RestMethod -Method Get `
        -Uri "$AtrsBaseUrl/api/Schedule/GetExecutionStatus?ExecutionId=$AtrsEncodedId" `
        -Headers $AtrsHeaders -TimeoutSec 30
    if ($null -eq $AtrsStatus -or $AtrsStatus.ExecutionId -ne $AtrsExecutionId) {
        throw "No matching execution record. Check activity and history."
    }
    Write-Host $AtrsStatus.Status
    if ($AtrsStatus.Status -in @("Completed", "Terminated by user")) {
        $AtrsFinished = $true
        break
    }
    if ($AtrsStatus.Status -eq "Stale") { break }
    Start-Sleep -Seconds 5
}
if (-not $AtrsFinished) {
    throw "Outcome unresolved. Keep ExecutionId $AtrsExecutionId; check activity before retrying."
}

Five seconds and ten minutes are example application settings, not API limits. An in-flight request can finish after the polling deadline. Transport errors stop this example so you can investigate the same run.

5. Check the execution result

ResultJson contains JSON inside a string. Parse it separately:

if ([string]::IsNullOrWhiteSpace($AtrsStatus.ResultJson)) {
    throw "No execution result is available. Investigate before retrying."
}
$AtrsResult = $AtrsStatus.ResultJson | ConvertFrom-Json -ErrorAction Stop
if ($AtrsResult.Result -isnot [bool] -or -not $AtrsResult.Result) {
    throw "Execution failed or result is invalid: $($AtrsResult.ErrorNumber) $($AtrsResult.ErrorMessage)"
}
Write-Host "ATRS reports success. Check the report and its destination."

A decoded success result has a boolean Result of true. A failed result can include ErrorNumber and ErrorMessage. Keep malformed or missing results for investigation.

6. Verify the report and delivery

Open the generated file or test email. Check:

• The intended Tableau view and parameter values.
• The expected file format, pages and layout.
• The intended recipient or server-side output folder.
• Every expected file when the workflow produces several outputs.

Your first execution is complete when you have checked both the reported result and the actual output.

If the outcome is uncertain

Keep the ExecutionId and follow Monitor, Recover, and Reconcile Executions. A status timeout does not cancel server work, and repeating submission can produce another delivery.