foliot docs

API reference / Reference / Workflow definition

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

SettingTypeDefaultRequiredWhat it does
namestring—YesThe 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-]*$
stepslist of steps—YesThe 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
versioninteger—YesThis definition's version number. A run stays on the version it started on for its whole life.
1 to 2147483647
descriptionstring—NoA short description of the workflow.
at most 1000 characters
retryretry policy—NoThe retry policy for every task step in the workflow. A step's own retry overrides it field by field.
runTimeoutduration—NoHow 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.

SettingTypeDefaultRequiredWhat it does
kindtask—YesWhich kind of step this is.
namestring—YesThe 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_.?-]*$
descriptionstring—NoA short description of the step.
at most 500 characters
handlerstring—NoA 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
nextstring—NoWhere 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
onFailurestring—NoWhere 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
queuestring—NoThe 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
retryretry policy—NoThis 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.
timeoutduration30sNoHow 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).

SettingTypeDefaultRequiredWhat it does
kindsleep—YesWhich kind of step this is.
namestring—YesThe 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_.?-]*$
descriptionstring—NoA short description of the step.
at most 500 characters
forduration—NoHow long to pause. Set for or untilPath; if you set both, for is used.
nextstring—NoWhere 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
onFailurestring—NoAccepted, 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
untilPathstring—NoA 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.

SettingTypeDefaultRequiredWhat it does
kindwait—YesWhich kind of step this is.
namestring—YesThe 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_.?-]*$
descriptionstring—NoA short description of the step.
at most 500 characters
nextstring—NoWhere 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
onFailurestring—NoAccepted, 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
onTimeoutstring—NoWhere 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
signalstring—NoThe 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
timeoutduration—NoHow 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.

SettingTypeDefaultRequiredWhat it does
elsestring—YesWhere the run goes when when is false: a step's name, or $end, $fail or $stuck.
at most 100 characters
kindchoice—YesWhich kind of step this is.
namestring—YesThe 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_.?-]*$
thenstring—YesWhere the run goes when when is true: a step's name, or $end, $fail or $stuck.
at most 100 characters
whencondition—YesThe condition to check against the run's input and state.
descriptionstring—NoA short description of the step.
at most 500 characters
nextstring—NoA 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
onFailurestring—NoAccepted, 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

SettingTypeDefaultRequiredWhat it does
backoffexponential or fixedexponentialNoHow 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.
initialduration10sNoThe wait before the first retry, and before every retry when backoff is fixed.
maxduration1hNoThe longest wait between attempts when backoff is exponential.
maxAttemptsinteger5NoHow many times a task step is tried in all, counting the first attempt.
1 to 1000
retryOnlist of strings—NoThe 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 are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days) and w (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.

ShapeSettingsWhat it does
Comparisonop: eq, ne, gt, gte, lt, lte, in or contains
path: string
value: any
Compares the value at path with value, using op.
Presence checkop: exists or truthy
path: string
Checks the value at path, using op. It takes no value.
All ofand: list of conditionsTrue when every condition in the list is true.
Any ofor: list of conditionsTrue when at least one condition in the list is true.
Notnot: conditionTrue 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:

OperatorTrue when
eqThe value at path equals value. Only strings, numbers, booleans and null can be equal; a list or an object never is.
neThe value at path is missing, or does not equal value.
gtBoth are numbers, and the value at path is greater than value.
gteBoth are numbers, and the value at path is greater than or equal to value.
ltBoth are numbers, and the value at path is less than value.
lteBoth are numbers, and the value at path is less than or equal to value.
invalue is a list, and the value at path equals one of its items.
containsThe value at path is a list with an item equal to value, or a string that contains the string value.
existsThe value at path is present and not null.
truthyThe value at path is present and is not false, 0, "" or null.