{{ ... }} 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$.messageis a JSONPath. It runs against the output of the task or trigger insource. That output has the shape of theoutput_json_schemareturned byGET /actions/{id}andGET /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: whatsourcepoints 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@itemand@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 insource depends on the endpoint:
- In a
workflow_definition(POST /workflows), use theslugyou gave the action underactions, or the literaltrigger. - On the per-task endpoints (
POST /workflows/{workflow_id}/revisions/{revision_id}/tasksandPATCH /workflows/{workflow_id}/revisions/{revision_id}/tasks/{id}), use the task’sid, a UUID returned by the task endpoints, or the trigger’sid, returned byGET /workflows/{workflow_id}/revisions/{revision_id}/trigger. These endpoints don’t resolve slugs or the literaltrigger.
fetch_user reference from the example above uses that task’s id:
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 parametervalue 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 insource. Withtypetask, that is the task’s output body. Withtypetrigger, it is the trigger data. Withtypetask_header, it is the task’s response headers, with header names in lower case, such as{{ $.content-type }}. A missing field resolves tonull.{{ @raw }}or{{ $ }}: the whole output of the task or trigger insource.{{ @file.path }}: the content of thesourcetask’s output file, which is the same content as{{ @raw }}. Use it for file parameters, such asfileandfile_2of “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 tonull, so use{{ @raw }}there.{{ @metadata.filename }},{{ @metadata.extension }},{{ @metadata.content_type }}: the file name, extension and content type of thesourcetask’s output. For “Create signed upload URL”, they describe the uploaded file.{{ @item }}or{{ @item.field.path }}: the current item of the task’s ownloop, available in that task’s input parameters and conditions. Leavesourceandtypeempty.{{ @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 }}. Settypetoaction_bundle.sourceisn’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. Leavesourceandtypeempty.{{ workflow_execution_webhook.<variable_name> }}: the callback URL of the “Wait for trigger” task whose webhook is indynamicmode with thatvariable_name. Each execution gets its own URL. Leavesourceandtypeempty.{{ 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 assprig.upper($.name).
$ 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.