Operate the API and Scheduler

Use the PBRS REST API to check connectivity, inspect scheduler state, control scheduling, monitor execution, and apply collaboration settings.

API availability, scheduler state, execution capacity, and report delivery are separate checks. A successful response from one does not establish that the others are healthy.

Before you begin

You need the configured PBRS API address and a valid access token for protected endpoints.

Send these headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

For JSON request bodies, also send:

Content-Type: application/json

GET /api/Service/Ping does not require authentication.

Run scheduler controls and collaboration changes through an administrative integration. Confirm which server you are addressing before changing its state.

Operations at a glance

Check API connectivity

GET /api/Service/Ping

A successful response is HTTP 200 with:

1

This confirms that the API endpoint is reachable and responding. It does not verify:

• Authentication.
• Scheduler state.
• Reporting account access.
• Database connectivity.
• Rendering or delivery.

If Ping fails, check the API service, configured address, network route, firewall, and applicable HTTPS configuration.

The API service must already be running to receive requests. StartScheduler starts the scheduler; it does not start an unavailable API service.

Check scheduler state

GET /api/Service/IsSchedulerRunning

A running scheduler returns:

true

A stopped scheduler returns:

false

The response is a JSON boolean, not an object containing a Result property.

A value of true describes scheduler state. It does not prove that every report, destination, or external dependency is working.

Start the scheduler

GET /api/Service/StartScheduler

A successful request returns HTTP 200 with an empty body.

After the request, call:

GET /api/Service/IsSchedulerRunning

Confirm that the scheduler reports the intended state. Review due schedules and execution activity after starting it.

Do not attempt to parse the empty start response as JSON.

Stop the scheduler

GET /api/Service/StopScheduler

A successful request returns HTTP 200 with an empty body.

Then retrieve scheduler state again:

GET /api/Service/IsSchedulerRunning

Stopping the scheduler can interrupt scheduled reporting. Do not treat it as a guarantee that all active work has finished or that every execution submitted through another path has been cancelled.

Inspect current execution activity separately.

StartScheduler and StopScheduler change server state despite using GET. Keep them out of health probes, automatic link checks, prefetching, and generic GET retry policies.

Retrieve the configuration path

GET /api/Service/GetConfigPath

With Accept: application/json, the response is a JSON string. For example:

"\\\\PBRS-SERVER\\PBRS\\config"

The result can be a network path. It is not the configuration file contents or a download URL.

Accessing that path from another machine requires the appropriate network connectivity and filesystem permissions.

Monitor execution

Use the monitoring endpoint that matches the question you need to answer.

These endpoints provide different views. Do not assume their results contain the same records or identifiers.

Inspect the API execution queue

GET /api/Schedule/GetExecutionQueue

The response contains waiting, executing, and retained API execution records.

Example:

[
  {
    "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"
  }
]

Keep these identifiers separate:

Observed queue states include Waiting, Executing, Completed, Terminated by user, and Stale. Handle additional state values without rejecting the entire response.

Interpret execution results

ResultJson contains JSON encoded inside a string. Parse it separately when a value is present.

For the example above, the decoded result is:

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

A record can have Status: "Completed" and still contain Result: false.

An empty ResultJson is not proof of success. It can occur while work is waiting, executing, or stale.

For an individual execution, request:

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

Use bounded polling, inspect the result, and confirm the generated output and delivery when required.

Queue retention

The queue selection includes completed entries whose completion age is less than 120000 seconds, or 33 hours and 20 minutes.

This selection window is not a guarantee that every record remains available for that duration. The API queue is not a durable execution archive.

Store execution identifiers, timestamps, results, and relevant delivery evidence separately when your application requires long-term history.

Inspect due schedules

GET /api/SystemMonitor/AllDue

This returns the Due Today — All monitor view, ordered by NextRunEpoch.

A due schedule is not necessarily an execution already submitted to the API queue. Do not use this response as evidence that a report is running or has been delivered.

Inspect currently executing schedules

GET /api/SystemMonitor/GetCurrentlyExecuting

The response contains task-monitor records with fields such as:

• ScheduleName.
• ScheduleType.
• uniqueid.
• ProcessId.
• ServerName.
• Status.
• EntryDateEpoch.

These records describe running processes. They are distinct from API queue records identified by ExecutionId.

Correlate process IDs with server names and execution details rather than treating a process ID as a globally unique execution identifier.

Check available execution capacity

GET /api/Schedule/GetNumberOfFreeThreads

Example response:

{
  "Result": 2
}

Result reports available schedule-execution capacity for the current server. The default capacity is four, but configuration can change it. The returned count is clamped to zero.

The value is a snapshot, not a reservation. Another request or scheduler action can consume capacity before your application submits work.

A result of zero does not by itself indicate a service failure.

Schedule execution slots, report-page renderer processes, and data-driver row threads are different capacities. This endpoint does not report all three.

The capacity calculation can also clean up old execution entries, so it is not a capacity-reservation operation.

Apply collaboration settings

Collaboration allows a primary PBRS installation to delegate schedule execution to other PBRS servers.

Before changing collaboration configuration:

• Configure the API on every participating server.
• Verify connectivity between the servers.
• Ensure collaborators use the primary scheduler’s database.
• Verify reporting, email, database, filesystem, and other execution dependencies on each server.
• Record the current configuration and recovery procedure.
• Coordinate the change with active scheduling.

