Jobs and cron
What a Schedule is, what a fire is not, and how one is declared and read.
A Schedule starts Runs of a Workflow on a calendar or an interval. Nothing calls it: every fire is an engine timer, so a schedule that is due fires even while nothing of yours is running.
(schedule, intended time) is the Run identity. One instant starts at most
one Run, however many times a wake is delivered, so a retry or a duplicated
wake cannot start the same instant's Run twice. And a fire is not a Run
result: the fire is what starts the Run, and how that Run ended is the Run's
own outcome.
What you set on a Schedule
| Field | Type | What it is |
|---|---|---|
calendar.kind | string | The trigger: rate, a fixed period, or cron, an expression. |
calendar.everySeconds | number | The period of a rate, 1 to 31536000 seconds. |
calendar.expression | string | The 5- or 6-field cron expression of a cron calendar. |
calendar.timezone | string | The IANA time zone the calendar is read in. |
overlap | string | What a fire does while the previous Run is still running: skip, buffer_one or allow. |
catchUp | string | What a missed fire does: skip, last_only (only the most recent), or bounded by maxTicks or maxAgeSeconds. |
target | object | Where the fire lands: an http target (an https url, a method, signed set to true), or execute, which names a jobId and its expectedRevision. |
retry.maxAttempts | number | How many times a fire is retried. |
pause | bool | Whether fires are paused. |
A rate's first due time is one interval after the schedule is created, so a schedule made now with a 30-second rate first fires 30 seconds from now.
How a Schedule is declared
You declare a Schedule in sylphx.toml, and each release projects it into the
environment, as that environment, with its own key. A [[jobs]] row with a
schedule gets one Schedule, and a [[compute.schedules]] row declares one on
its own, naming the service and the path the fire is sent to. A Schedule
runs in the project's production environment only; a row opts the others in
with previews = true. Changing the cron or timezone replaces the Schedule in
place, and removing the row retires it. The quickstart
shows the whole loop.
Reading and controlling it
The one API's schedules collection is the Schedule Resource, and the calls
that read and control a declared Schedule are served on api.sylphx.com. A
request presents a Sylphx Access key, Authorization: Bearer sylphx_sk_….
Creating and updating a Schedule are declared in sylphx.toml, not called:
the create and update methods of the collection refuse.
- Base URL
- https://api.sylphx.com
- List
- GET /v1/orgs/{org}/projects/{project}/envs/{env}/schedules
- Read one
- GET …/schedules/{schedule}
- Pause, resume
- POST …/schedules/{schedule}:pause, :resume
- Delete
- DELETE …/schedules/{schedule}
- Scopes
- workflows:read to read, workflows:write to change
- Name
- orgs/{org}/projects/{project}/envs/{env}/schedules/{schedule}
A declared Schedule is named <id>@<environment id>; the part before the @
is the id you declared.