Automation Actions

What It Is

This chapter is the action reference for the Automation Builder.

Actions are the building blocks of automation workflows. Each action is an atomic unit that performs a specific operation, accepts input parameters, and routes execution flow through endpoints. Actions can be chained and nested to build complex workflows.

Why It Matters

Understanding the available actions and their parameters is essential for building automations. Each action has:

• Input parameters: values that configure the action's behavior, written as CodeProcessor expressions
• Endpoints: named exit points that define what happens next (e.g. on success, on error, on completion)
• Endpoint-provided parameters: values produced by the action that downstream actions can read via endpoint("name")

Action Groups

Actions are organized into the following groups:

1. Control Structures
2. Loops
3. Variables
4. Database
5. Object Operations
6. Files
7. Notifications & Mailing
8. Network Communication
9. Front-end UI Control
10. System
11. AI

---

Control Structures

Condition

Evaluates a single boolean expression and routes execution to either the If true or If false endpoint. The expression is a CodeProcessor expression — write the entire condition inline using any operators, comparisons, function calls and logical combinators (&&, ||, !).

Prefer Condition over IF for new automations. Compound logic stays in one expression instead of being spread across chained IF nodes connected via the OR endpoint.

Examples:

trigger("user").age >= 18
trigger("object").status == "approved" && var("country") == "US"
changedFrom("status", "open")
compareDates(get('due_date'), today(), 'lt')

IF

Legacy two-operand comparison. Evaluates a condition by comparing two operands with a chosen operator. Routes the flow to the If true or If false endpoint accordingly. Multiple IF actions can be chained via the OR endpoint to build compound conditions.

For new automations use Condition instead. A single condition expression like trigger("user").age >= 18 && var("country") == "US" replaces the chain of IF + OR nodes that the two-operand model forces. IF is kept for backward compatibility with existing automations.

Available operators: =, >, >=, <, <=, !=, contains, containsKey, isIn, isTrue, isFalse, isNull, isIterable, isFile, isEmail, isEmpty.

Switch

Multi-way branch. Tests value against each item in the cases list and routes execution to the endpoint corresponding to the first matching case. If no case matches, routes to the Default endpoint. Functionally equivalent to a chain of IF actions, but the builder renders one endpoint per case, so the resulting automation is compact and intent is easier to read.

Comparison uses PHP's loose equality (==). Only the first matching case is triggered; subsequent matches are ignored (standard switch semantics).

Modes

cases supports two addressing modes, and both can be mixed in the same list:

Positional (value-based). Entries with integer (or omitted) keys are matched and addressed by their value. Endpoint identity is derived from a hash of the value, so identical values always map to the same endpoint. Only scalar values (string, int, float, bool, null) are accepted in this mode; non-scalar entries are silently skipped.

value = status
cases = ['approved', 'pending', 'rejected']

Produces three endpoints: Case: approved, Case: pending, Case: rejected.

Keyed (label-based). Entries with string keys are matched by their value but addressed by their key. Endpoint identity is derived from a hash of the key, so every entry gets its own endpoint regardless of what its value evaluates to. Any value type is accepted — scalars, objects, arrays, whatever == can compare.

This is the mode to use for the switch(true) { case expr1: ... case expr2: ... } pattern, where the value under test is simply true and each case is a boolean expression. In positional mode all true cases would collapse to a single endpoint; in keyed mode each rule keeps its own endpoint and its own label.

value = true
cases = [
    'adult'       => $age >= 18,
    'us_customer' => $country === 'US',
    'premium'     => $premium === true,
]

Produces three endpoints: Case: adult, Case: us_customer, Case: premium. The first entry whose value loosely equals true fires.

Positional and keyed entries can coexist in one list:

cases = [
    'legacy'   => $record->legacy === true,
    'approved',
    'pending',
]

Endpoint identity

Each case endpoint uses a content-addressed internal ID:

• Positional mode: case_<hash-of-value>.
• Keyed mode: case_k_<hash-of-key>.

This keeps endpoint IDs stable across reorderings of the list and safe to use as a DOM/URL id regardless of what the key or value contains (spaces, quotes, HTML-special characters, multi-byte text, etc.). The builder surfaces the key or value as the endpoint's name (e.g. Case: approved, Case: adult), so builder UI and run logs remain readable.

Removing a case

If a case is removed from the cases list while actions are still attached to its endpoint, the endpoint is preserved in the builder under the label Case: (removed) until the attached actions are moved or deleted. Nothing is silently dropped.

Editing the cases list

The cases input is flagged to re-render the canvas when its value changes, so new case endpoints appear (and unused ones disappear) without reloading the page.

Async Waitpoint

Pauses the automation flow and waits for an external callback. A unique callback URL and token are generated that an external system can POST to in order to resume the flow. Supports an optional timeout.

Run Action (GoTo)

Runs the specified target action and anything within its endpoints. Does not continue the flow after the target action, and returns to the calling point.

