Monitor, Recover, and Reconcile Executions

Track PBRS executions from submission through report generation and delivery. Use execution identifiers, status results, schedule history, and destination evidence to determine what happened before retrying work.

A successful HTTP response, an accepted execution, and a delivered report are different outcomes.

Before you begin

You need:

• A configured PBRS API connection.
• A valid access token.
• The schedule identifier and schedule type.
• Access to execution results and relevant delivery evidence.
• An application record of submitted work.

Send these headers with JSON requests:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

Complete Quick Start: Execute and Monitor a Schedule before implementing automated recovery.

The identifiers in this guide are examples. Replace them with values returned by your PBRS installation.

1. Record the submission

Before requesting execution, record enough information to investigate an uncertain response.

Keep credentials and access tokens out of execution logs. Protect any recorded parameters or driver data according to their sensitivity.

An application request identifier is for your own tracking. It does not make a PBRS execution request idempotent.

Where an execution request supports a supplied ExecutionId, do not treat that field as a duplicate-prevention guarantee. Retain the identifier returned by the operation.

2. Use the identifier returned by the operation

Execution operations do not all return the same response.

ExecuteScheduleOnTimeAsync uses the scheduled-time execution path and advances NextRun. Do not substitute it for an on-demand execution when preserving the next scheduled run matters.

For event execution, preserve the submitted event information. Do not assume every event uses the same AsyncData format.

Keep identifiers separate

Do not pass a schedule ID or process ID to an endpoint that requires ExecutionId.

Process IDs can be reused and are not globally unique across servers. Confirm the current process, server, and schedule before taking a process-level action.

3. Submit and retain the execution ID

For an asynchronous report execution:

POST /api/Schedule/ExecuteScheduleAsync

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

An accepted request returns an execution identifier:

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

Save the identifier immediately with your application record.

For a package, use its package-level uniqueid and ScheduleType: "package".

Acceptance means PBRS has acknowledged the execution request. It does not establish that rendering or delivery succeeded.

4. Poll execution status

Request the status using the returned identifier:

GET /api/Schedule/GetExecutionStatus?ExecutionId=b2ad1236-e4f9-43d5-9593-993347fa4792

Example response:

{
  "ExecutionId": "b2ad1236-e4f9-43d5-9593-993347fa4792",
  "uniqueid": 101,
  "ProcessId": 4820,
  "Status": "Completed",
  "EntryDateEpoch": 1789462800,
  "CompletionDateEpoch": 1789462812,
  "RunBy": "API",
  "ResultJson": "{\"Result\":true,\"ErrorMessage\":\"\",\"ErrorNumber\":0}",
  "ServerName": "PBRS-SERVER",
  "ScheduleType": "report",
  "ScheduleName": "Daily sales"
}

Use bounded polling

Your application should:

1. Set a polling interval appropriate to the workflow.
2. Set an overall monitoring deadline.
3. Set a timeout for each HTTP request.
4. Save the latest status and any populated result.
5. Stop normal polling when a conclusive result is available.
6. Move unresolved executions into reconciliation when the deadline expires.

Renew authentication when needed and continue monitoring the same ExecutionId.

A status-request timeout is not an instruction to submit the schedule again.

Interpret states

Treat Status as an open string. Preserve unfamiliar values and investigate them rather than failing to read the entire response.

An empty result or an unset completion timestamp does not establish success.

5. Parse the execution result

ResultJson is JSON encoded inside a string. Parse the response first, then parse ResultJson when it is populated.

For the successful example above, the decoded result is:

{
  "Result": true,
  "ErrorMessage": "",
  "ErrorNumber": 0
}

A Completed execution can instead contain a failed result. For example:

{
  "Result": false,
  "ErrorMessage": "Schedule was removed from API execution queue due to exceeding the allowed timeout of 10 hours",
  "ErrorNumber": 1041226
}

