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

# Use variables, expressions and secrets

> Put ${...} placeholders in node configuration to read message data, start payloads, server values and secrets, and keep secrets out of the stored workflow.

<dl />

**Use this when** a value in a node's `config` must come from somewhere else: a field of the message, what the run was started with, a server setting or a secret. Write `${...}` where the value belongs; the server fills it in just before the node runs.

## Steps

**1. Read the message and the run**

| Placeholder | Resolves to |
| - | - |
| `${payload.a.b}` | A nested field of the message in hand (maps only) |
| `${metadata.key}` | A label on the message, such as `${metadata.signal.decision}` |
| `${start.a.b}` | A field of the run's start payload, readable from every node however far down |
| `${context.name}` | A plain value the caller put in the run context |

A value that is exactly one placeholder keeps its type (`"${payload.count}"` stays a number); inside a longer string the result is text. Force a type with a suffix: `${payload.secs:int}` (`int`, `long`, `double`, `bool`, `string`). The full list is in the [Expressions reference](https://yukta.infenia.com/reference/expressions.md).

**2. Read the server, on an allow-list**

`${env.NAME}` and `${sys.name}` read the server's environment and system properties, but only names with the prefix `YUKTA_VAR_` (`yukta.var.`), a short list of harmless ones (`HOME`, `TZ`, `os.name` and a few more) and names you list in `YUKTA_VARIABLES_ALLOWED`. Names that look like secrets (`PASSWORD`, `TOKEN`, `KEY` and similar) stay blocked even when listed.

```bash theme={"system"}
export YUKTA_VAR_REGION=eu-west
```

Then use `${env.YUKTA_VAR_REGION}` in a node.

**3. Keep a secret out of the definition**

Write the whole value as `decrypted:name`. The server reads the environment variable `YUKTA_SECRET_` plus the name upper-cased, every other character turned into `_`. `decrypted:chat-token` reads `YUKTA_SECRET_CHAT_TOKEN`; a session or tenant scope is possible (see the reference).

```bash theme={"system"}
export YUKTA_SECRET_CHAT_TOKEN=xoxb-example   # in the server's environment
```

```json theme={"system"}
{ "nodeId": "notify", "type": "HTTP_REQUEST",
  "config": {
    "url": "https://chat.example.com/hooks/ops", "method": "POST",
    "headers": { "Authorization": "decrypted:chat-token" },
    "body": { "text": "Build ${payload.build} finished with ${payload.status}" } } }
```

A literal in a field the plugin declares secret is refused when the workflow is saved or run, so a pasted token cannot slip into a stored definition ([Security reference](https://yukta.infenia.com/reference/security.md)).

**4. Use an expression where a plugin takes one**

Branch cases, filter conditions, mapper projections and loop exit conditions are expressions, not placeholders. They read the message through `payload` and `metadata`:

```text theme={"system"}
payload.coverage >= 80 && payload.lintErrors == 0
```

Only a short list of safe methods is allowed and each evaluation has a time limit.

## Verify it worked

Start a run with `{"build":"42","status":"passed"}` and open the run log: the node's request body reads `Build 42 finished with passed`, and the token appears nowhere in the stored workflow (`GET /api/sessions/{id}/config`). A placeholder that finds nothing gives an empty value; a configuration that cannot be resolved at all, or a missing secret, fails that message like any plugin failure, so retries and error routing apply.

## Variations

* **Numeric options.** Write them as typed placeholders (`${payload.secs:int}`); an unknown value such as a timeout is applied when the first message arrives.
* **Scripts.** The `MAPPER` `SCRIPT` mode runs JavaScript with time and statement limits ([Transform plugins](https://yukta.infenia.com/reference/plugins/transform.md)).

## Related

* [Expressions reference](https://yukta.infenia.com/reference/expressions.md) for every source, suffix and limit.
* [Secure the server](https://yukta.infenia.com/guides/operate/secure-the-server.md) for keys and roles.


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