Quick Start: Execute and Monitor a Schedule

Run an existing PBRS schedule through the REST API, monitor its progress, and verify its execution result and report delivery.

This guide uses ExecuteScheduleAsync. The request returns an ExecutionId while PBRS processes the schedule. Your application uses that identifier to retrieve execution status.

Before you begin

You need:

• A running PBRS REST API service.
• The API base address.
• A valid access token and permission to execute the selected schedule.
• An existing schedule that runs successfully from PBRS.
• The schedule's numeric identifier and schedule type.
• A controlled delivery destination for testing.

Running the example executes the schedule's configured actions and delivery. Check the recipients and destinations before submitting it.

Complete Authentication and Token Management first. The PowerShell examples below use the $PbrsAccessToken variable created in that guide.

1. Identify the schedule

Open the schedule's properties in PBRS and obtain its unique identifier.

For this quick start, select an existing single report schedule and use report as its ScheduleType.

RunBy is descriptive information. It does not replace authentication or grant permissions.

Use the exact request field spelling uniqueid.

2. Configure the example

Run the following in the same PowerShell session used for authentication:

$PbrsBaseUrl = "http://localhost:9000"
$PbrsScheduleId = [int](Read-Host "Enter the existing PBRS schedule ID")

if ([string]::IsNullOrWhiteSpace($PbrsAccessToken)) {
    throw "Obtain a PBRS access token before continuing."
}

$PbrsHeaders = @{
    Accept        = "application/json"
    Authorization = "bearer $PbrsAccessToken"
}

Replace the base address with your installation's configured protocol, hostname, and port. Keep /api out of the base address.

localhost is appropriate only when running the command on the PBRS server. Use HTTPS for network connections after configuring the server certificate and listener.

Access tokens expire after 60 minutes. Obtain a fresh token before starting the test.

3. Submit the execution

Send a JSON request to:

POST /api/Schedule/ExecuteScheduleAsync

Example request body:

{
  "ScheduleType": "report",
  "uniqueid": 101,
  "RunBy": "API Quick Start"
}

The value 101 is illustrative. The following PowerShell command uses the schedule identifier you entered:

$PbrsExecutionBody = @{
    ScheduleType = "report"
    uniqueid     = $PbrsScheduleId
    RunBy        = "API Quick Start"
} | ConvertTo-Json

$PbrsSubmittedAt = [DateTimeOffset]::UtcNow

$PbrsSubmission = Invoke-RestMethod `
    -Method Post `
    -Uri "$($PbrsBaseUrl.TrimEnd('/'))/api/Schedule/ExecuteScheduleAsync" `
    -Headers $PbrsHeaders `
    -ContentType "application/json" `
    -Body $PbrsExecutionBody `
    -TimeoutSec 30 `
    -ErrorAction Stop

if ([string]::IsNullOrWhiteSpace($PbrsSubmission.ExecutionId)) {
    throw "No ExecutionId was returned. Check the API execution queue before submitting again."
}

$PbrsExecutionId = [string]$PbrsSubmission.ExecutionId

Write-Host "ExecutionId: $PbrsExecutionId"
Write-Host "Submitted at: $PbrsSubmittedAt"

An accepted submission returns a response such as:

{
  "ExecutionId": "b2ad1236-e4f9-43d5-9593-993347fa4792"
}

Retain the returned identifier immediately.

An accepted request is not confirmation of successful execution or delivery.

If submission times out or fails without a clear outcome, do not automatically submit it again. The schedule may already be queued or running.

4. Monitor execution

Retrieve status using:

GET /api/Schedule/GetExecutionStatus?ExecutionId={ExecutionId}

Use the returned ExecutionId, not the schedule identifier or process identifier.

Poll with a deadline

The following example checks every five seconds for up to ten minutes. These are client-side example settings, not PBRS execution limits.

Each status request has its own timeout. A request failure stops the example; it does not resubmit the schedule.

$PbrsPollIntervalSeconds = 5
$PbrsPollingDeadline = [DateTimeOffset]::UtcNow.AddMinutes(10)
$PbrsEncodedExecutionId = [Uri]::EscapeDataString($PbrsExecutionId)
$PbrsStatusUrl = "$($PbrsBaseUrl.TrimEnd('/'))/api/Schedule/GetExecutionStatus?ExecutionId=$PbrsEncodedExecutionId"

$PbrsCompleted = $false

while ([DateTimeOffset]::UtcNow -lt $PbrsPollingDeadline) {
    $PbrsStatus = Invoke-RestMethod `
        -Method Get `
        -Uri $PbrsStatusUrl `
        -Headers $PbrsHeaders `
        -TimeoutSec 30 `
        -ErrorAction Stop

    if ($null -eq $PbrsStatus) {
        throw "No execution record was returned. Retain ExecutionId $PbrsExecutionId and investigate."
    }

    if ([string]$PbrsStatus.ExecutionId -ne $PbrsExecutionId) {
        throw "The returned execution identifier does not match the submitted execution."
    }

    $PbrsState = [string]$PbrsStatus.Status
    Write-Host "Execution $PbrsExecutionId : $PbrsState"

    if ($PbrsState -eq "Completed") {
        $PbrsCompleted = $true
        break
    }

    if ($PbrsState -eq "Terminated by user" -or $PbrsState -eq "Stale") {
        throw "Execution requires investigation. Status: $PbrsState. ExecutionId: $PbrsExecutionId"
    }

    if ($PbrsState -notin @("Waiting", "Executing")) {
        throw "Unrecognized execution status '$PbrsState'. Retain the record and investigate before retrying."
    }

    Start-Sleep -Seconds $PbrsPollIntervalSeconds
}