The timeout message can say “10 hours” even when the configured timeout differs. Do not calculate the effective timeout from the message text.

Evaluate all relevant result fields:

• Result: whether the execution reports success.
• ErrorMessage: available failure information.
• ErrorNumber: the reported error identifier.

Do not treat the following as success:

• HTTP 200 without checking the response body.
• Status: "Completed" without checking ResultJson.
• Empty or null ResultJson.
• A result that cannot be parsed.
• A missing or unrecognized result value.

Preserve an unparseable result for investigation. Do not convert it into a successful outcome or automatically re-execute the schedule.

6. Verify report generation and delivery

After inspecting the execution result, confirm that the workflow produced the expected outcome.

An email delivery result does not prove that a person opened the message. Define whether your application's requirement is submission to the mail system, mailbox receipt, or another measurable outcome.

For packages and data-driven schedules, inspect individual reports and destinations. One successful file or delivery does not establish that the entire package succeeded.

7. Reconcile an uncertain outcome

Reconciliation means determining what PBRS actually executed and delivered before deciding whether another execution is necessary.

Start reconciliation when:

• Submission timed out or the connection was lost.
• Your application did not save the returned execution ID.
• Polling reached its deadline.
• A queue record is stale or no longer available.
• The execution result and delivery evidence disagree.
• Only part of a package or workflow completed.
• Collaboration or failover changed where work executed.

When you have an ExecutionId

1. Request GetExecutionStatus again using the saved identifier.
2. Inspect the API queue if additional context is needed.
3. Check currently executing schedules.
4. Correlate the schedule, server, process, and timestamps.
5. Review applicable schedule history.
6. Inspect report output and destination evidence.
7. Record the confirmed outcome or leave it unresolved.

A record disappearing from the API queue does not establish that the execution never occurred.

When submission returned no identifier

A timeout or lost response can occur after PBRS accepted the request.

Before submitting again:

1. Inspect the API execution queue.
2. Look for matching schedule type, schedule ID, submission time, and other available details.
3. Check currently executing work and applicable history.
4. Inspect the intended destinations.
5. Determine whether another application or scheduled run could explain the matching records.

A matching schedule name alone is insufficient when concurrent or repeated runs are possible.

If the available evidence cannot distinguish the original submission from another execution, retain an unresolved outcome for review. Do not assume that the first request failed.

8. Use the appropriate monitoring view

These views are not interchangeable. A due schedule is not proof of an active execution, and an empty API queue does not prove that no reports are running.

Schedule history

For example:

GET /api/Scheduleinfo/getScheduleHistory?id=101&page=1&pageSize=50

The response contains:

• Items.
• TotalCount.
• Page.
• PageSize.

The default page is 1, and the default page size is 50.

Paging is not a stable snapshot. New activity can change the results while you retrieve additional pages. Empty or out-of-range responses can report TotalCount: 0; do not interpret that as proof that the schedule has never run.

History result fields contain the strings "true" or "false" when a result is populated. A null result does not establish success or failure.

Do not apply the boolean parsing rules for decoded ResultJson indiscriminately to every history response.

Latest result limitations

For a report schedule:

POST /api/Scheduleinfo/LastRunResult

{
  "Id": 101,
  "ScheduleType": "report"
}

LastRunResult returns the latest stored result, which may belong to a later execution than the one you are investigating.

When no matching history exists, numeric fields can be zero and result or text fields null. This is not proof of success or failure.

This operation does not populate ScheduleName, StartedAtUtc, or FinishedAtUtc. Do not depend on those fields to correlate its response.

Do not use ScheduleType: "package" with LastRunResult to determine a package execution outcome. Retain the package execution's ExecutionId, inspect GetExecutionStatus, and verify delivery.

Schedule-type selectors are operation-specific. Do not copy a selector between execution and history requests without checking the target operation.

9. Separate deadlines, timeouts, and retention

Reaching a client deadline does not cancel the server-side execution.

