Automations — Reference
The Automations surface is the event-driven workflow plane for SGEN. It owns the catalog of platform events automations can listen for, the per-automation trigger configuration, the ordered chain of actions an automation runs in response, the run history that records every fire and every per-action outcome, and the rate-limit and de-duplication layer that prevents runaway loops. Anything that asks "when X happens, do Y" traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before scripting against it, extending the event catalog or the action catalog, or scoping a multi-system orchestration. Customer-facing automation walkthroughs live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Automations live under the Automations module in SG-Admin. The module renders four primary views — the automation list (every configured automation on the site, with state and run statistics), the automation editor (a trigger picker plus a sortable action chain), the run history (per-fire records with per-action outcomes and timing), and the catalog views for events and actions (the underlying primitives an automation composes from).
The module is paired by convention with the Notifications, Integrations, and Tools surfaces. Actions that send email or SMS hand off to Notifications; actions that call external APIs hand off to Integrations through the configured connector; actions that record audit-adjacent events feed into Tools. The Automations module owns the orchestration; the consuming surfaces own the per-channel work.
A second surface — conditional branching — extends the model. An automation's action chain is not strictly linear. Each action carries an optional condition that gates whether the action runs. Conditions evaluate against the triggering event's payload, the prior actions' outcomes, and the current context (current operator, current site, current date / time). A failed condition skips the action; subsequent actions continue.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Automations
- URL prefix:
/sg-admin/automations/ - View templates:
application/views/Admin/Automations/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Automations [+ New automation]│├──────────────────────────────────────────────────────────────────────┤│ Name Trigger Runs Last fired││ ────────────────────────── ───────────────── ───── ──────────││ Welcome new subscriber signup.completed 88 2 min ago ││ Tag editorial drafts post.saved.draft 24 1 hr ago ││ Notify on big purchase order.placed 142 8 min ago ││ Sync to CRM on new contact contact.created 16 3 hr ago ││ On publish: send to socials page.published 58 yesterday ││ Recover abandoned cart cart.idle.30min 203 now ││ ││ [⋯ Edit] [⋯ View runs] [⋯ Pause] [⋯ Duplicate] [⋯ Delete] │└──────────────────────────────────────────────────────────────────────┘Actions
The Automations surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List automations
Returns every automation configured on the site. Each row carries the automation name, the trigger event, the current state (enabled, paused, error), the total run count, the recent fire timestamp, and the success rate over the rolling run window.
View automation
Loads a single automation record with the trigger configuration, the action chain (in order), and the recent run summary (last 20 fires with per-action timing).
Create automation
Opens an empty automation form. The form prompts for a name, a description, the trigger event (from the event catalog), the trigger filter (optional clauses that narrow when the trigger fires — only orders over a threshold, only subscribers from a specific signup form), and the initial action chain (one or more actions from the action catalog, with per-action configuration).
Edit automation
Loads an existing automation into the editor. Changes to trigger, filter, or action chain apply to subsequent fires; in-progress runs continue with their original configuration to completion. Disabling an automation is a separate state change — editing does not implicitly disable.
Pause automation
Marks an automation paused. Paused automations do not fire on incoming events. The pause survives platform restarts. Useful for diagnosing a runaway automation or for temporarily disabling a workflow during a maintenance window without deleting the configuration.
Resume automation
Reverses a pause. The automation returns to enabled state and fires on the next matching event. Events that occurred during the pause are not retroactively replayed — pause is a forward-acting state, not a queue.
Run automation manually
Fires an automation against a synthetic payload. The form accepts a JSON payload matching the trigger event's schema and runs the action chain against it. Per-action outcomes return in the same shape as a real fire. Useful for testing an automation's wiring before enabling it for live events.
View run
Loads a single run record with the triggering event payload, the action chain, the per-action outcome (success, failure, skipped by condition), the per-action duration, and any error detail returned by an action.
Search runs
Returns run records filterable by automation, outcome, time range, and triggering event. Each row links to the full run view. Useful for diagnosing intermittent failures and for compliance review of cross-system orchestration.
Add action to chain
Inserts an action into an automation's chain at a chosen position. The form prompts for the action type (from the action catalog), the per-action configuration (the action type's schema fields), and the optional condition that gates whether the action runs at fire time. Saving the action updates the automation's chain and applies to subsequent fires.
Remove action from chain
Deletes an action from a chain. The chain's positions re-number; subsequent actions advance. The automation's overall configuration is otherwise unchanged.
Reorder actions
Moves an action up or down within the chain. Drag-place in the editor calls this action repeatedly as the operator drags. The order matters — actions earlier in the chain produce outcomes that later actions can condition on or reference.
Duplicate automation
Copies an existing automation (including trigger, filter, action chain, and per-action conditions) into a new record. The copy starts in the disabled state so the operator can adjust before enabling. Useful for parallel workflows with small configuration deltas.
Data model
An event identifier carries the following fields. The event catalog is owned by the platform — new event identifiers ship with module updates.
| Field | Type | Notes |
|---|---|---|
slug | string | Event identifier — signup.completed, post.saved.draft, order.placed, page.published. Stable across releases. |
module | string | The module that emits the event. |
display_name | string | Display label rendered in the trigger picker. |
description | string | One-line description of what triggers the event. |
payload_schema | JSON | Field schema for the event payload — field name, type, description. Used by the trigger filter editor and by action conditions to reference payload fields. |
is_archived | boolean | True for retired event identifiers. Existing automations continue to fire if the event is still emitted. |
| Field | Type | Notes |
|---|---|---|
slug | string | Action identifier — email.send, tag.add_to_contact, webhook.post, record.update, delay.wait. |
category | enum | notification, data_mutation, external_call, flow_control. |
display_name | string | Display label rendered in the action picker. |
description | string | One-line description of what the action does. |
configuration_schema | JSON | Field schema for action instances — field name, type, default, validation. |
is_archived | boolean | True for retired action types. Existing chain entries continue to run. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
name | string | Operator-chosen automation name. |
description | string | Optional. Surfaced in the list and the editor. |
state | enum | enabled, paused, error. |
trigger_event_slug | string | Event identifier. Join key against the event catalog. |
trigger_filter | JSON | Optional clauses that narrow when the trigger fires. |
action_chain | JSON | Ordered array of action entries. Each entry carries action_type_slug, configuration, condition, and a position. |
rate_limit | JSON | Optional. max_fires_per_window + window_seconds. Prevents runaway loops. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
automation_id | integer | The automation that fired. |
fired_at | timestamp | Set at fire time. |
triggering_payload | JSON | The event payload that triggered the fire. |
outcome | enum | success, partial_failure, failure, skipped_rate_limit, skipped_filter. |
action_outcomes | JSON | Per-action result. Each entry carries position, action_type_slug, outcome (success / failure / skipped), duration_ms, and optional error_detail. |
total_duration_ms | integer | End-to-end run duration. |
skipped_filter outcome and does not run the action chain.Action chain semantics: actions run in position order. Each action's outcome is recorded against the run. A failing action does not by default stop the chain — subsequent actions continue, and the run's overall outcome is marked partial_failure. The default can be overridden per chain — a stop_on_failure flag on the automation switches the chain to abort on first failure. Earlier actions' outcomes are referenceable in later actions' conditions and configurations through a templating syntax.
Conditional action semantics: each action carries an optional condition that gates whether the action runs. Conditions evaluate against the triggering payload, prior action outcomes, and the current context. A failing condition records a skipped outcome for the action; the chain continues. Conditions use the same selector / operator / value shape as widget show rules — for example, payload.order_total > 5000 or prior_action_succeeded(position=2).
Rate-limit semantics: an automation can carry a rate limit — maximum fires per rolling window. A fire that would exceed the limit records a skipped_rate_limit outcome; the action chain does not run. The default is unlimited; operators can configure a per-automation limit through the editor. Useful for guarding against runaway loops (an action that emits the same event the automation listens for).
De-duplication semantics: the platform maintains a rolling identifier set per automation and skips fires whose triggering payload matches a recent fire by a configured identity key. The identity key is typically the payload's primary entity identifier — for order.placed, the order ID; for signup.completed, the contact email. De-duplication prevents accidental double-fires from event emitters that retry on network errors.
EVENT EMITTED: order.placed { order_id: 4521, total: 8400, currency: "PHP" }│▼┌───────────────────────────────────┐│ Match enabled automations ││ on trigger_event_slug │└─────────────────┬─────────────────┘│▼┌───────────────────────────────────┐│ For each match — evaluate filter ││ filter: total > 5000 ││ payload total = 8400 → PASS │└─────────────────┬─────────────────┘│▼┌───────────────────────────────────┐│ Check rate limit ││ limit: 50 / hour ││ current window count: 12 → OK │└─────────────────┬─────────────────┘│▼┌───────────────────────────────────┐│ Check de-duplication ││ identity key: order_id ││ recent set: not present → OK │└─────────────────┬─────────────────┘│▼┌───────────────────────────────────┐│ Run action chain ││ 1. email.send → success (340ms)││ 2. tag.add → success (45ms) ││ 3. webhook.post → fail (timeout)││ 4. record.update → success ││ outcome: partial_failure │└───────────────────────────────────┘│▼Run record persistedActivity Log entry writtenPermissions
Access to the Automations surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Automations surface. Event emission itself bypasses the admin gate — events are platform-internal and emitted by the originating modules during normal write paths.
Layer 2 — per-action capability. Within SG-Admin, each Automations action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List automations | ✔ | ✔ | ✔ |
| View automation | ✔ | ✔ | ✔ |
| Create automation | ✔ | ✔ | — |
| Edit automation | ✔ | ✔ | — |
| Pause automation | ✔ | ✔ | — |
| Resume automation | ✔ | ✔ | — |
| Run automation manually | ✔ | ✔ | — |
| View run | ✔ | ✔ | ✔ |
| Search runs | ✔ | ✔ | ✔ |
| Add action to chain | ✔ | ✔ | — |
| Remove action from chain | ✔ | ✔ | — |
| Reorder actions | ✔ | ✔ | — |
| Duplicate automation | ✔ | ✔ | — |
| Delete automation | ✔ | — | — |
| Register custom event or action type | ✔ | — | — |
external_call category — webhook out, third-party API call, integration push — carry an additional capability gate: automations.external_call.edit. The gate guards against an operator wiring a chain that leaks site data to an unsanctioned endpoint. Operators without the gate can place internal actions (email, tag, record update) but cannot add a webhook or external API action.Self-trigger protection. The platform detects automations whose action chain emits an event the same automation listens for. Such an automation creates a self-trigger loop. The save flow flags the loop and requires an explicit acknowledgment plus a configured rate limit before persisting. Without the rate limit, the platform rejects the save with a structured rejection.
Cross-automation chain detection. A chain that fires automation A whose actions emit an event that fires automation B whose actions emit an event that fires automation A constitutes an indirect loop. The platform tracks event-to-automation dependencies and flags such chains at save time. Operators can persist the configuration after acknowledgment, but the chain runs under stricter rate-limit defaults.
Audit. Every operator write — create, edit, pause, resume, manual fire, action add, action remove, action reorder, duplicate, delete — emits an Activity Log entry. Run records themselves are recorded in the per-automation run history (with longer retention than the rate-limit window) and surfaced in the run search. The Activity Log records configuration changes; the run history records execution outcomes; the two together provide the full audit picture.
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Automations → "Notify on big purchase" → Run history │├──────────────────────────────────────────────────────────────────────┤│ Filters: [outcome: any ▾] [last 7d] [search payload field] ││ ────────────────────────────────────────────────────────────────────││ Fired at Trigger payload Outcome Duration ││ ─────────────── ────────────────────── ─────────────── ──────── ││ 2026-05-21 14:32 order #4521 ₱8,400 success 480 ms ││ 2026-05-21 14:18 order #4520 ₱12,200 partial_failure 1,200 ms ││ 2026-05-21 13:04 order #4519 ₱5,800 success 395 ms ││ 2026-05-21 12:51 order #4518 ₱9,000 success 422 ms ││ 2026-05-21 12:14 order #4517 ₱4,800 skipped_filter 4 ms ││ ││ [⋯ View per-action timing] [⋯ Replay against current chain] │└──────────────────────────────────────────────────────────────────────┘Related references
- Notifications — Reference. Actions in the
notificationcategory (email.send, sms.send, push.send) hand off to Notifications for the per-channel delivery work. Notifications owns the channel configuration and the delivery log. - Integrations — Reference. Actions in the
external_callcategory (webhook.post, integration.push) hand off to Integrations through the configured connector. Integrations owns the credentials and the per-vendor adapter. - Tools — Reference. Activity Log entries for automation configuration changes are queryable from Tools alongside the rest of the audit log. The run history view is dedicated to per-fire records and is reachable from the automation detail.
- Subscriptions — Reference. Subscription lifecycle events (
subscription.created,subscription.charge_succeeded,subscription.charge_failed,subscription.cancelled) are common automation triggers for billing-adjacent workflows. - Pages — Reference. Page lifecycle events (
page.published,page.saved.draft) are emitted by the Pages surface and consumed by automations. - Posts — Reference. Post lifecycle events route through the same event catalog.
- Forms — Reference. Form submission events (
form.submitted) are a common automation trigger for lead-routing workflows. - Roles — Reference. The capability map above resolves through the Roles catalog.
- Permissions — Reference. The
automations.external_call.editcapability and the per-action gates are defined in the Permissions catalog.
/docs/automations.