Skip to main content
A workflow starts with a trigger and runs a set of tasks. Each task runs one action from the catalog and takes input parameters. A parameter can hold a fixed value, or take data from the trigger or from a task that ran before it. Parameter objects say where the data comes from. Interpolation with {{ ... }} reads the data into the value, and functions can transform it first.

Parameter objects

Every input parameter, on tasks and on the trigger, is an object with three keys: value, source and type. Values in loop, in conditions, and in the filters of the trigger and of “Wait for trigger” actions use the same object.
  • value: the literal value, or an interpolation that reads the output of a task or of the trigger, such as {{ $.message }}. Here $.message is a JSONPath. It runs against the output of the task or trigger in source. That output has the shape of the output_json_schema returned by GET /actions/{id} and GET /events/{id}. {{ @raw }} passes the whole output. Interpolation, below, lists every form.
  • source: "" for a literal. Otherwise the task or the trigger that produces the value, named as described in Referencing tasks and the trigger, below.
  • type: what source points at:
    • task: the task’s output body.
    • task_header: the task’s response headers.
    • trigger: the trigger data.
    • action_bundle: an input parameter of the enclosing action bundle, a reusable group of actions that a workflow runs as one action.
    • "": a literal, or an interpolation that doesn’t read a task or the trigger, such as @item and @var.
GET /actions/{id} returns the exact value/source/type shape an action expects, as its input_json_schema. For example, in a workflow_definition, an action with a literal url and a name taken from the output of an earlier action with slug fetch_user:

Referencing tasks and the trigger

How you name a task or the trigger in source depends on the endpoint:
  • In a workflow_definition (POST /workflows), use the slug you gave the action under actions, or the literal trigger.
  • On the per-task endpoints (POST /workflows/{workflow_id}/revisions/{revision_id}/tasks and PATCH /workflows/{workflow_id}/revisions/{revision_id}/tasks/{id}), use the task’s id, a UUID returned by the task endpoints, or the trigger’s id, returned by GET /workflows/{workflow_id}/revisions/{revision_id}/trigger. These endpoints don’t resolve slugs or the literal trigger.
On the per-task endpoints, the fetch_user reference from the example above uses that task’s id:
A task can only read the output of tasks that run before it. A task referenced with type task or task_header has to be connected to the task that references it through the revision’s dependencies, either directly or through other tasks. References to tasks that run in parallel or later are rejected. If a task is already connected through others, don’t add a direct dependency on it.

Interpolation

A parameter value is a string that can contain {{ ... }} interpolations. If the whole value is one interpolation, it keeps the type of what it resolves to, such as an object, list or number. If the value mixes text with interpolations or holds more than one, it becomes a string. Non-string values are JSON-encoded and missing values become null. For example, "Job {{ $.id }} done" becomes "Job 42 done" when id is 42. What an interpolation reads depends on the value’s source and type:
  • {{ $.path.to.field }}: a JSONPath into the output of the task or trigger in source. With type task, that is the task’s output body. With type trigger, it is the trigger data. With type task_header, it is the task’s response headers, with header names in lower case, such as {{ $.content-type }}. A missing field resolves to null.
  • {{ @raw }} or {{ $ }}: the whole output of the task or trigger in source.
  • {{ @file.path }}: the content of the source task’s output file, which is the same content as {{ @raw }}. Use it for file parameters, such as file and file_2 of “Transform JSON with jq v2”. On a “Create signed upload URL” task, it is the uploaded file, while {{ @raw }} is still the URL. The referencing task fails until the file has been uploaded. For the trigger, it resolves to null, so use {{ @raw }} there.
  • {{ @metadata.filename }}, {{ @metadata.extension }}, {{ @metadata.content_type }}: the file name, extension and content type of the source task’s output. For “Create signed upload URL”, they describe the uploaded file.
  • {{ @item }} or {{ @item.field.path }}: the current item of the task’s own loop, available in that task’s input parameters and conditions. Leave source and type empty.
  • {{ @action_bundle.<name> }}: the input parameter <name> of the enclosing action bundle, available to the actions inside it. An action bundle is a reusable group of actions that a workflow runs as one action. For a file parameter, use {{ @action_bundle.<name>.as_file }}. Set type to action_bundle. source isn’t used for this interpolation and can be empty.
  • {{ @var.<name> }}: the workflow owner’s variable <name>, or an empty string if it doesn’t exist. Leave source and type empty.
  • {{ workflow_execution_webhook.<variable_name> }}: the callback URL of the “Wait for trigger” task whose webhook is in dynamic mode with that variable_name. Each execution gets its own URL. Leave source and type empty.
  • {{ sprig.<function>(<arguments>) }}: a function call, as described in Functions. An argument can be a double-quoted string, an integer, a { ... } closure, another function call, or any interpolation above except @var, written without the braces, such as sprig.upper($.name).
All $ JSONPath, @raw, @file.path and @metadata interpolations in a value read the same source, including those passed to functions. In sprig.replace($.old, $.new, $.text), all three paths read that one task. Different parameters can read different tasks. To combine the outputs of two tasks in one value, merge them first with “Transform JSON with jq v2” (phrase_jq_v2/jq), passing one task’s {{ @file.path }} to file and the other’s to file_2, then reference its output. @item, @action_bundle, @var and workflow_execution_webhook don’t depend on source, so they can appear in the same value as interpolations that do. An interpolation that is only a string literal, like {{ "[1, 2]" }} or {{ "true" }}, is parsed as JSON and resolves to the decoded value, here a list and a boolean, not a string. A literal that isn’t valid JSON, like {{ "hello" }}, stays a string. So does a string literal passed to a function. An interpolation that is only an integer, like {{ 42 }}, resolves to that integer.