Automations

What It Is

An automation is Jetstack's configurable workflow and business logic surface. It stores trigger configuration, variables, serialized action content, draft state, execution counters, role restrictions, and trigger-aware runtime behavior.

Why It Matters

Automations are where the platform stops being only a configured data application and becomes a working process system.

They are used for:

  • event reactions
  • form handling
  • button handling
  • routines
  • scheduled work
  • webhook handling

Automation Roles

Jetstack distinguishes these main automation roles:

  • general
  • event handlers
  • form handlers
  • button handlers
  • routines
  • scheduled actions
  • webhooks

The role does not change the automation engine itself, but it strongly affects how the automation is expected to be used and understood.

Key Configuration Surface

Identity

  • automation_name
  • description
  • trigger_preview

Access And Availability

  • restricted_to_roles
  • is_active

Runtime Definition

  • trigger
  • variables
  • content

Draft State

  • trigger_draft
  • variables_draft
  • content_draft
  • draft_saved

Operational Metrics

  • last_run
  • run_count

Trigger Model

Automations are driven by trigger configuration plus runtime-provided arguments. Depending on the trigger source, the automation may receive:

  • app context
  • current object or action context
  • event parameters
  • scheduler arguments
  • webhook payload-related values

The trigger itself is defined only in the Automation Builder, using:

  • a trigger resource
  • optional selectors
  • an event exposed by that resource

For the detailed reference of trigger resources, selector behavior, event groups, and trigger parameters, see Automation Triggers.

Variable Model

Automation variables help keep the action graph understandable. Use them when:

  • several actions depend on the same derived value
  • an expression is too complex to repeat safely
  • the workflow benefits from naming an intermediate business concept

Content And Action Graph

The automation stores its action graph as serialized content. At runtime, Jetstack rehydrates the action structure and resolves previous action links, trigger-aware parameters, and endpoint chains.

This matters because action sequencing and parameter scope are part of the automation contract, not just builder convenience.

Building The Action Graph

The builder is canvas-based. Actions are added on demand — there is no permanent action library taking up screen space.

The list of available actions lives in a small floating popover that opens only when the implementer asks for it. Picking an action is a click, not a drag — the chosen action is inserted directly into the slot that opened the gallery, so context is never lost.

A + chip appears next to every place an action can legitimately go. Chips fade in only when the relevant node is hovered, so a finished graph reads cleanly:

  • Start node — the chip below the start anchor adds the first main action.
  • Empty endpoint — the chip beside an empty endpoint anchor adds the first action inside that endpoint.
  • Below an action's last successor — the chip below an action adds the next action in its sequence.
  • Midway along a connection line — hovering a connection line surfaces a midpoint chip. Clicking it inserts the new action between the two existing nodes:
    • on a structural line (start → first main, endpoint → first child, action → next), the new action takes the head position of that slot and the previous occupant is pushed one step further down the chain;
    • on a goto link, the goto is split: the new action takes the slot the goto used to occupy, and a fresh goto is created from the new action onward to the original target. If the new action exposes no sequence slot, the chain ends at it.
  • Empty canvas — double-clicking empty canvas opens the gallery in standalone-creation mode. The picked action becomes a standalone (orphan) at the click point.

What The Builder Does Around The Insert

Inserting through any chip stays inside the slot's contract:

  • the new action is wired into its parent scope at the right position (head, between, or end);
  • any goto link that was holding the slot open is removed automatically — slots are single-valued;
  • the saved canvas position for the new node is seeded close to where it will end up. When the new node would land on top of an existing successor, it is offset slightly to the right so both stay readable until the implementer drags either.

Editing And Re-Arranging

Existing nodes can still be dragged between scopes (endpoint → endpoint, sequence → sequence, etc.) using the connection anchors at the card edges. Drag is reserved for re-arranging; adding is always click-driven.

Deleting Actions

Deleting an action removes it from its scope but does not destroy its endpoint children. Each direct child is promoted to a standalone (orphan) action and stays at its current canvas position. This:

  • preserves work — a deletion in the middle of a graph is non-destructive for everything nested inside;
  • keeps goto links pointing at any of those children intact, since the children survive;
  • removes only the goto links whose source or target was the deleted node, since those references are now stale.

If the implementer wanted the children gone too, they delete them explicitly afterwards.

This rule applies whether the deleted action sits in the main flow, inside an endpoint, or is itself a standalone — children are always kept and re-parented as standalones.