Return Value

Immediately terminates the current automation and returns a value to the parent automation that called it (via Run Automation). The parent receives the returned value in the Output endpoint parameter.

Abort Parent Operation

Aborts the parent API operation (e.g. a create, update, or delete triggered by an API event). The operation that triggered this automation will be cancelled. Useful for validation or permission checks that should prevent the parent operation from completing.

No input parameters. No endpoints.

Terminate Automation

Immediately stops the entire automation. No further actions or endpoints are executed after this point.

No input parameters. No endpoints.

Prevent Iteration Over Selection

When an automation is invoked on a selection of objects, the system normally iterates over each selected item and runs the automation for each one individually. This action prevents that iteration, so the automation runs only once for the entire selection.

No input parameters. No endpoints.

---

Loops

For Each

Iterates over an iterable value (array, collection, etc.) and executes the With each iteration endpoint for every item. Supports Break loop and Continue loop actions inside the loop body.

While

Repeats execution as long as the Iteration step value evaluates to a truthy value. The value is re-evaluated before each iteration. Supports Break loop and Continue loop actions inside the loop body.

Break Loop

Immediately exits the nearest enclosing For each or While loop. No further iterations are executed.

No input parameters. No endpoints.

Continue Loop

Skips the rest of the current iteration and jumps to the next one in the nearest enclosing For each or While loop.

No input parameters. No endpoints.

---

Variables

Assign a Variable

Sets an automation variable to the specified value. If the variable already exists, its value is overwritten. Variables are accessible throughout the automation via var("variableName").

Append Value to a Variable

Appends a value to an existing automation variable (typically an array). If the variable does not exist yet, it is created.

Set Template Variable

Sets a variable on the current front-end template (Latte). The variable becomes available in the rendered template as $variableName. The variable name must be a valid PHP identifier.

Update by Reference

Updates a single property on an object by reference. The change is applied directly to the in-memory object without saving to the database.

Patch by Reference

Updates multiple properties on an object by reference in a single action. Changes are applied directly in memory without saving to the database.

---

Database

Query

Executes a raw SQL query against the database. SELECT queries can optionally return results as ActiveResource objects.

---

Object Operations

Create Object

Creates a new object of the specified type. Optionally saves it to the database immediately.

Get Object

Retrieves a single object by its ID, UUID, or system name.

List Objects

Retrieves a list of objects of the specified type. Filter using either a saved Query or inline Conditions.

Update Object

Updates an existing object with new data. Provide the object directly or look it up by type and ID.

Delete Object

Deletes an existing object from the database. Provide the object directly or look it up by type and ID.

Perform Object Action

Triggers a registered action on an object (e.g. a custom button action defined on an object type). Provide the object directly or look it up by type and ID.

Convert Object

Creates a new object of a different type by duplicating data from an existing object. Non-persistent system fields (id, timestamps, etc.) are excluded automatically.

---

Files

Store Local File

Saves a file to a local storage location.

Write to Local File

Writes data to a file in local storage. Can create a new file or update an existing one.

Read Local File

Retrieves the contents of a locally stored file.

Initiate a File Download

Initiates a file download for the user.

---

Notifications & Mailing

Send an E-mail

Sends an e-mail using either a saved e-mail template or an inline message body. Supports multiple recipients, attachments, and template variables.

Send a Notification

Sends an in-app system notification to a specific user, group, role, or custom recipient.

Send an Expo Notification

Sends a push notification to a mobile device via the Expo Push Notification service.

Send an SMS

Sends an SMS text message via the configured SMS gateway.

---

Network Communication

Send HTTP Request

Sends an HTTP request to an external URL. Supports all common HTTP methods.

Send JSON Response

Sends a JSON response back to the client. The content type is set to application/json.

Send Response

Sends a response with a custom content type. More flexible than Send JSON Response.

Publish Server-Sent Event

Publishes a message to one or more SSE channels via Redis. Clients subscribed to the channel receive the message in real time.

Load Data from ARES

Looks up a Czech company in the ARES (Administrative Register of Economic Subjects) by its identification number (ICO).

Iterate JSON Stream

Streams a JSON document from a URL and iterates over its items without loading the entire response into memory. Uses JSON Machine for memory-efficient parsing.

---

Front-end UI Control

Flash Message

Displays a temporary flash message to the user.

Banner Message

Displays a persistent banner message in the page template. Unlike flash messages, banners remain visible until the page is reloaded.

Redirect App

Redirects the user to a different page or URL. Supports both internal presenter destinations and full external URLs.

Hide Last Modal

Closes the most recently opened modal dialog in the front-end.

No input parameters. No endpoints.

Reload UI Components

Triggers a full reload of all UI components on the current page.

No input parameters. No endpoints.

Run JavaScript

Executes arbitrary JavaScript in the user's browser at the end of the current request. The code is appended to the response payload and runs after the page renders (full page load) or after the next AJAX snippet update (signal/AJAX request).

