Workflow management

Acceptance

Verify duplicate handling and recovery after failed steps.

Boundary

The engine has one acceptance contract; each recipe is not a new feature.

Configure workflow triggers and steps

Set the trigger and entry filters in the Info tab, connect action and decision steps on the Flow canvas, and verify execution with one test event.

Starting conditions and inputs

Verify actor permissions, the test event, and expected side effects before activating the workflow.

• Set organization and data permissions

Command sequence

open "$entry_url" && snapshot -i
click "$workflow_row" && snapshot -i
click "$info_tab" && snapshot -i
click "$trigger_picker" && snapshot -i
click "$cron_option" && snapshot -i
fill "$schedule_input" "$schedule" && press 'Tab' && snapshot -i
click "$flow_tab" && snapshot -i
click "$step_node" && snapshot -i
get text body
# Outside browser: Generate one test source event. Restrict sending workflows to the designated test recipients.
open "$workflow_run_url" && snapshot -i
get text body

Check the result

The matching workflow and step runs show intended outcomes without duplicate execution.

Resuming after interruption

Read the same IDs again. Preserve correct settings and update only differences.

Workflows automate recurring operations such as sending confirmation notices or checking overdue reservations. Opening a workflow displays two tabs: Flow and Info. Flow renders an interactive node canvas of the trigger and steps, while Info edits the workflow status and trigger rules.

This guide explains how to configure triggers and filter chips in Info. You will also connect action and decision steps on the Flow canvas and verify the workflow with a test event.

Example trigger: Daily schedule (0 9 * * *) or reservation status entering confirmed (db)

Example steps: Query or classify records with Decide (workflows.decide), then run the matching follow-up action

Keep the workflow in draft status while editing so unfinished steps do not run on live customers. Switch the status to active only after verifying one test run.

How the Flow and Info tabs work

Select Workflows in the left menu and click a workflow row to open its workspace.

Choose the trigger

Open the Info tab (or click the top trigger card on the Flow canvas) and select a Trigger type.

When you choose db, use the Filter button under source_query to add condition chips just like table filters. On an update event, the workflow fires only when the record newly enters the filter set. Active filter chips also appear on the trigger card in the Flow canvas.

Define steps and inputs

Return to the Flow tab and click Insert or Decide in the top bar. Click a step node on the canvas to configure its fields in the detail pane.

1. Feature steps, list queries (*.list), and fan-out loops (each)

1. Select the feature: Pick the capability to run, such as reservations.list, reservations.update, or template message delivery.
2. Build list queries: When the feature ends with .list, the Input section provides visual controls for Filter (where), Sort by (order), and Limit (limit). Add filter chips to narrow the target rows.
3. Loop over rows (each): Set Each to a prior list step's row array (such as ${steps.step_1.rows}) to run once per row. The canvas node displays a ↻ ${steps.step_1.rows} badge and binds each element to ${item}.

2. Decision steps (workflows.decide) and branch conditions (when)

Click Decide in the top bar to add a workflows.decide step that classifies data and branches the flow.

1. Decision state and question key: Select the input data to evaluate (such as Trigger (${trigger}) or Loop item (${item})) and name each question key (such as urgency).
2. Question type and evaluator:
   • Choose Choice, Boolean, Score, or Resource field.
   • Select AI (LLM) to evaluate with natural-language instructions, or Rules to match filter chips and return a typed answer.
3. Connect branch conditions (when): Click the follow-up step card on the canvas and add a condition under When. Select the decision question (such as Decision: Decision 1 - urgency) or trigger data as the source, then set the matching filter chip. The Flow canvas renders these condition chips directly on the incoming branch edge.

Check execution permissions

Each workflow executes with the permissions of its owning member. Confirm that the owner's role allows every feature used in the steps under organization and data permissions.

Wording inside a prompt or description never grants database access. Recheck workflow execution whenever a member's role changes.

Prevent repetition and handle errors

Design conditions and follow-up updates so recurring heartbeat or cron workflows do not select the same record again on the next tick.

1. Update state after processing: When a step processes a pending reservation, update its status or tracking field so the next query excludes it.
2. Guard external side effects: Before sending messages, placing calls, or creating payments, ensure duplicate events cannot trigger a second send to the same customer.

Test the saved result

Test the workflow with one synthetic record before switching it to active.

1. Trigger the event with a single test customer or reservation. Restrict any message or call step to a test recipient.
2. Open Workflow runs in the left menu and confirm that the run status is succeeded.
3. Open the run to inspect each step run's inputs, outputs, decision values, and any skipped branches.
4. Repeat the event once to verify that no duplicate side effect occurs, then set the workflow status to active in the Info tab.