Most automations are trees: the trigger fans out into a sequence of actions, endpoints branch into nested actions, and control flows top-down. Goto links and standalone actions extend that model for the cases where a strict tree gets in the way.

A goto link redirects control from one point in the graph to any other action on the canvas.

Where a link can start. Only outgoing slots that have no regular successor are eligible:

  • the trigger's start output, when the automation has no main actions
  • an endpoint anchor whose body is empty
  • the "next" anchor below an action that is last in its scope

A small handle appears on hover over an eligible anchor. Dragging it onto another action creates the link. Filling a slot with a real successor — by inserting an action through that slot's + chip, or by moving a branch into it — automatically removes any goto that was attached to that slot, since slots are single-valued.

Goto lines also expose the same midpoint + chip as structural lines. Inserting on a goto splits the chain: the new action takes the source slot, and a replacement goto from the new action onward keeps the chain converging on the original target (when the new action has a sequence slot to attach to).

Runtime semantics: siblings only. When control reaches a goto link, it jumps to the target action and executes it, then runs the target's immediate scope-siblings in order. Once that scope is exhausted the automation ends. Control does not walk back up to resume the parent scope where the goto originated.

This rule keeps goto-based flows understandable: a link is a handoff, not a temporary detour. To run something and come back, use the existing "Run action" action instead — it remains the right tool for that case.

When to use goto links.

  • an error endpoint should abandon the normal flow and finish in a different recovery sequence
  • a condition's true/false branches both need to merge into the same tail sequence
  • an empty endpoint should simply redirect control elsewhere without nesting

When not to use them.

  • if the "goto" should return afterwards — use "Run action"
  • if the jump is really about conditional sequencing within the same scope — structure it with an endpoint instead, so the graph reads top-down

Standalone Actions

A standalone (orphan) action lives on the canvas without a parent. The main run loop does not iterate standalone actions; they only execute when a goto link points at one. Once reached, a standalone action behaves like any other — it can have endpoints, nested actions, and its own outgoing goto links.

There are two ways to end up with a standalone:

  • Create one explicitly. Double-click an empty area of the canvas to open the action gallery in standalone-creation mode. The picked action becomes a standalone at the click point and is shown with a dashed border.
  • Promote on delete. Deleting an action that has endpoint children leaves each direct child alive as a standalone, keeping their current positions. This is how a deletion can shed surrounding scope without losing the work nested inside.

Dragging a standalone back into a regular slot anchor converts it into a main or nested action, and any goto link that targeted it continues to work.

Use standalone actions to:

  • collect a recovery or cleanup sequence that should run only when explicitly reached
  • keep rarely-taken branches off the main flow for readability
  • stage work in progress without wiring it in yet
  • preserve children of a node you are deleting, so the surrounding structure can be re-shaped without throwing nested logic away

Example

An order-processing automation validates an order, charges the card, and finishes with a receipt email. If the charge fails, the "error" endpoint of the charge action links to a standalone "Refund and notify customer" sequence. Control leaves the normal flow, the refund sequence runs, and the automation ends — no receipt is sent.

Best Practices

  • Prefer ordinary sequencing and endpoints first; reach for goto links only when the flow genuinely has to abandon its current path.
  • Name the target action clearly ("Handle payment failure") — a goto curve is easy to miss, and a readable target title is the main cue for future readers.
  • Keep standalone sequences self-contained. If a standalone action needs context from the caller, it should read it from variables, not rely on scope.

Action Workspace

What It Is

Each action opens its own workspace — a three-column surface that combines parameter editing, last-run input inspection, and endpoint inspection in one place. The workspace is the canonical surface for designing, debugging, and trying a single action, and it opens by clicking an action card or double-clicking it on the canvas.

Why It Matters

Configuring an action well means looking at three things together: what the action receives, how it processes that input, and what it dispatches on the way out. Splitting these into separate dialogs forces the implementer to remember context that could be visible at a glance. The workspace puts the same picture the runtime sees in front of the implementer while they edit.

Three Panes

  • Left — Input data. A card per input parameter the action accepts and per non-reserved automation variable. After the automation has been run, each card shows the resolved value the action saw in the most recent run — the actual runtime value, not the configured expression. Cards are editable: typing a different value overrides it for the next single-node execute without changing the stored automation.

  • Middle — Parameter editor. The action's input parameters, each with a Fixed / Expression mode toggle and a collapsible editor. Edits made here are saved to the automation draft and follow the normal draft/publish flow.

  • Right — Endpoints. A card per endpoint defined on the action. Each card shows whether that endpoint was dispatched in the last run, the parameters that were passed to it, and the child actions wired beneath it. Above the cards, an Execute this node button runs the action in isolation.

