Schedule Step Dispatch

Schedule steps are dispatched to Panel Service via the /api/schedules/action/next endpoint.

Accessing this endpoint requires the "scheduler" license, and "Execute|Schedule" permission. Additionally Read and Write data permissions are needed for ScheduleInstance, StepInstance, Schedule, and ServiceStatus.

This endpoint dispatches the next available step(s) that can run on the connecting service. It also handles side-effects that are part of schedule operations, including:

• Finding and terminating expired steps. An expired step is one that was previously dispatched to a Panel Service, but where that Panel Service is either no longer available, or has experienced a restart since the step was dispatched.
• Queuing steps that must run soon based on scheduled time. This is done by finding any schedule times (less currently running schedules) where the schedule is due to start between 15 seconds ago, and 20 seconds from now. If the time is in the future, an async task is queued to wake at the schedule start time.
• Unless the nopoll=true query parameter is specified, sleep asynchronously for up to 20 seconds to see if steps become available for dispatch (part of long polling implementation)

Like other Panel Service endpoints, application/bson is the normal serialization format, but application/json is available. Unlike e.g. the HistoryRecord type, schedule steps will serialize in both formats.

NOTES:

This endpoint uses a database driven implementation of critical section locking (for step queuing and dispatch). This reduces scheduler performance, but solves problems of simultaneous dispatch on load-balanced instances.

Headers:

This endpoint expects the X-Version header to be supplied which provides the current version number of the Panel Service making the request. If the header is missing a version of "pre 3.4" is assumed.

Requests to this endpoint MUST provide the X-ServiceName header identifying the servername of the requesting Panel Service.

Query Parameters:

nopoll: causes the scheduler to return results right away without waiting for steps to be enqueued. If no steps are already in the queue an empty result will be returned.

Response Format:

This endpoint returns a ListWrap<StepInstance>.

For example:

{
  "Count": 1,
  "Data": [
    {
      "Id": byte array, // schedule instance id + int representing the index of the step
      "Service": "service name",
      "ServiceInstance: "guid", // random guid of current run instance of service (used to detect restarts)
      "Locks": [ "step lock" ], // exclusive and shared locks used for step isolation based on run type
      "Order": 0, // step index in schedule
      "ScheduleInstance": byte array,
      "Status": "NotStarted|Running|FailedStart|Finished|Failed|TimedOut|Skipped|Cancelled",
        // Set to Running when dispatched
      "Error": null,
      "Started": "timestamp", // set for dispatch
      "Finished": null, // set on submission
      "InProcess": true, // set on dispatch
      "Paused": false, // set by user via dashboard on separate endpoint
      "StepHistoryId": null, // guid set after step runs if it produces history
      "Step": { schedule step definition json/bson, comes from schedule settings },
      "Skip": 0 // number of steps to skip based on rule evaluation, set by Panel Service post-execution
    }
  ]
}