Collaborators execute work assigned by the primary rather than their own local schedules. Follow the PBRS collaboration setup procedure when establishing the environment.

Request fields

POST /api/Service/UpdateCollaborationSettings

Supply values appropriate to the target server and its configured database. These connection fields are not API authentication credentials.

Do not send an empty object as a no-op request or assume omitted properties preserve every existing setting.

Effects of the update

This operation:

• Applies collaboration settings.
• Terminates relevant system processes.
• Rewrites configuration.
• Replaces stored connection values when nonempty connection fields are supplied.
• Clears local database connection fields.

It is not a simple flag update. Disabling collaboration must not be assumed to restore a previous standalone database configuration.

A successful request returns HTTP 200 with an empty body. It does not return the resulting configuration.

After the operation:

1. Verify configuration on the affected server.
2. Confirm access to the intended scheduler database.
3. Confirm the required processes and services are running.
4. Check API connectivity and scheduler state.
5. Verify delegated execution with a controlled schedule.
6. Inspect generated output and delivery.

If the connection is lost during the change, inspect the server before retrying. The operation may already have changed configuration or terminated processes.

Understand collaboration and failover

Collaboration distributes execution across participating servers. Failover provides a backup scheduler that can take over when the primary fails.

The supported collaboration methods include:

UpdateCollaborationSettings does not, by itself, complete a failover deployment.

Configure the backup scheduler and required shared dependencies using the PBRS failover setup procedure.

Validate takeover and recovery in your environment, including execution ownership, access to reports, and destination delivery. Do not assume a configuration response guarantees uninterrupted or duplicate-free delivery.

Verify collaboration with an automation workflow

Use a controlled automation workflow to verify that child schedules execute on the intended collaborating servers and deliver the expected reports.

Configure and run this initial test through the PBRS interface. It verifies the collaboration environment independently of an application's API request handling.

Prepare the test

1. Complete collaboration setup and confirm the required dependencies on each participating server.
2. Use at least two collaborating execution servers for this test so that you can observe work assigned to different servers. This is a test arrangement, not a universal deployment minimum.
3. Select Server Affinity when testing whether a child schedule runs on its designated server.
4. Prepare two or more child report schedules with controlled email destinations.
5. Assign the child schedules to different servers.
6. In each child's email subject, include a recognizable test label and insert Current Server Name using the PBRS message-insert selector.

Use the actual Current Server Name insert rather than typing a fixed server name into the subject.

Confirm that each assigned server can access the report source and deliver to the test destination.

Run a parent automation schedule

1. Create a parent Automation schedule.
2. Add multiple Run Schedule tasks, each referencing one of the prepared child report schedules.
3. Execute the parent manually.
4. Inspect the parent and child execution activity and results.
5. Check each delivered email's subject for the actual execution server.
6. Open the attached reports and verify their content.

Compare the observed execution server with each child's assigned server. A successful parent execution alone does not establish that every child generated and delivered its report.

Cover other automation workflows

Repeat the test for the workflow types used in your environment:

Use controlled events and a small, known set of driver records. For nested automation, inspect each level rather than relying only on the top-level result.

This procedure verifies the distribution of child schedules within a workflow. It does not establish that one report is divided across servers, that all child schedules execute simultaneously, or that a particular speed improvement is guaranteed.

Record execution and delivery evidence

For each test case, record:

Under Round-Robin, the schedule's affinity selection does not determine the execution server. Verify execution on participating servers and successful delivery without treating a difference from the affinity assignment as a failure.

If a child fails, identify which reports were already generated or delivered before retrying the parent. Re-running the entire workflow can repeat successful deliveries.

Verify API-triggered execution separately

After the manual workflow succeeds, test the execution operation used by your application against the same controlled configuration.

Use an operation that supports the parent schedule type, and follow that operation's request and identifier contract. Retain any returned execution identifier and correlate it with the parent, child execution records, and delivery evidence.

Do not assume that every child appears as a separate API queue entry or receives its own API ExecutionId. Use the task monitor, schedule history, server information, and delivered output as appropriate.

The manual workflow test does not by itself validate an API request, event-context payload, or application retry policy.

Perform a maintenance check

Before maintenance:

1. Confirm the target server and its role.
2. Check API connectivity and scheduler state.
3. Inspect due schedules, the API queue, and currently executing work.
4. Coordinate external applications that can submit executions.
5. Record relevant execution IDs and configuration.
6. Stop scheduling if the maintenance procedure requires it.

After maintenance:

1. Confirm that the API responds.
2. Confirm the intended scheduler state.
3. Verify database and reporting dependencies.
4. Inspect outstanding executions.
5. Run a controlled report and verify delivery.
6. Resume normal scheduling and submissions.

In a collaborative environment, perform the applicable checks on every affected server.

Handle responses and failures

Parse responses according to the endpoint contract:

• Ping returns a number.
• Scheduler status returns a boolean.
• Configuration path returns a string.
• Capacity returns an object.
• Monitoring endpoints return arrays.
• Start, stop, and collaboration updates return empty bodies.

Do not apply a universal “parse every successful response as a JSON object” rule.

Protected requests require a valid bearer token. Renew authentication when the token expires.

Service operations can return HTTP 500 for processing failures. Inspect available error details and the server’s actual state before retrying a state-changing request.