Variables & Templates

Overview

Jinba Flow supports powerful templating capabilities that allow you to:

Reference results from previous steps
Access configured secrets securely
Use Nunjucks templates for complex logic
Create dynamic, reusable workflows

Variable Placeholders

Basic Syntax

Variables are enclosed in double curly braces: {{ variable }}

Available Variables

Variable	Description	Example
`steps.<step_id>.result`	Result from a previous step	`{{steps.fetch_data.result}}`
`steps.<step_id>.result.<property>`	Specific property from result	`{{steps.api_call.result.content}}`
`steps.<step_id>.status`	Status of a previous step (`success`, `failed`, `skipped`, `cancelled`)	`{{steps.fetch_data.status}}`
`secrets.<secret_name>`	Configured workspace secret	`{{secrets.API_KEY}}`
`item`	Current item in a forEach loop	`{{item}}`
`item.<property>`	Property of current item	`{{item.id}}`
`itemIndex`	Position of the current item in a forEach loop, starting at 0	`{{itemIndex}}`
`itemCount`	Number of items in the forEach loop	`{{itemCount}}`

item, itemIndex and itemCount exist only in the inputs of a step that has forEach.

Accessing Step Results

# Access entire result
- name: data
  value: "{{steps.previous_step.result}}"

# Access specific property
- name: content
  value: "{{steps.llm_response.result.content}}"

# Access nested property
- name: user_email
  value: "{{steps.get_user.result.user.email}}"

# Access array element
- name: first_item
  value: "{{steps.get_list.result[0]}}"

A plain {{steps.<step_id>.result...}} placeholder is inserted as text:

Objects and arrays become JSON
Strings are inserted as-is, without quotes
null or a missing value becomes an empty string

This automatic conversion applies only to steps.<step_id>.result... placeholders with no filter. Other objects, such as {{item}} when the item is an object, render as [object Object]; write {{item | json}} instead. A step that reads another step’s result must list that step in needs, or it may run before the result exists. See Step Module Options.

PYTHON_SANDBOX_RUN returns its output under result.data, so a later step reads it as {{steps.<step_id>.result.data}}.

Using Secrets

Secrets are configured at the workspace level and accessed securely:

config:
  - name: api_key
    value: "{{secrets.OPENAI_API_KEY}}"
  - name: token
    value: "{{secrets.GITHUB_TOKEN}}"

Security Notes:

Secrets are encrypted at rest
Never hardcode sensitive values in workflows
Use secrets for API keys, tokens, and credentials

Nunjucks Templates

Jinba Flow renders templates with Nunjucks, whose syntax is close to Jinja2 but not identical. Templates are processed before step execution.

Control Structures

For Loops

value: |
  {%- for user in steps.get_users.result %}
  - {{user.name}} (ID: {{user.id}})
  {%- endfor %}

Conditional Statements

value: |
  {%- if steps.check.result.status == 'success' %}
  Processing successful
  {%- else %}
  Handling error
  {%- endif %}

Loop with Index

value: |
  {%- for entry in steps.get_list.result %}
  {{loop.index}}: {{entry}}
  {%- endfor %}

loop.index counts from 1 and loop.index0 counts from 0.

Built-in Functions

# range - Generate number sequence
{%- for i in range(5) %}
Item {{i}}
{%- endfor %}

# length/count
Total: {{items|length}}

Nunjucks has no zip(). To walk two lists side by side, loop over one and index the other with loop.index0:

{%- for user in steps.users.result %}
{{user.name}}: {{steps.orders.result[loop.index0].id}}
{%- endfor %}

Filters

Apply transformations to values:

# String manipulation
{{ variable | upper }}
{{ variable | lower }}
{{ variable | trim }}
{{ variable | replace('old', 'new') }}

# Default values
{{ variable | default('fallback_value') }}

# JSON handling
{{ data | json }}

# List operations
{{ items | first }}
{{ items | last }}
{{ items | join(', ') }}

default replaces only a missing value. To also replace null, an empty string or false, write default('fallback_value', true). json is added by Jinba Flow and outputs strict JSON: strings keep their quotes and null stays null. There is no tojson filter. Jinba Flow also adds filters for the output of a forEach step:

Filter	Returns
`successful`	The items whose status is `success`
`failed`	The items whose status is `failed`
`results`	The `result` of each successful item
`pluck('key')`	The value of `key` from each item

Succeeded: {{ steps.batch | successful | length }}
Failed: {{ steps.batch | failed | length }}

Whitespace Control

Use {%- and -%} to control whitespace:

value: |
  {%- for item in items -%}
  {{item}}
  {%- endfor -%}

{%- removes whitespace before the tag
-%} removes whitespace after the tag

Common Patterns

The Python examples below read earlier results with json.loads(r'''{{steps.<step_id>.result}}'''). Pasting a result straight into Python code breaks on JSON values such as null, true and false. PYTHON_SANDBOX_RUN uses the value of the last line as its result; set data_type to OBJECT and end with json.dumps(...) to return structured data.

Processing Lists

- id: input_list
  tool: INPUT_JSON
  input:
    - name: value
      value: '[{"id": 1}, {"id": 2}]'

- id: process_items
  tool: PYTHON_SANDBOX_RUN
  needs:
    - input_list
  input:
    - name: code
      value: |
        import json
        items = json.loads(r'''{{steps.input_list.result}}''')
        results = [{"id": item["id"], "processed": True} for item in items]
        json.dumps(results)
    - name: data_type
      value: OBJECT

Conditional Data Selection

