Execution Model

How workflows run: from trigger activation to node chains, branching, loops, and completion.

Execution Lifecycle

A workflow execution follows a predictable lifecycle from start to finish.

  1. 1
    Trigger fires

    A system event matches a trigger's configuration. The trigger creates an initial payload with its output variables and sends it downstream.

  2. 2
    Payload flows through connected nodes

    Each node receives the payload, executes its logic, adds its output variables, and passes the updated payload to the next node in the chain.

  3. 3
    Conditions branch the flow

    When execution reaches a Condition node, it evaluates the comparison and routes the payload down either the Yes or No outlet. Only one branch executes.

  4. 4
    Loops iterate

    For Each and While nodes create loops. For Each iterates over an array, executing downstream nodes once per item. While repeats until a condition becomes false.

  5. 5
    Execution completes

    When the last node in every active branch finishes, the execution is marked complete. The full timeline is recorded for inspection.

Triggers vs. Emitters

Triggers

Fire once per event. A file change, a webhook request, or a scheduled time produces a single execution. The workflow runs to completion, then waits for the next event.

Emitters

Continuously stream data at configurable intervals. A Resource Monitor emits CPU and memory readings every N seconds. Each emission starts a new execution through the downstream chain.

Branching with Conditions

Condition nodes evaluate a comparison (equals, greater than, contains, etc.) and route the payload to one of two outlets:

Yes — condition is true
No — condition is false

You can chain multiple conditions to create complex decision trees. Each branch operates independently with its own copy of the payload.

Loops

For Each

Takes an array from the payload and executes the downstream chain once for each item. On each iteration, the current item and its index are added to the payload. When all items have been processed, execution continues past the loop.

// Iteration payload includes:
{
  "currentItem": "file1.txt",
  "currentIndex": 0,
  "items": ["file1.txt", "file2.txt", "file3.txt"]
}

While

Repeats the downstream chain as long as a condition evaluates to true. The condition is checked before each iteration. A configurable maximum iteration count prevents infinite loops.

Execution Timeline

Every node execution is recorded in the timeline panel. For each node, the timeline shows:

  • Start time and duration
  • Input payload (what the node received)
  • Output payload (what the node produced)
  • Status (success, error, skipped, or disabled)

Click any entry in the timeline to inspect the full payload at that point in execution. This makes debugging straightforward — you can see exactly what data each node received and produced.

Execution Controls

Watchflows provides several controls for managing running workflows:

Control Behavior
Breakpoints Pause execution when it reaches a Breakpoint node. Inspect the current payload, then resume or cancel. Useful for debugging mid-flow.
Cancel Stop a running execution immediately. Any node currently in progress is interrupted. Nodes that already completed are not rolled back.
Replay Re-run a previous execution using the same initial trigger payload. Helpful for testing changes to downstream nodes without waiting for the trigger to fire again.
Manual Run Start a workflow manually with a test payload, bypassing the trigger. The Input node or a manually composed payload is used as the starting data.

Error Handling

When a node encounters an error during execution:

  • The node is marked as failed in the timeline with the error message.
  • Execution stops for that branch. Other independent branches are not affected.
  • The node shows a red error indicator on the canvas so you can quickly identify the problem.
  • You can fix the configuration and replay the execution to test the fix.