Step Module Options

The step settings screen. Switch between form/YAML, configure run conditions, loops, and error handling, and inspect input/output data

Overview

Each step in a Jinba Flow can be configured with advanced options that control how and when it executes. These options allow you to create sophisticated workflows with conditional logic, loops, and complex dependencies.

Step Dependencies (needs)

The needs option specifies which steps must complete before the current step can run. This creates an execution order and ensures data is available when needed.

Basic Usage

fetch_data and validate_input stand for earlier steps in your flow; fetch_data’s result is assumed to be a list.

- id: analyze_data
  tool: PYTHON_SANDBOX_RUN
  needs:
    - fetch_data
    - validate_input
  input:
    - name: code
      value: |
        import json
        data = json.loads(r'''{{steps.fetch_data.result}}''')
        len(data)
    - name: data_type
      value: NUMBER

Key Points

Execution Order: Order comes only from needs. Referencing {{steps.X...}} does not make a step wait for X, so list every step whose output you read
Parallel Execution: Steps that don’t depend on each other can run in parallel
Failure Handling: If a needed step fails or is cancelled, this step is cancelled, and so are the steps that depend on it. If every needed step was skipped, this step is skipped; a skipped step alongside one that succeeded does not stop it. A step with when ignores these rules and follows its condition (see below)
forEach Dependencies: A forEach step counts as succeeded if at least one item succeeded or it had no items, and as failed if no item succeeded and at least one failed or was cancelled
Diamond Patterns: Complex dependency graphs are supported (A→B, A→C, B→D, C→D)

Example: Multi-Branch Workflow

- id: input_data
  tool: INPUT_JSON
  input:
    - name: value
      value: "[1, 2, 3, 4, 5]"

- id: process_even
  tool: PYTHON_SANDBOX_RUN
  needs:
    - input_data
  input:
    - name: code
      value: |
        import json
        data = json.loads(r'''{{steps.input_data.result}}''')
        json.dumps([x for x in data if x % 2 == 0])
    - name: data_type
      value: OBJECT

- id: process_odd
  tool: PYTHON_SANDBOX_RUN
  needs:
    - input_data
  input:
    - name: code
      value: |
        import json
        data = json.loads(r'''{{steps.input_data.result}}''')
        json.dumps([x for x in data if x % 2 != 0])
    - name: data_type
      value: OBJECT

- id: combine_results
  tool: PYTHON_SANDBOX_RUN
  needs:
    - process_even
    - process_odd
  input:
    - name: code
      value: |
        import json
        even = json.loads(r'''{{steps.process_even.result.data}}''')
        odd = json.loads(r'''{{steps.process_odd.result.data}}''')
        json.dumps({"even": even, "odd": odd})
    - name: data_type
      value: OBJECT

PYTHON_SANDBOX_RUN uses the value of the last line as its result and stores it under result.data. With data_type: OBJECT, a final json.dumps(...) is returned as structured data. Reading a result through json.loads(r'''...''') avoids the breakage you get from pasting JSON (null, true, false) straight into Python.

Conditional Execution (when)

The when option allows a step to execute only if a specified condition is true. This enables dynamic workflow behavior based on previous step results.

Basic Syntax

- id: conditional_step
  tool: TOOL_NAME
  when: "<condition_expression>"
  input:
    - name: param
      value: "value"

Condition Expressions

Conditions are CEL expressions, written directly without {{ }}:

String Comparison: steps.check.result.status == 'success'
Numeric Comparison: steps.count.result.total > 5
Boolean Evaluation: steps.validate.result.isValid
Step Status: steps.fetch_data.status == 'failed'
Combining: &&, ||, !

The template form also works: {{ }} placeholders are filled in first, then the text is evaluated as CEL. Put quotes around placeholders that produce strings, for example "'{{steps.check.result.status}}' == 'success'".

Example: Conditional Branching

- id: check_type
  tool: PYTHON_SANDBOX_RUN
  input:
    - name: code
      value: |
        import json
        json.dumps({"type": "premium"})
    - name: data_type
      value: OBJECT

- id: premium_processing
  tool: PYTHON_SANDBOX_RUN
  when: "steps.check_type.result.data.type == 'premium'"
  needs:
    - check_type
  input:
    - name: code
      value: |
        "Processing premium user..."

- id: standard_processing
  tool: PYTHON_SANDBOX_RUN
  when: "steps.check_type.result.data.type == 'standard'"
  needs:
    - check_type
  input:
    - name: code
      value: |
        "Processing standard user..."

Important Notes

Conditions are evaluated before step execution. item, itemIndex and itemCount are not available in when
If the condition is false, the step status becomes skipped
A step whose needed steps were all skipped is skipped too; if another needed step succeeded, it still runs
When when is set, the condition alone decides whether the step runs, and a failed needed step does not cancel it. when: "true" runs a step even after a needed step failed; when: "steps.X.status == 'failed'" runs it only in that case
If the condition cannot be evaluated (for example, a placeholder renders as empty text), the step is marked failed

Loop Execution (forEach)

The forEach option executes a step multiple times, once for each item in a collection. This is useful for batch processing lists of data.

Basic Syntax

- id: get_list
  tool: INPUT_JSON
  input:
    - name: value
      value: '["apple", "banana", "cherry"]'

- id: process_items
  tool: TOOL_NAME
  needs:
    - get_list
  forEach: "steps.get_list.result"
  input:
    - name: value
      value: "{{item}}"