if (-not $PbrsCompleted) {
    throw "Polling deadline reached. Execution $PbrsExecutionId may still be active. Do not resubmit automatically."
}

Reaching the polling deadline stops local monitoring. It does not cancel the PBRS execution or establish that it failed.

A status request already in progress can extend monitoring beyond the polling deadline by its request timeout.

Interpret the status

Status is an open string. If another value is returned, preserve it and investigate rather than classifying it as success.

5. Inspect the execution result

ResultJson contains JSON encoded inside a string. Parse it separately from the outer status response.

A completed status response can include:

{
  "ExecutionId": "b2ad1236-e4f9-43d5-9593-993347fa4792",
  "uniqueid": 101,
  "ProcessId": 4820,
  "Status": "Completed",
  "ResultJson": "{\"Result\":true,\"ErrorMessage\":\"\",\"ErrorNumber\":0}"
}

This is an illustrative subset of the status fields.

Continue with the completed record from the polling example:

if ([string]::IsNullOrWhiteSpace($PbrsStatus.ResultJson)) {
    throw "Execution completed without a result payload. Verify the outcome before retrying."
}

$PbrsResult = $PbrsStatus.ResultJson | ConvertFrom-Json -ErrorAction Stop

if ($PbrsResult.Result -isnot [bool]) {
    throw "The execution result does not contain the expected boolean Result field."
}

if (-not $PbrsResult.Result) {
    throw "PBRS reported failure. Error $($PbrsResult.ErrorNumber): $($PbrsResult.ErrorMessage)"
}

Write-Host "PBRS reported a successful execution result. Verify the output and delivery."

A Completed record can contain Result: false, including when execution exceeds an applicable timeout.

An empty or unparseable result is not evidence of success.

6. Verify output and delivery

After PBRS reports success, confirm that the schedule produced the intended business outcome:

• The expected report files were generated.
• The content, filters, parameters, and output format are correct.
• The files reached the configured destination.
• Email attachments or destination files are accessible as expected.
• No duplicate delivery occurred.

For packages or schedules with multiple outputs, verify each expected output and destination.

An email accepted for sending is not, by itself, confirmation that it reached the recipient's inbox.

Review execution in PBRS

To inspect API execution activity in the application:

1. Open System Monitor.
2. Select API Execution Queue.
3. Locate the relevant execution using the schedule and submission details.

For troubleshooting, retain:

• Schedule identifier and schedule type.
• Returned ExecutionId.
• Submission time.
• Last retrieved status.
• Error number and message, if present.
• Relevant output and delivery evidence.

Keep access tokens, credentials, and confidential report content out of diagnostic logs.

Choose the appropriate execution mode

These operations are not interchangeable. Consult their reference pages before changing execution mode.

For example, do not substitute ExecuteScheduleOnTimeAsync when you need to preserve the next scheduled run.

Recover without duplicate execution

Renew an expired token before resuming status checks. Token renewal does not require submitting the schedule again.

Cancellation is a separate action. It is not guaranteed to remove every waiting job, and it does not undo files already created or reports already delivered.

For a complete PowerShell example, follow Authenticate, Execute, and Monitor a Schedule. The recipe covers authentication, asynchronous execution, polling with a time limit, and execution-result checks.

Next steps

Continue with Discover Folders, Reports, and Reporting Resources to obtain identifiers programmatically.

Use Monitor, Recover, and Reconcile Executions for advanced polling, cancellation, reconciliation, and recovery workflows.