Scheduler Connector

Overview

Runs runbooks on a recurring or one-off schedule. The connector exposes two triggers — Scheduler for runbooks whose schedule is configured statically on the trigger, and Dynamic Scheduler for runbooks whose schedules are created, updated, and deleted at runtime by other runbooks — plus three actions (Create Schedule, Update Schedule, Delete Schedule) that manage schedules pointing at Dynamic Scheduler runbooks. Schedules are persisted in iPaaS and dispatched by the platform's internal scheduler service; no external service is called.

Prerequisites

• Access to the Xurrent runbook builder.
• For Dynamic Scheduler workflows, the runbook being scheduled must already exist in the same solution and use the Dynamic Scheduler trigger; the manager runbook references it by runbook_uuid.

Authentication

None — this connector runs in-process against the current solution's schedule store. No connection needs to be configured.

Triggers

Scheduler

Triggers the runbook on the recurrence configured on the trigger itself. When the runbook is provisioned, a schedule record is created from the trigger config; when the runbook is deprovisioned, the schedule is soft-deleted. The trigger is internal — the dispatch is performed by the platform's scheduler service, not by an external HTTP caller.

Use case: run a runbook every 15 minutes, every weekday at 09:00, on the first of every month, etc., where the cadence is known at design time and lives with the runbook.

Input Parameters

Schedule (Recurrence) object fields

Example Input

Trigger configuration on the runbook (every other week on Saturday and Sunday at 16:55:50 UTC):

{
"schedule": {
  "frequency": "weekly",
  "time_zone": "UTC",
  "interval": 2,
  "day": ["saturday", "sunday"],
  "time_of_day": "16:55:50"
},
"request_body": { "source": "scheduler" }
}

Output

Example Output

{
"body": {
  "schedule_reference": "f0b5a7e9-3c52-4e7a-9b2e-2a9c1b1d6e44",
  "source": "scheduler"
},
"triggered_at": "2026-04-29T16:55:50Z"
}

Error Handling

• Provision failure — if the schedule cannot be persisted (validation error on the recurrence, missing required fields, invalid frequency, etc.), provision raises Failed to register schedule: <error> and the runbook deployment fails.
• Deprovision — silently no-ops if no schedule_reference is stored against the trigger; otherwise performs a soft delete (deleted: true).
• Invalid recurrence at runtime — if next_occurrence_at cannot be computed (e.g. timeout while computing), the schedule disables itself and the next-occurrence error is recorded on the schedule record.
• Dispatch failure — if dispatching the runbook returns a non-2xx response, the platform's scheduler service records Runbook execution failed with status <status> and continues to the next occurrence.

Best Practices

• Use this trigger when the cadence is owned by the runbook itself. For schedules driven by another runbook (e.g. one schedule per onboarded customer), use Dynamic Scheduler plus Create Schedule.
• Set a time_zone explicitly. Defaults to the server's Time.zone, which is rarely what users expect when reasoning about local fire times.
• Put run-correlation data (e.g. a tenant ID, environment marker) into request_body; the scheduler reference is injected for free as schedule_reference.

Dynamic Scheduler

Triggers a runbook when an external Create Schedule action fires its scheduled job. Unlike Scheduler, this trigger has no recurrence config of its own — the schedule lives in a separate record created by another runbook calling Create Schedule, and the trigger only describes how to extract a job-context identifier from the inbound request.

Use case: run-per-tenant or run-per-resource schedules where the set of schedules changes at runtime — e.g. a manager runbook that creates one schedule per customer onboarded, and a worker runbook (this trigger) that fires when each schedule occurrence dispatches.

Input Parameters

Example Input

Trigger configuration on the runbook:

{
"job_context_identifier_path": "body.schedule_reference"
}

Output

Example Output

{
"body": {
  "schedule_reference": "tenant-42-daily",
  "tenant_id": "42"
},
"triggered_at": "2026-04-29T09:00:00Z"
}

Error Handling

• Path not present — the path resolver walks body first and falls back to top-level keys; if no key matches, no context identifier is set and the run proceeds normally.
• Path traversal error — if a segment is applied to a non-hash value (e.g. indexing into an array with a string key), the trigger logs Unable to determine job context identifier. <ErrorClass>: <message> and the run proceeds without a context identifier.
• Empty body — the trigger accepts empty bodies; body is set to the raw value (nil or empty string) and triggered_at is still emitted.

Best Practices

• Set job_context_identifier_path to a value that uniquely identifies the work item driven by the schedule (e.g. body.schedule_reference or body.tenant_id); job-context identifiers are how iPaaS deduplicates and correlates concurrent runs.
• Keep the path stable. Changing it after schedules are live retroactively changes how concurrent runs of the same worker are correlated.
• When the manager runbook owns the lifecycle, store schedule_reference somewhere durable (a runbook variable, a CMDB record) so that Update Schedule and Delete Schedule can be called against it later.

Actions

Create Schedule

Creates a new schedule that fires the runbook identified by runbook_uuid. The target runbook must be in the same solution and must use the Dynamic Scheduler trigger (the platform rejects the call otherwise). On success the action returns the schedule_reference (echoed from the input) and the computed next_occurrence_at.

Use case: a manager runbook that creates per-tenant or per-resource schedules at runtime — for example, when a new customer is onboarded, create a daily schedule that runs the worker runbook for that customer.

Input Parameters

Example Input

{
"runbook_uuid": "7c0d8739-5fbd-4a6f-a1b4-2991bb0e2b54",
"schedule_reference": "tenant-42-daily",
"schedule": {
  "frequency": "weekly",
  "time_zone": "UTC",
  "interval": 1,
  "day": ["monday", "wednesday", "friday"],
  "time_of_day": "09:00:00"
},
"request_body": { "tenant_id": "42" }
}