- id: config
  tool: INPUT_JSON
  input:
    - name: value
      value: '{"mode": "full"}'

- id: full_data
  tool: INPUT_JSON
  input:
    - name: value
      value: '{"users": 120, "orders": 45, "revenue": 9800}'

- id: summary_data
  tool: INPUT_JSON
  input:
    - name: value
      value: '{"users": 120}'

- id: select_data
  tool: PYTHON_SANDBOX_RUN
  needs:
    - config
    - full_data
    - summary_data
  input:
    - name: code
      value: |
        import json
        {%- if steps.config.result.mode == 'full' %}
        data = json.loads(r'''{{steps.full_data.result}}''')
        {%- else %}
        data = json.loads(r'''{{steps.summary_data.result}}''')
        {%- endif %}
        json.dumps(data)
    - name: data_type
      value: OBJECT

Combining Multiple Sources

- id: users
  tool: INPUT_JSON
  input:
    - name: value
      value: '[{"name": "Alice"}, {"name": "Bob"}]'

- id: orders
  tool: INPUT_JSON
  input:
    - name: value
      value: '[{"id": "A-100"}, {"id": "A-101"}]'

- id: merge_data
  tool: PYTHON_SANDBOX_RUN
  needs:
    - users
    - orders
  input:
    - name: code
      value: |
        import json
        users = json.loads(r'''{{steps.users.result}}''')
        orders = json.loads(r'''{{steps.orders.result}}''')
        combined = [
            {"user": user["name"], "order": order["id"]}
            for user, order in zip(users, orders)
        ]
        json.dumps(combined)
    - name: data_type
      value: OBJECT

zip here is Python’s, which runs inside the sandbox. In a template, use the loop.index0 pattern shown under Built-in Functions.

Filtering Lists

Nunjucks does not support Jinja2’s {% for x in list if condition %}: it checks the condition once for the whole list, so the loop usually outputs nothing. Put the condition inside the loop instead:

value: |
  {%- for entry in steps.get_items.result %}
  {%- if entry.status == 'active' %}
  - {{entry.name}}
  {%- endif %}
  {%- endfor %}

Building Dynamic Prompts

- id: items
  tool: INPUT_JSON
  input:
    - name: value
      value: '[{"name": "Widget", "description": "Compact desk lamp"}, {"name": "Gadget", "description": "Wireless charger"}]'

- id: generate_prompt
  tool: OPENAI_INVOKE
  needs:
    - items
  input:
    - name: prompt
      value: |
        Analyze the following items:
        {%- for item in steps.items.result %}
        - {{item.name}}: {{item.description}}
        {%- endfor %}
        
        Provide insights based on the above data.

Best Practices

Variable References

Use descriptive step IDs for clarity
Access only the properties you need
Handle potential null/undefined values with defaults

Templates

Keep templates readable with proper indentation
Use whitespace control for clean output
Break complex logic into multiple steps

Secrets

Never log or expose secret values
Use workspace-level secrets for team sharing
Rotate secrets regularly

Performance

Avoid deeply nested templates
Limit loop iterations
Pre-process data when possible

Troubleshooting

Common Issues

Variable not found or empty

Check step ID spelling
Make sure the referenced step is listed in needs
Verify the property path is correct (for PYTHON_SANDBOX_RUN, the output is under result.data)

Template syntax error

Check for balanced braces {{ }}
Verify Nunjucks tag syntax {% %}
Look for missing quotes in strings

Unexpected output

Use debug steps to inspect intermediate values
Check whitespace handling
Verify data types (string vs object)
[object Object] means an object was inserted without conversion; add | json

TemplateSecurityError: ... is not allowed in templates

Templates are flow-authored, so the engine refuses anything that could run code or read files, and the step fails instead of rendering
Not allowed: reading constructor, prototype or __proto__ on any value (including a result field with that name); {% asyncEach %} / {% asyncAll %}; names that are not plain identifiers (letters, digits, _, $) as a variable, loop variable, macro, filter or test
{% include %}, {% import %} and {% extends %} fail separately with a “template not found” render error, because no template files are loadable from a flow
Ordinary member access, method calls on values such as {{ steps.x.result.trim() }}, filters, range and macros keep working
Front-end code with its own {{ }} interpolation (for example {{ user?.name }} in an HTML snippet) must be wrapped in {% raw %} ... {% endraw %}

Step Module Options - forEach, when, needs
YAML Coding Panel - Complete YAML syntax
Debug - Debugging workflows

​Overview

​Variable Placeholders

​Basic Syntax

​Available Variables

​Accessing Step Results

​Using Secrets

​Nunjucks Templates

​Control Structures

​For Loops

​Conditional Statements

​Loop with Index

​Built-in Functions

​Filters

​Whitespace Control

​Common Patterns

​Processing Lists

​Conditional Data Selection

​Combining Multiple Sources

​Filtering Lists

​Building Dynamic Prompts

​Best Practices

​Variable References

​Templates

​Secrets

​Performance

​Troubleshooting

​Common Issues

​Related

Overview

Variable Placeholders

Basic Syntax

Available Variables

Accessing Step Results

Using Secrets

Nunjucks Templates

Control Structures

For Loops

Conditional Statements

Loop with Index

Built-in Functions

Filters

Whitespace Control

Common Patterns

Processing Lists

Conditional Data Selection

Combining Multiple Sources

Filtering Lists

Building Dynamic Prompts

Best Practices

Variable References

Templates

Secrets

Performance

Troubleshooting

Common Issues

Related