Timeout cleanup can produce a Completed record with Result: false and error number 1041226. Reconcile current activity and delivered output before retrying.

The API queue is not a durable archive. Save execution identifiers, results, timestamps, and delivery evidence when your application requires long-term records.

See Errors, Execution States, and Limits for additional limit details.

10. Cancel or terminate an execution

Cancellation and termination change execution state. They do not roll back generated files or recall delivered reports.

Cancel using ExecutionId

GET /api/Schedule/CancelExecution?ExecutionId=b2ad1236-e4f9-43d5-9593-993347fa4792

A successful response is:

{
  "Result": "Execution cancelled successfully"
}

This response's Result is a message string, not a boolean.

The operation resolves the execution record's associated process and attempts to terminate it. A waiting record without a live associated process may fail; this is not a general guarantee that any queued job can be removed.

Cancellation can be recorded with Status: "Terminated by user" and this decoded result:

{
  "Result": false,
  "ErrorMessage": "Execution cancelled by user",
  "ErrorNumber": -102562911
}

After cancellation:

1. Retrieve execution status again.
2. Inspect current execution activity.
3. Confirm the recorded result.
4. Check what output or delivery occurred before termination.
5. Check for child or delegated work that may require separate attention.

Do not assume cancelling a parent terminates every child or delegated execution.

Terminate using ProcessId

GET /api/Schedule/TerminateSchedule?ProcessId=4820

A successful response is a JSON boolean:

true

Before calling this operation, confirm the current process identity, associated schedule, and executing server.

A ProcessId does not identify a remote server. Confirm that the API server you address is responsible for the intended process; do not assume the request is automatically forwarded to a collaborator.

Do not reuse an old process ID without checking current activity.

After termination, inspect the task monitor, applicable execution records, and delivery evidence. Do not assume a process-level response updates every related record or resolves an entire workflow.

Both cancellation and termination use GET despite changing state. Exclude them from health probes, automatic link checks, prefetching, and generic GET retry policies.

Stopping the scheduler is not a substitute for reconciling or terminating an individual execution.

11. Recover partial packages and distributed workflows

A workflow can finish some reports or deliveries before another part fails.

For packages, record:

• Which report members generated output.
• Which merged files were produced.
• Which destinations received files.
• Which driver records and recipients were affected.
• Which parts failed or remain unresolved.

For automation and collaboration, also record:

• Parent and child schedule identifiers.
• Nested workflow relationships.
• Collaboration method.
• Assigned server.
• Observed execution server.
• Parent and child results.
• Delivery evidence for each child.

Use Current Server Name in controlled email tests to verify actual execution servers. Under Server Affinity, compare execution with the designated server. Under Round-Robin, do not treat a difference from the affinity assignment as a failure.

Do not assume each child schedule appears as a separate API queue entry or has its own API ExecutionId.

After failover, check execution ownership and completed deliveries before restarting work. Takeover alone does not establish that a previous execution stopped or that its output was not delivered.

See Operate the API and Scheduler for the collaboration verification procedure.

12. Decide whether to retry

PBRS execution requests do not expose an idempotency-key contract. Repeating a submission can create another execution and another delivery.

If retrying is appropriate:

1. Correct the underlying failure.
2. Confirm the intended schedule configuration and data inputs.
3. Check that no earlier attempt, scheduled run, or other integration is already performing the work.
4. Decide how to handle outputs already produced.
5. Submit once.
6. Retain the new execution identifier and associate it with the original attempt.
7. Monitor and verify the new outcome.

Do not assume retrying a package resumes only its failed members. Re-executing the package can repeat previously successful reports and deliveries.

A later execution can also use changed report data, driver records, or schedule settings. Confirm whether a fresh run satisfies the original business requirement.

Troubleshooting

Next steps

Use Errors, Execution States, and Limits to interpret failures and timing behavior.

Use Operate the API and Scheduler to inspect server state, collaboration, and current execution activity.