Workflow definition
This page lists every setting a workflow definition accepts. They are the same whether you build the definition with the SDK’s defineWorkflow or register it as JSON with PUT /apps/{appId}/workflows. Settings of type duration take a length of time written like "10s" or "1h30m", or a number of milliseconds. See Durations.
Workflow
| Setting | Type | Default | Required | What it does |
|---|---|---|---|---|
name | string | — | Yes | The workflow's name. You name it when you start a run. Use lower-case letters, digits and hyphens. at most 100 characters · pattern ^[a-z0-9][a-z0-9-]*$ |
steps | list of steps | — | Yes | The steps, in order. A step goes on to the next one in the list unless it sets next.at least 1 item · at most 200 items |
version | integer | — | Yes | This definition's version number. A run stays on the version it started on for its whole life. 1 to 2147483647 |
description | string | — | No | A short description of the workflow. at most 1000 characters |
retry | retry policy | — | No | The retry policy for every task step in the workflow. A step's own retry overrides it field by field. |
runTimeout | duration | — | No | How long a run may take, counted from when you start it. A run that has not finished by then is marked stuck. A rewind starts the clock again, and so does a redrive of a run that has failed, is stuck or is past its deadline; a redrive of a run still within its deadline keeps it. Without it, a run has no time limit. |
Steps
There are four kinds of step, set by kind: task, sleep, wait, choice. A step's next, onFailure, then, else or onTimeout names another step, or one of these special values: $end finishes the run as succeeded, $fail finishes it as failed, and $stuck marks it stuck so you can redrive it.
Task step
Calls your handler, or offers the task to a worker that pulls tasks when the step sets queue. It is the only kind of step that reaches your app.
| Setting | Type | Default | Required | What it does |
|---|---|---|---|---|
kind | task | — | Yes | Which kind of step this is. |
name | string | — | Yes | The step's name, unique within the workflow. Other steps' next, onFailure, then, else and onTimeout refer to it.at most 100 characters · pattern ^[a-zA-Z0-9][a-zA-Z0-9_.?-]*$ |
description | string | — | No | A short description of the step. at most 500 characters |
handler | string | — | No | A path on the app's handler base URL, starting with a single /. Defaults to /foliot/{workflow}/{step}. Never an address: no scheme, host or //, and no spaces, control characters, backslashes or #.at most 500 characters |
next | string | — | No | Where the run goes when this step finishes: a step's name, or $end, $fail or $stuck. Defaults to the next step in the list, or $end after the last one.at most 100 characters |
onFailure | string | — | No | Where the run goes if this step fails for good, when its retries are used up or its error cannot be retried: a step's name, or $end, $fail or $stuck. For example, a step that releases reserved stock. Without it, the run fails.at most 100 characters |
queue | string | — | No | The name of a queue to offer this step's tasks on, for a worker that pulls tasks with POST /apps/{appId}/tasks/poll. When set, Foliot does not send the task to your handler.at most 100 characters |
retry | retry policy | — | No | This step's retry policy. A field left out comes from the workflow's retry, and from the defaults there when the workflow does not set it either. |
timeout | duration | 30s | No | How long one attempt may take. An attempt that is not finished in time fails, and is tried again if the retry policy allows. |
Sleep step
Pauses the run for a length of time (for) or until a time held in the run's data (untilPath).
| Setting | Type | Default | Required | What it does |
|---|---|---|---|---|
kind | sleep | — | Yes | Which kind of step this is. |
name | string | — | Yes | The step's name, unique within the workflow. Other steps' next, onFailure, then, else and onTimeout refer to it.at most 100 characters · pattern ^[a-zA-Z0-9][a-zA-Z0-9_.?-]*$ |
description | string | — | No | A short description of the step. at most 500 characters |
for | duration | — | No | How long to pause. Set for or untilPath; if you set both, for is used. |
next | string | — | No | Where the run goes when this step finishes: a step's name, or $end, $fail or $stuck. Defaults to the next step in the list, or $end after the last one.at most 100 characters |
onFailure | string | — | No | Accepted, but a sleep step does not use it: if the sleep's end cannot be worked out (for example, untilPath is not a date), the run fails.at most 100 characters |
untilPath | string | — | No | A path to a timestamp in the run's input or state, such as input.sendAt. The run pauses until that time. The value must be an RFC 3339 timestamp, such as 2026-12-01T09:00:00Z. |
Wait step
Pauses the run until a named signal arrives, with an optional timeout.
| Setting | Type | Default | Required | What it does |
|---|---|---|---|---|
kind | wait | — | Yes | Which kind of step this is. |
name | string | — | Yes | The step's name, unique within the workflow. Other steps' next, onFailure, then, else and onTimeout refer to it.at most 100 characters · pattern ^[a-zA-Z0-9][a-zA-Z0-9_.?-]*$ |
description | string | — | No | A short description of the step. at most 500 characters |
next | string | — | No | Where the run goes when this step finishes: a step's name, or $end, $fail or $stuck. Defaults to the next step in the list, or $end after the last one.at most 100 characters |
onFailure | string | — | No | Accepted, but a wait step does not use it: a wait that times out goes to onTimeout, or fails the run without one.at most 100 characters |
onTimeout | string | — | No | Where the run goes if the signal does not arrive in time: a step's name, or $end, $fail or $stuck. Without it, the run fails.at most 100 characters |
signal | string | — | No | The name of the signal to wait for. Defaults to the step's name. A signal sent before the run reaches this step is kept and used when it gets here. at most 100 characters |
timeout | duration | — | No | How long to wait for the signal. Without it, the run waits until the signal arrives. |
Choice step
Picks the next step from a condition on the run's input and state. Foliot checks the condition itself, and none of your code runs. The result is kept in the run's state under the step's name.
| Setting | Type | Default | Required | What it does |
|---|---|---|---|---|
else | string | — | Yes | Where the run goes when when is false: a step's name, or $end, $fail or $stuck.at most 100 characters |
kind | choice | — | Yes | Which kind of step this is. |
name | string | — | Yes | The step's name, unique within the workflow. Other steps' next, onFailure, then, else and onTimeout refer to it.at most 100 characters · pattern ^[a-zA-Z0-9][a-zA-Z0-9_.?-]*$ |
then | string | — | Yes | Where the run goes when when is true: a step's name, or $end, $fail or $stuck.at most 100 characters |
when | condition | — | Yes | The condition to check against the run's input and state. |
description | string | — | No | A short description of the step. at most 500 characters |
next | string | — | No | A choice goes to then or else, not to next. next is used only if you skip a run past this step.at most 100 characters |
onFailure | string | — | No | Accepted, but a choice step does not use it: if the choice cannot go to the step it picked, the run fails. at most 100 characters |
Retry policy
| Setting | Type | Default | Required | What it does |
|---|---|---|---|---|
backoff | exponential or fixed | exponential | No | How the wait between attempts grows. exponential doubles it after each failed attempt, starting at initial and never longer than max. fixed waits initial every time. Each wait is varied slightly, so runs that failed together do not all retry at once. |
initial | duration | 10s | No | The wait before the first retry, and before every retry when backoff is fixed. |
max | duration | 1h | No | The longest wait between attempts when backoff is exponential. |
maxAttempts | integer | 5 | No | How many times a task step is tried in all, counting the first attempt. 1 to 1000 |
retryOn | list of strings | — | No | The error classes to retry. With a non-empty list, only an error whose class is in it is tried again, and an error with no class is not. An empty list counts as not set. Not set on the workflow, every error that can be retried is; not set on a step, the workflow's list applies. An error your handler marks as not retryable is never retried. |
Durations
A length of time, written the way people say it: "10s", "3d", "1h30m", "250ms". A bare number is milliseconds.
The ceiling is 9223372036854 ms, about 292 years. Anything longer is refused, in either spelling.
- A string, such as
"10s"or"1h30m". The units arems(milliseconds),s(seconds),m(minutes),h(hours),d(days) andw(weeks). - A number of milliseconds, such as
250.
Conditions
A condition tree. and, or and not may nest at most 32 levels deep; a deeper tree is refused. A node has exactly one shape (a comparison, and, or or not); one with more than one is refused.
| Shape | Settings | What it does |
|---|---|---|
| Comparison | op: eq, ne, gt, gte, lt, lte, in or containspath: stringvalue: any | Compares the value at path with value, using op. |
| Presence check | op: exists or truthypath: string | Checks the value at path, using op. It takes no value. |
| All of | and: list of conditions | True when every condition in the list is true. |
| Any of | or: list of conditions | True when at least one condition in the list is true. |
| Not | not: condition | True when the condition inside it is false. |
A condition's path is a dot-separated path into the run's data, starting with input (what the run was started with) or state (each finished step's output, under the step's name). For example, input.amount or state.check-fraud.approved.
A comparison or presence check is true when:
| Operator | True when |
|---|---|
eq | The value at path equals value. Only strings, numbers, booleans and null can be equal; a list or an object never is. |
ne | The value at path is missing, or does not equal value. |
gt | Both are numbers, and the value at path is greater than value. |
gte | Both are numbers, and the value at path is greater than or equal to value. |
lt | Both are numbers, and the value at path is less than value. |
lte | Both are numbers, and the value at path is less than or equal to value. |
in | value is a list, and the value at path equals one of its items. |
contains | The value at path is a list with an item equal to value, or a string that contains the string value. |
exists | The value at path is present and not null. |
truthy | The value at path is present and is not false, 0, "" or null. |