> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phrase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pass data through a workflow

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](https://developers.phrase.com/en/api/orchestrator/transform-data-with-functions.md) 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`:

```json theme={null}
{
  "url":  { "value": "https://example.com", "source": "", "type": "" },
  "name": { "value": "{{ $.name }}", "source": "fetch_user", "type": "task" }
}
```

## 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`:

```json theme={null}
{ "name": { "value": "{{ $.name }}", "source": "4b0d6c0e-6f1a-4c43-9a8e-2f7f7f1b9d3a", "type": "task" } }
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.