Automation (automation)

Category: apps | Form: | Symbol: At

Orchestrate multi-step execution as a directed graph

Defines and executes a directed acyclic graph (DAG) of steps. Each step references an element in the same circle by slug. Steps declare dependencies via depends_on (ordering) or edges (data routing with port-level connections). Execute operation runs the graph in topological order, routing data between steps along edges. Steps support per-step error strategies (stop, skip, retry, fallback), CEL skip-conditions, and timeout overrides. Use validate operation to check for missing refs, cycles, and edge format errors before executing. Use status to monitor per-step progress of a running execution. Supports concurrency > 1 for parallel branches. Edges use arrow notation: ‘step-a:output → step-b:input’. Steps without depends_on or incoming edges are root nodes and receive the automation’s input.

Guide

Orchestrate multi-step execution as a directed graph

What It Does

Automation is a compound element that chains multiple steps into a directed execution graph. Each step can invoke an action, query a data element, call an IO connector, or branch on a condition. Steps execute in dependency order with data flowing between them via ports.

Automations are the primary way to build multi-step workflows on Triform. They combine atomic elements (actions, IO, data) into higher-level business logic without writing orchestration code.

Element Definition

Property	Value
Type	automation
Category	apps
Form	compound

Compound Children

Child Type	Purpose
condition	Branch execution based on a boolean expression
loop	Repeat a sub-graph over a collection or until a condition
wait	Pause execution for a duration or until an event

Usage

1. Create an automation element
2. Add steps by wiring action, data, or IO elements
3. Use conditions and loops for control flow
4. Connect an IO trigger (schedule, webhook, platform-trigger) to start the flow

Invoke Response Shape

POST /api/{circle}/{slug}/ops/invoke returns an AutomationResult object:

{
  "run_id":        "<uuid>",
  "status":        "completed | failed | cancelled | timed_out",
  "duration_ms":   1234,
  "steps":         [{ "step_id": "s1", "status": "completed", "outputs": {}, "duration_ms": 100 }],
  "steps_executed": 2,
  "steps_skipped":  0,
  "steps_failed":   0,
  "outputs":       { "body": "...", "status": 200 }
}

Field	Type	Notes
run_id	uuid string	Unique execution identifier
status	enum	completed, failed, cancelled, or timed_out
duration_ms	integer	Wall-clock ms for the full automation run
steps	array of StepResult	Per-step outcomes in completion order
steps_executed	integer	Count of steps that ran
steps_skipped	integer	Count of steps skipped (unsatisfied depends_on)
steps_failed	integer	Count of steps that errored
outputs	object	Merged outputs from leaf steps

Note (BUGS-772): Prior to fix 2c3c4ecca, the response used a raw Rust Duration {secs, nanos} shape instead of duration_ms, and steps[] was absent. The schema and runtime are now reconciled.

Relationships

• Contains: condition, loop, wait
• Attaches to: rate-limit, auth-policy, validation, alert, evaluator, prompt, variable

Capabilities

• assembly: References library elements as workflow steps (assembly pattern)
• app-transparent-create: When creating an element under this automation, auto-create in library and link via element_references
• activity-scope-members: Activity/stats queries scope to the automation’s referenced members
• dag-execution: Execute steps in topological order as a directed acyclic graph
• data-routing: Route outputs between steps along typed edges with port-level granularity
• parallel-branches: Execute independent branches concurrently up to the concurrency limit
• error-recovery: Per-step error strategies: stop, skip, retry with backoff, or fallback
• conditional-steps: Skip steps based on CEL condition evaluation

Properties