A helper namespace window.Jetstack is available to the injected code, with small shortcuts for the most common UI commands so callers don't need to reproduce the Bootstrap markup:

Referencing UI components (data-soopio-id)

Soopio stamps a data-soopio-id attribute on a handful of rendered surfaces so Run JavaScript code can reliably find them. Use Jetstack.getElement(id) / Jetstack.getElements(id) to retrieve them.

Auto-generated IDs:

The <typeSystemName> is the type's system_name (e.g. User, Article); it falls back to the numeric type id only when no system_name has been set on the type.

Author-controlled IDs:

• Canvas items — set a "Public ID" on any canvas item via the builder (link-icon button next to Change title). The wrapper <div> gets data-soopio-id="<your-id>", overriding any auto-generated ID for that item. Inside an iterator, each rendered row is suffixed: <your-id>#<iteratorUniqueId> — use Jetstack.getElements(id) to match them all, or include the exact suffix to target a single row.
• Flash / Banner messages — pass a publicId input parameter (or { publicId } option to the JS helper). The toast/banner carries data-soopio-id="<your-id>".

Author-chosen IDs are free-form strings. Uniqueness within a page is the author's responsibility. Auto-generated IDs are applied only when the author has not set a Public ID.

Beyond these helpers, any browser API, jQuery, or Bootstrap JS call is available. Example — force-open a specific collapsible on the page:

const el = document.getElementById('editProfileCollapse');
if (el && !el.classList.contains('show')) {
    document.querySelector('a[href="#editProfileCollapse"]')?.click();
}

Caveats:

• allowRepeat is on by default, so the same code runs every time the action fires. Untick it to enable per-page hash deduplication — identical code blocks will then execute only once per page lifetime.
• If the triggering request produces no HTML response (pure redirect, background task, JSON-only response with no script payload channel), the code is not delivered.
• The code runs with full page privileges — it is author-trusted, same as Canvas scripts. Treat code as privileged content.

---

System

Schedule a Task

Schedules an automation to run at a specific time in the future. Supports recurring execution.

Cancel a Task

Cancels a previously scheduled task.

Run Automation

Executes another automation synchronously within the current flow. If the called automation uses a Return Value action, the returned value is available in the Output endpoint parameter.

Add Object Action

Dynamically adds a custom action button to an object at runtime. The action appears in the object's context menu and top buttons area.

Create a PDF

Generates a PDF from a Canvas template. Uses Browsershot (headless Chrome) for rendering by default, with Dompdf as a fallback.

Log Event

Creates an entry in the system event log.

Dump Data to Local Storage

Writes a JSON-encoded message to the tenant's local log file.

Bar Dump

Dumps a variable to the Tracy debug bar for inspection. Only visible to superuser roles when the debugger is enabled.

PHP

Executes custom PHP code in a sandboxed environment. The code has access to the Internal API and any input parameters.

Convert Markdown to HTML

Renders a Markdown source string as HTML using the league/commonmark library.

Convert HTML to Markdown

Converts an HTML string to Markdown using the league/html-to-markdown library.

Login As User

Impersonates another user by switching the current session. Requires the loginAs system permission and the target must be a subordinate by role hierarchy.

---

AI

Prompt a Model

Calls an external AI model and stores results into automation variables. Prompts support template placeholders like {{vars.myVar}} and {{steps.output}}.

---

Common Endpoints

Most actions inherit three standard endpoints from the base action class:

Some actions do not inherit these standard endpoints because they serve a specific purpose that does not fit the success/error/complete pattern. These include: Redirect, Bar dump, Hide last modal, Reload UI components, Dump data to local storage, Log event, and Publish Server-Sent Event.

Practical Design Guidance

• Start with Object Operations and Control Structures. Most automations center on reading, creating, or updating objects, with IF conditions and loops directing the flow.
• Use Variables to simplify complex workflows. When several actions depend on the same derived value, assign it to a variable once rather than repeating the expression.
• Prefer Run Automation over duplicating action sequences. Extract reusable logic into a separate automation and call it with Run Automation. Use Return Value to pass results back.
• Choose the right notification channel. Use Flash Message for immediate UI feedback, Send a Notification for persistent in-app alerts, Send an E-mail for external communication, and Publish Server-Sent Event for real-time front-end updates.
• Use Abort Parent Operation for validation. When an automation is triggered by a create or update event and the operation should be prevented, use Abort Parent Operation rather than trying to reverse the change.
• Schedule deferred work with Schedule a Task. When work should happen later or recurrently, schedule it rather than blocking the current request.
• Debug with Bar Dump and Dump Data to Local Storage. Use Bar Dump for interactive debugging during development and local storage logging for production troubleshooting.

Related Chapters

• Automations
• Automation Triggers
• Expressions
• Code Processor Functions
• Scope Resolvers