forEach also accepts the template form, "{{steps.get_list.result}}".

How It Works

The forEach value is evaluated to get a list. If it is not a list, the step runs zero times, without an error
The step executes once for each item in the list
In the step’s inputs, {{item}} is the current item, {{itemIndex}} its position (from 0), and {{itemCount}} the number of items. For an object item use {{item.<property>}} or {{item | json}}; {{item}} alone renders as [object Object]
Later steps see steps.<step_id> as a list with one entry (status, result, error) per item. steps.<step_id>.result is the list of results from the items that succeeded, and steps.<step_id>.status is success, partial or failed

Example: Processing Multiple Items

- id: get_users
  tool: INPUT_JSON
  input:
    - name: value
      value: |
        [
          {"id": 1, "name": "Alice"},
          {"id": 2, "name": "Bob"},
          {"id": 3, "name": "Charlie"}
        ]

- id: greet_users
  tool: PYTHON_SANDBOX_RUN
  forEach: "steps.get_users.result"
  needs:
    - get_users
  input:
    - name: code
      value: |
        f"Hello, {item['name']}!"

- id: combine_greetings
  tool: PYTHON_SANDBOX_RUN
  needs:
    - greet_users
  input:
    - name: code
      value: |
        import json
        greetings = json.loads(r'''{{steps.greet_users.result}}''')
        "\n".join(g["data"] for g in greetings)

Inside PYTHON_SANDBOX_RUN, the current item is also available as the Python variable item. Each greeting is stored as {"data": "Hello, Alice!"}, which is why combine_greetings reads g["data"].

Accessing Item Properties

forEach: "steps.items.result"
input:
  - name: id
    value: "{{item.id}}"
  - name: name
    value: "{{item.name}}"

forEach with Index

Use itemIndex (from 0) and itemCount to know where you are in the loop:

- id: get_items
  tool: INPUT_JSON
  input:
    - name: value
      value: '["apple", "banana", "cherry"]'

- id: process_with_index
  tool: PYTHON_SANDBOX_RUN
  needs:
    - get_items
  forEach: "steps.get_items.result"
  input:
    - name: code
      value: |
        position = {{itemIndex}} + 1
        total = {{itemCount}}
        f"{position}/{total}: {item}"

forEach Options

forEachOptions controls how the items are processed. In the step settings these are the Sequential / Parallel choice (with a thread count), the maximum number of items, and the Stop on error / Continue choice:

- id: process_items
  tool: TOOL_NAME
  forEach: "{{steps.get_list.result}}"
  forEachOptions:
    concurrency: 1        # 1 = Sequential; a larger number = Parallel with that many threads
    maxItems: 100         # only the first N items are processed
    continueOnError: true # skip failed items instead of stopping the loop
  input:
    - name: item
      value: "{{item}}"

concurrency: how many items run at the same time. Choosing Sequential saves 1; Parallel saves the thread count you enter. When it is not set, the loop runs with the deployment’s default parallelism.
maxItems: process only the first N items of the list. When it is not set, all items are processed.
continueOnError: true (Continue, the default) skips the items that fail and keeps looping; false (Stop on error) stops the loop after the batch in which an item failed, and the remaining items are marked skipped. To stop right after the first failure, set concurrency: 1.

Combining Options

You can combine needs, when, and forEach in a single step: check_enabled stands for an earlier step in your flow whose result contains a boolean active.

- id: get_items
  tool: INPUT_JSON
  input:
    - name: value
      value: '["apple", "banana", "cherry"]'

- id: process_active_items
  tool: PYTHON_SANDBOX_RUN
  needs:
    - get_items
    - check_enabled
  when: "steps.check_enabled.result.active == true"
  forEach: "steps.get_items.result"
  input:
    - name: code
      value: |
        f"Processed: {item}"

Evaluation Order:

Wait for all needs steps to finish
If when is set, run only if it is true. Without when, the outcome of the needs steps decides (cancelled or skipped, as described above)
Execute the forEach loop (or a single execution if there is no forEach)

Best Practices

Dependencies

Keep dependency chains shallow when possible
Use parallel execution to improve performance
Clearly name steps to make dependencies readable

Conditions

Use meaningful condition expressions
Consider all possible outcomes (success, failure, edge cases)
Test conditions with various input values

Loops

Limit loop iterations to avoid long execution times
Handle empty arrays gracefully
Consider memory usage for large datasets

YAML Coding Panel - Complete YAML syntax reference
Variables & Templates - Variable placeholders and Nunjucks templates
Debug - Debugging workflow execution

​Overview

​Step Dependencies (needs)

​Basic Usage

​Key Points

​Example: Multi-Branch Workflow

​Conditional Execution (when)

​Basic Syntax

​Condition Expressions

​Example: Conditional Branching

​Important Notes

​Loop Execution (forEach)

​Basic Syntax

​How It Works

​Example: Processing Multiple Items

​Accessing Item Properties

​forEach with Index

​forEach Options

​Combining Options

​Best Practices

​Dependencies

​Conditions

​Loops

​Related

Overview

Step Dependencies (needs)

Basic Usage

Key Points

Example: Multi-Branch Workflow

Conditional Execution (when)

Basic Syntax

Condition Expressions

Example: Conditional Branching

Important Notes

Loop Execution (forEach)

Basic Syntax

How It Works

Example: Processing Multiple Items

Accessing Item Properties

forEach with Index

forEach Options

Combining Options

Best Practices

Dependencies

Conditions

Loops

Related