If the result differs from what you expected

Editing a record did not trigger a db workflow

For update triggers with source_query filter chips, the workflow runs only when the row transitions from not matching to matching. Editing another field on a row that already matched does not fire the trigger again. Also check that the workflow status is active in the Info tab.

A new step does not connect under the expected branch on the canvas

The Flow canvas positions steps based on references in When (when), Each (each), and Input (input). To branch from a decision step, select that decision question as the condition source in the follow-up step's When field.

A loop step (each) is skipped with zero items

Inspect the prior .list step run to see whether its query returned zero rows. Also check that the step slug in ${steps.<slug>.rows} matches the list step's name.

A step fails with a permission error

Check the owning member's role permissions for the step's feature. After updating permissions, follow workflow failure recovery.

Inspect workflow failures and recovery

Find failed workflow runs, inspect step inputs and completed side effects, and recover without repeating messages or payments.

Starting conditions and inputs

Identify the failed workflow run ID, its first failed step, and the source record ID.

Command sequence

open "$entry_url" && snapshot -i
click "$workflow_run" && snapshot -i
get text body
open "$cause_record_url" && snapshot -i
get text body
# Outside browser: The operator corrects the cause and resumes through a supported recovery path. Do not repeat completed sends or payments.
open "$workflow_run_url" && snapshot -i
get text body

Check the result

Successful effects are not duplicated and recovery correlates to the original event.

Resuming after interruption

Check the original request ID and outcome first. Do not resubmit while its result remains unknown.

Even when a workflow is active, an individual run can fail if a customer record is missing a phone number or a channel account loses permission. Re-running the entire workflow blindly can repeat messages or updates that already succeeded in earlier steps.

This guide explains how to inspect Workflow runs and Step runs, separate completed actions from the failed step, and recover safely.

Run status to inspect: failed

Key check before recovery: Whether any succeeded step before the failure already sent a message, placed a call, or processed a payment

Find the run

Open Workflow runs in the left menu. Locate the run by workflow name, status (queued, running, succeeded, failed), and start time, then click the row.

An active badge on the workflow list only means the trigger is enabled. Always check Workflow runs to verify whether individual executions succeeded.

Inspect the failed step

In the workflow run detail pane, inspect the linked Step runs (step_runs) in position order.

1. Check steps completed before the failure: Identify every step marked succeeded before the first failed step. Never repeat a message delivery or payment step that already succeeded.
2. Distinguish skipped from failed: A skipped step means its When (when) branch condition evaluated to false. Open the prior workflows.decide step run and check its output values to see why that branch was not taken.
3. Classify the error cause: Read the failed step's input and error fields to identify the root cause.
   • Missing source data: Empty phone number, missing required custom field, or canceled reservation.
   • Permission denial: The workflow owner's role lacks permission for the step's feature.
   • External provider error: Unapproved template, withdrawn consent, or expired integration credentials.

Choose a safe retry scope

Fix the root cause on the source record ($cause_record_url) or role settings before retrying. Do not assume every screen has a replay button or re-trigger the entire event blindly.

1. Failure before any external effect: A list or decision step can fail before any write or send step runs. Fix the missing data or rule, then let the next schedule tick or supported trigger run it.
2. Failure after a completed send or write: An earlier step can send a message before a later step fails. Complete only the remaining work manually or through a targeted action so the customer does not receive duplicate messages.
3. Repeated failures: Pause the workflow in the Info tab (paused) if an external outage or invalid filter causes repeated failures. Repair the configuration before reactivating it.

Check recovery results

After fixing the cause and completing recovery, verify three records.

1. Source record state: Confirm that the customer, reservation, or purchase record reflects the intended final status.
2. Single delivery or payment: Check Deliveries or Calls to confirm that only one message or call was sent for the event.
3. Audit trail: Keep both the original failed run ID and the recovery run ID for troubleshooting.

If the result differs from what you expected

The workflow run is succeeded, but a step did not run

Check whether the step run status is skipped. Steps with a When (when) condition are skipped without error when the condition is not met. Compare the step's condition chips with the prior decision output.

The same record fails again on the next schedule

Check whether a recurring heartbeat or cron query still selects the unupdated record, or whether a duplicate customer row exists with the same name.

The send step succeeded, but the customer did not receive the message

A succeeded step run confirms that the delivery request was submitted. Check actual handset delivery, consent exclusions, and provider status in message delivery verification.