The two splitters between columns are draggable and remember their widths between sessions.

Single-Node Execute

The Execute this node button runs only the selected action, using the values shown in the left pane (including any overrides typed there). The action's own logic runs end-to-end, but its endpoints do not propagate — Jetstack records each dispatch and stops there, so child actions never fire. The right pane updates with the result: status, duration, and which endpoints were dispatched with which parameters.

Single-node executes are transient. They are not saved to the automation run history and do not affect run counters.

Use single-node execute to:

  • iterate on one action without re-running the whole automation
  • try the action with synthetic inputs before wiring it in
  • inspect what each endpoint would dispatch for a given input

Override Semantics

Overrides typed in the left pane apply only to the next single-node execute. They are not persisted, do not change the stored expression for that parameter, and do not influence later full-automation runs. Reserved environment variables are not editable.

Empty State

The workspace is useful even before the first run. Without run data, the left pane shows blank editable cards, the middle pane shows the configured parameters, and the right pane lists the endpoints without dispatch markers. The implementer can fill in the left pane and click Execute this node to try the action immediately — the workspace doubles as a "try it" surface from the moment an action is added.

Action Input Parameters

Each action exposes a set of input parameters configured in the middle pane of the action workspace. A parameter has a name, an expected data type, and a value cell where you supply that value.

Default And Specialized Inputs

Two kinds of input controls are used:

  • Default code editor. Most parameters render as a code editor where you type an expression, a scoped value, or a literal. This is the most expressive option and works for every parameter.
  • Specialized input. Some parameters ship with a tailored control — for example, a select box of known values, a PHP editor for custom scripts, or a checkbox for a boolean flag. Specialized inputs make the common case faster to configure, but they can only represent values they were designed for.

Switching Input Mode

When a parameter offers a specialized input, the parameter row shows a small Fixed / Expression toggle next to the parameter's type. It switches that parameter between the specialized input and the default code editor. The choice is stored per parameter in the automation draft, so the same mode is used on every reload.

Use the default code editor when:

  • the value needs an expression the specialized input cannot represent
  • the value references a variable, trigger parameter, or endpoint parameter that requires scoped syntax
  • the stored value was authored in the code editor already and would be misrepresented if rendered as a select or other narrow control

Use the specialized input when the parameter's value is one of the intended, well-known shapes. It is the faster, less error-prone choice for standard configurations.

Persistence And Draft Workflow

Input values and the chosen input mode are stored with the action and participate in the normal draft/publish flow. Changing the input mode creates or updates the draft like any other edit.

Runtime Context

Automations get a dedicated code processor with access to:

  • trigger parameters
  • previous endpoint parameters
  • global variables
  • local variables
  • app parameters
  • current data query
  • secrets provider

This is why automations can act as the main integration and workflow surface for many implementations.

Builder Support

The automation builder uses automation scope resolution to expose:

  • top-level keywords
  • traversable available fields
  • parameterized callable items
  • resolved runtime values

See Scope Resolvers.

Error And Control Flow Considerations

Automations can be interrupted or redirected by exceptions and control-flow mechanisms such as:

  • termination
  • redirect
  • async suspension
  • selection-specific flow changes

Implementers do not need to memorize engine details, but they should understand that automations are closer to runtime workflows than simple "if this then that" rules.

Example

A customer-onboarding automation might:

  1. trigger when a Customer object is created
  2. set intermediate variables for ownership and onboarding date
  3. create related tasks
  4. schedule a follow-up automation
  5. send a welcome email using a template

Design Questions To Ask Before Finalizing An Automation

  • Is the automation reacting to an event, a user action, a schedule, or a public entry point?
  • Does the automation need role restriction?
  • Which values deserve named variables instead of repeated expressions?
  • Should a step happen immediately or through the scheduler?
  • Is a secret-backed integration involved?

Best Practices

  • Use small, composable automations.
  • Keep trigger descriptions and variable names readable.
  • Reserve secrets access for integration-specific steps.
  • Use scheduled automations when work should happen asynchronously or later.
  • Keep builder graphs understandable enough that another implementer can trace the business flow.
Previous← IntroductionNextCanvas Items And Canvas Builder →