Variables & Templates

Learn how to use variable placeholders and Nunjucks templates to create dynamic workflows

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 %}

Related

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