# Automations Overview

Automations are Sovrium's workflow engine. Each automation pairs **one trigger** (the event that starts it) with an **ordered list of actions** (the steps it runs). When the trigger fires, the actions execute sequentially — passing data forward through template variables — until the workflow completes, stops, or fails.

Automations are declared under the top-level `app.automations[]` array. Triggers react to record changes, schedules, inbound webhooks, auth events, form submissions, manual buttons, sub-workflow calls, other automations' failures, and comments. Actions span more than 20 families: HTTP, record CRUD, email, AI, file operations, flow control, approvals, and more.

```yaml
automations:
  - name: new-order-alert
    label: Notify the team about new orders
    trigger:
      type: record
      table: orders
      events: [create]
    actions:
      - name: notifyTeam
        type: email
        operator: send
        props:
          to: '{{trigger.data.owner_email}}'
          subject: 'New order {{trigger.data.id}}'
          body: 'Amount: ${{trigger.data.amount}}'
    timeout: 60000
```

## Anatomy

An automation has exactly one `trigger` and at least one entry in `actions`. Everything else — timeout, retry, concurrency, tags, permissions, AI exposure — is optional.

| Property      | Description                                                                                                                                                             |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | Unique kebab-case identifier (`^[a-z][a-z0-9-]*$`, max 100 chars). Used in webhook URLs and as the `automation/call` target.                                            |
| `label`       | Human-readable label shown in the admin interface.                                                                                                                      |
| `description` | Free-text description of what the automation does.                                                                                                                      |
| `enabled`     | Boolean. When `false`, the automation is registered but never fires. Defaults to `true`.                                                                                |
| `trigger`     | The single event that starts this workflow. See [Triggers](/en/docs/automation-triggers).                                                                               |
| `actions`     | Ordered array of action steps (minimum 1). Steps run sequentially unless a `path`/`loop` action branches. See [Actions Overview](/en/docs/automation-actions-overview). |
| `retry`       | Automation-level retry policy applied to the whole run. See [Retry & Failure](/en/docs/automation-retry-failure).                                                       |
| `timeout`     | Total run timeout in milliseconds (1000–900000, default 300000).                                                                                                        |
| `concurrency` | `{ limit }` — max simultaneous runs of this automation (1–50). See concurrency note below.                                                                              |
| `tags`        | Array of strings for organizing and filtering automations.                                                                                                              |
| `permissions` | `{ trigger }` — who can manually invoke this automation (`all`, `authenticated`, or a role array).                                                                      |
| `aiAccess`    | Declares a **manual-trigger** automation as invokable via Sovrium's MCP server. Setting it on a non-manual trigger is a decode error.                                   |

:::callout
**Data flows between steps via template variables.** Reference the trigger payload with `{{trigger.data.fieldName}}`, a prior step's output with `{{stepName.result}}`, an environment secret with `$env.VAR_NAME` (never logged), and a stored credential with `$connection.NAME`. See [Template Helpers](#template-variables) below.
:::

## Template Variables

Every string prop in an action can interpolate runtime values. The resolution sources are:

| Source           | Syntax                     | Notes                                                                                                                               |
| ---------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Trigger payload  | `{{trigger.data.field}}`   | The data the trigger carried (record row, webhook body, form values, …).                                                            |
| Previous step    | `{{stepName.result}}`      | The output of any earlier action, referenced by its `name`.                                                                         |
| Environment var  | `$env.VAR_NAME`            | Resolved from `app.env`. Redacted in logs. See [Env Vars](/en/docs/automation-env-vars).                                            |
| Connection       | `$connection.NAME`         | Resolved credentials for an external service. See [Connections](/en/docs/automation-connections).                                   |
| Helper functions | `{{helperName arg "lit"}}` | 100+ formatting helpers (text, number, date, logic, collection, encoding). Nest with parentheses: `{{uppercase (trim step.text)}}`. |

## Concurrency

Each automation has an independent FIFO semaphore. When `concurrency.limit` is set, incoming triggers beyond the limit are persisted as `queued` and promoted to `running` as in-flight slots free. Without the block, the global `AUTOMATION_CONCURRENCY_DEFAULT` env (default 5) applies. Queueing is in-memory and single-process — designed for Sovrium's single-tenant deployment model.

## Configuration Surface

Automations sit alongside three sibling top-level blocks that they routinely reference:

| Block             | Purpose                                                    | Page                                                     |
| ----------------- | ---------------------------------------------------------- | -------------------------------------------------------- |
| `app.automations` | The workflows themselves.                                  | this page                                                |
| `app.actions`     | Reusable action templates referenced via the `ref` action. | [Actions Overview](/en/docs/automation-actions-overview) |
| `app.connections` | Stored credentials for authenticated HTTP/AI calls.        | [Connections](/en/docs/automation-connections)           |
| `app.env`         | Declared environment variables / secrets.                  | [Env Vars](/en/docs/automation-env-vars)                 |

## Related Pages

- [Triggers](/en/docs/automation-triggers) — all 9 trigger types.
- [Actions Overview](/en/docs/automation-actions-overview) — the action model and the ~22 families.
- [Runs](/en/docs/automation-runs) — monitoring execution history and statuses.
- [Retry & Failure](/en/docs/automation-retry-failure) — retry policies, timeouts, idempotency.
- [Connections](/en/docs/automation-connections) — OAuth2, API key, basic, bearer credentials.
- [Environment Variables](/en/docs/automation-env-vars) — secrets for automations.