> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution Model

> How workflows execute from trigger to completion

Understanding the execution model helps you design reliable workflows and debug issues effectively.

## Build Time vs Run Time

Workflows have two distinct phases:

<CardGroup cols={2}>
  <Card title="Build Time" icon="hammer">
    Design your workflow in the editor. Define steps, configure tools, and set up dependencies.
  </Card>

  <Card title="Run Time" icon="play">
    The runner interprets and executes the manifest. Steps run in dependency order as data flows through.
  </Card>
</CardGroup>

## Execution Timeline

When a workflow runs, it follows this timeline:

<Steps>
  <Step title="Trigger">
    Execution begins via API call, schedule, MCP, or manual run
  </Step>

  <Step title="Validate">
    Input parameters validated, manifest loaded
  </Step>

  <Step title="Execute">
    Steps run according to dependency graph
  </Step>

  <Step title="Handle">
    Errors caught, retries attempted if configured
  </Step>

  <Step title="Return">
    Final result returned to caller
  </Step>
</Steps>

## Step Execution Patterns

<CardGroup cols={2}>
  <Card title="Sequential" icon="arrow-right">
    Steps with dependencies run one after another
  </Card>

  <Card title="Parallel" icon="arrows-split-up-and-left">
    Independent steps run simultaneously
  </Card>

  <Card title="Conditional" icon="code-branch">
    Steps run only when `when` condition is true
  </Card>

  <Card title="Loop" icon="rotate">
    Steps repeat for each item via `forEach`
  </Card>
</CardGroup>

### Sequential Execution

Steps with `needs` wait for their dependencies:

```yaml theme={null}
steps:
  - id: step_a
    tool: TOOL_A

  - id: step_b
    tool: TOOL_B
    needs: [step_a]  # Waits for step_a

  - id: step_c
    tool: TOOL_C
    needs: [step_b]  # Waits for step_b
```

**Execution order:** `step_a` → `step_b` → `step_c`

### Parallel Execution

Steps without shared dependencies run in parallel:

```yaml theme={null}
steps:
  - id: input
    tool: INPUT_TEXT

  - id: branch_a
    tool: TOOL_A
    needs: [input]

  - id: branch_b
    tool: TOOL_B
    needs: [input]  # Runs parallel with branch_a

  - id: merge
    tool: TOOL_C
    needs: [branch_a, branch_b]  # Waits for both
```

**Execution order:** `input` → (`branch_a` ∥ `branch_b`) → `merge`

### Conditional Execution

Use `when` for conditional logic:

```yaml theme={null}
steps:
  - id: classify
    tool: GEMINI_CHAT
    input:
      - name: prompt
        value: "Classify as 'urgent' or 'normal': {{inputs.message}}"

  - id: urgent_handler
    tool: SLACK_POST_MESSAGE
    needs: [classify]
    when: "'{{steps.classify.result.content}}' == 'urgent'"
    input:
      - name: message
        value: "URGENT: {{inputs.message}}"

  - id: normal_handler
    tool: GMAIL_SEND
    needs: [classify]
    when: "'{{steps.classify.result.content}}' == 'normal'"
    input:
      - name: body
        value: "{{inputs.message}}"
```

Only one handler executes based on the classification result.

### Loop Execution (forEach)

Process collections with `forEach`:

```yaml theme={null}
steps:
  - id: get_items
    tool: INPUT_JSON
    input:
      - name: value
        value: '[{"name": "Alice"}, {"name": "Bob"}, {"name": "Carol"}]'

  - id: greet_each
    tool: GEMINI_CHAT
    forEach: "{{steps.get_items.result}}"
    needs: [get_items]
    input:
      - name: prompt
        value: "Write a greeting for {{item.name}}"
```

The step executes once for each item in the collection.

## Failure Modes

| Failure Type         | Cause                                | Handling                    |
| -------------------- | ------------------------------------ | --------------------------- |
| **Validation Error** | Invalid input parameters or manifest | Execution stops immediately |
| **Tool Error**       | External service failure or timeout  | Step marked failed          |
| **Timeout Error**    | Step exceeds configured time limit   | Step terminated             |
| **Dependency Error** | Required step failed                 | Dependent steps skipped     |
| **Condition Error**  | Invalid `when` expression            | Step skipped with warning   |

## Step Status States

Each step transitions through these states:

| Status      | Description                            |
| ----------- | -------------------------------------- |
| **Pending** | Waiting for dependencies to complete   |
| **Running** | Currently executing                    |
| **Success** | Completed successfully                 |
| **Failed**  | Execution failed with error            |
| **Skipped** | Condition not met or dependency failed |

## Variable Resolution

Variables are resolved at execution time:

| Pattern                          | Resolved To                       |
| -------------------------------- | --------------------------------- |
| `{{inputs.name}}`                | Input parameter value             |
| `{{steps.step_id.result}}`       | Full result of completed step     |
| `{{steps.step_id.result.field}}` | Specific field from step result   |
| `{{secrets.KEY_NAME}}`           | Credential from workspace secrets |
| `{{item}}`                       | Current item in forEach loop      |
| `{{item.field}}`                 | Field from current loop item      |

## Error Handling Best Practices

1. **Validate Early**: Use INPUT\_\* tools to validate data at the start
2. **Check Outputs**: Add validation steps after critical operations
3. **Use Conditions**: Handle different outcomes with `when` clauses
4. **Design for Failure**: Consider what happens when external services fail
5. **Review History**: Use execution history to analyze failures

## Debugging Tips

| Issue                 | Solution                                  |
| --------------------- | ----------------------------------------- |
| Step not running      | Check `needs` dependencies are satisfied  |
| Wrong data            | Verify variable reference syntax          |
| Condition not working | Test `when` expression with actual values |
| Loop not iterating    | Ensure `forEach` target is an array       |
| Timeout               | Increase step timeout or optimize logic   |

## What's Next?

<CardGroup cols={2}>
  <Card title="Debug Workflows" icon="bug" href="/en/pages/basics/debug">
    Learn debugging techniques
  </Card>

  <Card title="YAML Reference" icon="file-code" href="/en/pages/basics/manifest">
    Complete manifest syntax reference
  </Card>
</CardGroup>