Running Workflows and Reading the Run Ledger

Two ways to run

StretchAutomate executes a workflow in one of two modes:

• Simulate (the default) — a complete dry run. The engine plans the workflow, walks the graph stage by stage, resolves every step's inputs against the accumulated data, evaluates filters, and records what would happen — with no real side effects. Action steps are marked as simulated with their resolved input captured. Simulate as often as you like; nothing reaches your customers.
• Live — a real execution. The engine performs the same plan‑and‑resolve pass and records the trace; action steps are queued for dispatch (recorded as pending) so the connector side effects can be carried out. Because dispatch is queued, live runs typically finalize as partial until the queued actions complete.

How a run unfolds

When you start a run, StretchAutomate:

1. Plans the workflow and confirms the graph is valid — an empty workflow or an invalid graph is rejected before anything executes.
2. Seeds the run context with the trigger payload.
3. Walks the plan's stages in order. For each step it evaluates the step against the current context:
- Filters either pass (recorded succeeded) or fail (recorded skipped), and a failed filter causes every dependent step to be skipped too — skip propagation down the branch.
- Actions, transforms, and delays have their inputs resolved. If every reference resolves, the step is recorded simulated (simulate mode) or pending/queued (live mode). If a reference cannot be resolved, the step is recorded failed and the run becomes partial.
4. Finalizes the run with an overall status and the full accumulated context.

Run and step statuses

A run finishes in one of these states:

• simulated — a clean simulate run; every step resolved.
• partial — some steps did not fully complete (unresolved references, or actions queued for live dispatch).
• failed — the run hit an error it could not continue past.

Each step in the trace carries its own status: succeeded, skipped, simulated, pending, or failed, plus its attempt count, its resolved input, its output, and any error message.

Run a workflow

1. From the Workflows tab, open the workflow and choose Run.
2. Pick the mode — simulate to test, live to execute for real.
3. Provide a trigger payload (the event data the run should start from). For a manual test, supply representative sample data.
4. Start the run and open it in the Run ledger to read the trace.

Reading the Run ledger

The Run ledger is the audited history of every execution. The list view enriches each run with the workflow name, the step count, a blocked count (steps that were skipped or failed), a retry count (total attempts across steps), and the next retry time if any step is scheduled to retry. Open any run to see its per‑step trace: for each step, its status, the resolved input it computed, the output it produced, and — for actions — which connector and action it targeted. Filters show which rules were evaluated and whether they passed. This is your source of truth for what actually happened.

You can list runs across all workflows, or filter the ledger to a single workflow to see just its history.

Realistic example

An operator simulates New order → fulfil with a sample order under $500. The ledger shows: the high_value filter skipped (order below threshold), and — because they depend on it — the vip_tag and owner_task actions skipped with the reason "upstream step skipped." The thanks_email action, which depends only on the trigger, is simulated with the recipient resolved to the buyer's email. Everything behaved as designed, so they run it live; this time the ledger shows thanks_email as pending, queued for dispatch, and the run finalized as partial until dispatch completes.

Tips

• Always simulate first. It is free of side effects and shows you exactly what each step resolved to.
• Use the blocked count in the ledger to spot runs with skipped or failed steps at a glance.
• If an action is failed with an unresolved reference, the step's input mapping points at data that wasn't in the context — fix the mapping and re‑simulate.
• Feed realistic trigger payloads into simulations so you validate real references, not just the happy path.

Troubleshooting

"Workflow has no steps to run." Add at least one step before running.

"Workflow graph is invalid; validate before running." The plan failed. Open Validate & Plan, fix the errors, and run again.

Run is stuck at "partial" after a live run. Action steps are pending — queued for dispatch. Review the ledger; if a step is failed rather than pending, it hit an unresolved reference or error you need to fix.

Running returns "engine is not enabled." Runs require the StretchAutomate engine. Ask your administrator to enable it (see The StretchAutomate Engine).