Property	Type	Default	Description
steps	array	—	Ordered list of steps in the automation graph
edges	array	—	Data routing between steps. One chip per edge in arrow notation: step-id:port → step-id:port. Press Enter or use the + Add control to add a chip; click the × to remove.
entry	string	—	Step ID that receives the automation’s initial input (defaults to first root node)
concurrency	integer	1	Max steps executing in parallel (1 = strictly sequential topological order)
timeout_ms	integer	300000	Whole-automation timeout in milliseconds
error_strategy	string	"stop"	Automation-level error behavior — stop aborts on first step failure, continue runs all reachable steps
response	object	—	Optional response shape for automations invoked synchronously (e.g. as the target_ref of an io/http inbound element). Lets a flow declare that its response body comes from a specific step’s output rather than the default last-step passthrough. Used by the CPRX hot-path to forward an io/http/call_streaming outbound’s stream-handle directly to the inbound’s SSE response without materializing chunks.
trigger	object	—	Trigger configuration — describes what event starts this automation (e.g., schedule, webhook, platform-trigger)
dry_run	boolean	false	When true, validate and resolve the graph without executing side effects
response_transform	string	—	Optional CEL expression evaluated at flow termination against the final state. The result is placed in OrchestrationResult.outputs._response. Use this to surface flow-level response metadata that doesn’t fit per-step outputs — for example, {stream_from: steps.upstream_call.output.stream} to tell the io/http inbound’s receive op to switch to SSE response mode (Phase B.1.5b of CPRX). CEL context: input + inputs + steps.<id>.output.<field> + context + status. Same shape as input_transform: and condition:.
on_complete	object	—	Actions to take when the automation completes
members	array	[]	Element references added via the ‘reference’ operation
input_schema	object	—	JSON Schema describing expected input data shape. Used for port compatibility and runtime validation.
output_schema	object	—	JSON Schema describing output data shape. Used for port compatibility and runtime validation.

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

automation_status

Get /ops/status/{run_id} | Auth: Read

Get detailed automation execution status

Returns per-step status, outputs, errors, and timing for an automation execution. Includes the resolved graph topology (which steps depend on which). Use this to poll progress of an async automation execution.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

build-flow

Post /ops/build-flow | Auth: Execute

Declaratively define or update the automation’s step graph and data routing

Sets the automation’s steps, edges, and execution config in a single call. Replaces the current graph with the provided definition (use merge: true to add/remove incrementally). Runs validation automatically and returns any issues. Steps reference library elements by slug. Edges route data between step ports using arrow notation. When a step includes create: { type: "python" } (or any element type), the element is auto-created as a placeholder if it doesn’t exist yet. This lets you define the full flow topology first, then implement each step later. The intention field becomes the element’s description. Example — scaffold a pipeline with auto-created steps: build-flow({ steps: [ { id: “fetch”, ref: “fetch-data”, create: { type: “python”, intention: “Fetch order data from the database” } }, { id: “transform”, ref: “transform-fn”, depends_on: [“fetch”], create: { type: “python”, intention: “Validate and transform order payload” } }, { id: “notify”, ref: “slack-notify”, depends_on: [“transform”], create: { type: “slack”, intention: “Send order confirmation to Slack” }, condition: “steps.transform.outputs.valid == true” } ], edges: [ “fetch:result → transform:input”, “transform:result → notify:input” ] })

Example — loop step (iterates over a collection): build-flow({ steps: [ { id: “get-users”, ref: “fetch-users” }, { id: “process-each”, ref: “process-user”, type: “loop”, depends_on: [“get-users”], loop: { items: “steps.get_users.output.users”, variable: “user”, max_iterations: 50, break_condition: “user.inactive == true” } } ], edges: [“get-users:output → process-each:input”] })

Incremental update — add a step and remove another: build-flow({ merge: true, add_steps: [ { id: “log”, ref: “logger-fn”, depends_on: [“transform”], create: { type: “python”, intention: “Log the transformation result” } } ], add_edges: [“transform:result → log:input”], remove_steps: [“notify”] })

cancel

Post /ops/cancel | Auth: Execute

Cancel a running or paused automation

Cancels automation execution. Running steps are allowed to complete (no hard kill). Returns final state with which steps completed before cancellation.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

execute

Post /ops/execute | Auth: Execute

Execute the automation graph

