Skip to main content
View as Markdown

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.

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.
actions Ordered array of action steps (minimum 1). Steps run sequentially unless a path/loop action branches. See Actions Overview.
retry Automation-level retry policy applied to the whole run. See 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.

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.
Connection $connection.NAME Resolved credentials for an external service. See 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
app.connections Stored credentials for authenticated HTTP/AI calls. Connections
app.env Declared environment variables / secrets. Env Vars