Output

Example Output

{
"schedule_reference": "tenant-42-daily",
"next_occurrence_at": "2026-05-01T09:00:00Z",
"next_occurrence_errors": null
}

Error Handling

• Unknown runbook — if runbook_uuid does not match a runbook in the current solution, the action fails the job with Failed to create schedule: No Runbook found.
• Wrong trigger — if the target runbook does not use a supported scheduler trigger template, the action fails with Failed to create schedule: Trigger template <uuid> is not supported for scheduling.
• Duplicate reference — schedule_reference must be unique per solution; reusing one fails validation with Failed to create schedule: ["Reference must be unique per solution"].
• Invalid recurrence — missing frequency for a recurrent schedule, interval < 1, an unknown frequency, or invalid day_of_week/month_of_year values fail validation with the corresponding ActiveRecord error message.

Best Practices

• Generate schedule_reference deterministically from a stable key (e.g. "tenant-#{id}-daily") so the manager runbook can recompute it later without persisting it separately.
• Capture next_occurrence_errors and surface it back to the caller — a successful create with a null next_occurrence_at means the schedule was registered but will never fire as configured.
• Pass tenant/resource identifiers through request_body rather than encoding them into schedule_reference; the worker runbook reads them from body directly.

Update Schedule

Replaces the recurrence on an existing schedule identified by schedule_reference. Pending dispatches enqueued before the update are unscheduled so the new recurrence takes effect immediately.

Use case: change the cadence of a previously created schedule — e.g. shift a customer's nightly run from 02:00 to 04:00 after their time zone changes, or pause a schedule by setting disabled: true on the recurrence.

Input Parameters

Example Input

{
"schedule_reference": "tenant-42-daily",
"schedule": {
  "frequency": "weekly",
  "time_zone": "UTC",
  "interval": 1,
  "day": ["monday", "wednesday", "friday"],
  "time_of_day": "09:00:00"
}
}

Output

Example Output

{ "success": true }

Error Handling

• Unknown reference — schedule_reference not found in the current solution (or already soft-deleted) fails the job with Failed to update schedule: Schedule not found.
• Validation failure — invalid recurrence values fail with Failed to update schedule: Schedule update failed. Schedule fields not provided in schedule are reset to their defaults during the update — pass a complete recurrence object, not a partial patch.

Best Practices

• Treat Update Schedule as a full replacement, not a patch. Recompute the entire recurrence from your source of truth before calling.
• To pause a schedule without losing the reference, Update Schedule with disabled: true on the recurrence; to resume, send another Update Schedule with disabled: false.
• For one-off changes to the next firing only, prefer creating a fresh schedule with Create Schedule and deleting the old one — Update Schedule clears the queued occurrence and recomputes from the new recurrence's start_date.

Delete Schedule

Soft-deletes the schedule identified by schedule_reference. Pending dispatches for the schedule are unscheduled.

Use case: tear down per-tenant schedules when a tenant is offboarded; clean up schedules whose owning resource has been removed.

Input Parameters

Example Input

{ "schedule_reference": "tenant-42-daily" }

Output

Example Output

{ "success": true }

Error Handling

Soft-delete is idempotent — calling Delete Schedule with a schedule_reference that does not exist (or is already deleted) returns { "success": true } without error. There are no validation failure modes once schedule_reference is provided.

Best Practices

• Pair Delete Schedule with the same idempotency key your manager runbook uses to Create Schedule, so reruns of the offboarding flow don't fail when the schedule is already gone.
• Soft-deleted schedules are filtered out by the model's default scope (where(deleted: false)); callers cannot resurrect a deleted reference. To re-enable, Create Schedule again with a fresh recurrence.

Best Practices

• Use the Scheduler trigger when the cadence is owned by the runbook (one runbook → one schedule). Use Dynamic Scheduler + Create / Update / Delete Schedule when schedules are created at runtime (one runbook → many schedules).
• Use deterministic schedule_reference values (e.g. "tenant-<id>-<purpose>") so manager runbooks can update or delete schedules without persisting the reference separately. References must be unique per solution.
• Always specify time_zone explicitly on recurrences — relying on the platform default makes runbook behaviour environment-dependent.
• Carry tenant/resource identifiers through request_body. The worker runbook receives them on its body output alongside the platform-injected schedule_reference.
• Set job_context_identifier_path on Dynamic Scheduler to the field that uniquely identifies the work item (typically body.schedule_reference or body.tenant_id). Job-context identifiers drive concurrency and correlation for runs of the same worker runbook.
• Recurrences with frequency: minutely or hourly self-enqueue the next occurrence after each run. daily / weekly / monthly / yearly are batched by the platform's daily enqueuer; expect the first daily-or-coarser run to be dispatched directly only when its first occurrence falls before tomorrow.

Common Use Cases

• Recurring runbook on a fixed cadence — add the Scheduler trigger to the runbook, set frequency, interval, time_of_day, and time_zone, and provision the runbook. The platform creates the schedule automatically.
• Per-tenant scheduled work — manager runbook calls Create Schedule with schedule_reference: "tenant-<id>-<purpose>", runbook_uuid of a worker runbook (using the Dynamic Scheduler trigger), and request_body carrying the tenant ID. The worker runbook reads the tenant ID from body on each fire.
• Pause / resume an existing schedule — manager runbook calls Update Schedule with the same schedule_reference and a recurrence carrying disabled: true to pause; send another Update Schedule with disabled: false to resume.
• Bulk teardown on offboarding — when a tenant is removed, manager runbook iterates the tenant's known schedule references and calls Delete Schedule for each. Idempotent, so retries are safe.

References

• iCalendar (RFC 5545) — recurrence semantics that the underlying recurrence engine (ice_cube) implements.
• IANA Time Zone Database — source of valid time_zone values.