Runs all steps in topological order, routing data along edges. Returns run_id immediately (async). Input is passed to root steps (those with no depends_on or incoming edges). If entry step is configured, only that step receives input. Use status with the run_id to poll progress. Per-step errors are handled by each step’s on_error strategy. The automation-level error_strategy (stop/continue) controls whether unreachable downstream steps are cancelled or skipped.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

invoke

Post /ops/invoke | Auth: Execute

Invoke the automation synchronously

Synchronous entry point — runs all steps and returns the complete result. Used by IO elements to dispatch external traffic into the automation. Unlike execute (async, returns run_id), invoke waits for completion. Input is passed to root steps. Can also be called directly via API.

invoke-step

Post /ops/invoke-step | Auth: Execute

Invoke a single step of the automation (canvas Run button)

Runs ONE step of the automation synchronously, rather than the whole graph. Used by the canvas Run button: user selects a step hex, clicks Run, this op executes that step’s ref element with its primary op, persists the output to the per-circle automation_step_outputs scratchpad, and returns the result. Input is hydrated from upstream scratchpad rows along spec edges (edge upstream:output → this:input merges the upstream step’s latest stored output into this step’s input). The caller-provided input overrides any edge-hydrated fields. Emits WS updated events with step_invoke_* details so the canvas hex can update pending/running/ok/failed without polling.

pause

Post /ops/pause | Auth: Execute

Pause a running automation at the next step boundary

Pauses automation execution after the current step(s) complete. Does not interrupt running steps. Use resume to continue. Returns the list of completed and pending steps at time of pause.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

reference

Post /ops/reference | Auth: Write

Add an element reference as a workflow step

Adds a library element (action, agent, tool, IO, data) to this automation as a referenced workflow step. Use ref as a path (e.g., “actions/python/my-fn”) or provide target_id as UUID. Validates topology (can_reference check). Referenced elements appear on the automation canvas and can be wired into the step graph via edges. Prefer this operation over manual spec.steps edits.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

resume

Post /ops/resume | Auth: Execute

Resume a paused automation

Continues execution from where the automation was paused. Pending steps resume in topological order. Optionally override input for specific steps via step_overrides.

retry_step

Post /ops/retry-step | Auth: Execute

Retry a specific failed step in a completed or failed automation

Re-executes a single failed step and its downstream dependents. The automation must be in a terminal state (completed/failed). Uses the original inputs unless input_override is provided. Downstream steps re-execute with the new output.

run_get

Get /ops/runs/{run_id} | Auth: Read

Get details of a specific automation run

Returns full execution details for a single run: per-step status, outputs, errors, timing, and the resolved graph topology. Equivalent to automation_status but accessed via the standard run_get path pattern.

runs

Get /ops/runs | Auth: Read

List automation execution runs

Returns a paginated list of past and current automation executions. Each entry includes run_id, status, started_at, duration, and step summary. Use limit/offset for pagination. Filter by status with ?status=completed.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

unreference

Post /ops/unreference | Auth: Write

Remove an element reference from this automation

Removes a referenced workflow step from this automation. Accepts ref (path) or target_id (UUID). Does not delete the library element. Any edges connected to this step should be cleaned up separately.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

validate

Post /ops/validate | Auth: Execute

Validate the automation graph without executing

Checks that all step refs resolve to existing elements, edges reference valid step IDs and ports, no cycles exist, and entry step (if set) exists. Returns a list of issues with severity (error/warning). Run this after modifying steps or edges to catch problems early.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
AUTOMATION_CYCLE_DETECTED	validation	no	The step graph contains a cycle and cannot be executed
AUTOMATION_STEP_REF_NOT_FOUND	validation	no	A step references an element slug that does not exist in this circle
AUTOMATION_EDGE_INVALID	validation	no	An edge references a step ID or port that does not exist
AUTOMATION_TIMEOUT	limit	yes	Automation execution exceeded the configured timeout
AUTOMATION_STEP_FAILED	internal	no	A step failed and the error strategy is stop
AUTOMATION_STEP_TIMEOUT	limit	yes	A step exceeded its per-step timeout