In this Article:

• Overview
  • YAML
  • Jinja
  • Inputs
  • Workflow Structure
    • start_step 
    • steps
• Step Categories and Types
  1. Flow Lifecycle
     1.1 Start
     1.2 End
  2. Process Steps
     2.1 Call API
     2.2 Execute Database Query
     2.3 Execute JDBC Operation
     2.4 Execute Code
     2.5 Send Email
     2.6 Monitor Status
  3. Prompt AI
     3.1 DvSum AI Agent
     3.2 LLM Call
  4. External Systems
     4.1 Jira Cloud
  5. Flow Controls
     5.1 Decision
     5.2 Fan-Out
     5.3 Composite
     5.4 ForEach
     5.5 Human in the Loop
     5.6 Variable Operation

Overview

AI Orchestration Workflows are defined using YAML and consist of a sequence of steps executed based on their configuration.

Each workflow defines an entry point (start_step) and a set of steps, where each step performs a specific action based on its type.

YAML Format

Workflows are defined using YAML (YAML Ain’t Markup Language), a human-readable format used to structure configuration data.

Key Concepts

• Uses indentation (spaces) to define hierarchy
• Uses key-value pairs
• Lists are defined using -

Example

steps:
  - id: step1
    type: llm_call

Dynamic Expressions (Jinja)

Workflows support dynamic expressions using Jinja syntax.

• Used to reference variables dynamically
• Evaluated at runtime

Syntax

{{ variable_name }}

Example

message: "Processing customer {{ customer_id }}"

Inputs

Description

Defines the input parameters required to start the workflow.
Inputs are available throughout the workflow and can be referenced by subsequent steps during execution.

Configuration Schema

inputs:
  - param: <name>
    description: <string>
    path: <path>
    type: <type>
    required: <boolean>

Supported Keys

Behavior

• Inputs are defined at the workflow level.
• Input values are collected when the workflow is executed.
• The param field defines the parameter exposed during workflow execution and testing.
• The path field defines how the input value is mapped within the workflow.
• Inputs can be referenced by subsequent workflow steps.
• Required inputs must be provided before workflow execution.

Example

inputs:
  - param: entity_key
    path: fibernode_id
    type: integer
    required: true
    description: Give the name of the fiber node

steps:
  - id: start_step
    type: start
    name: Start Workflow
    config:
      message: "Processing fiber node {{ payload.fibernode_id }}"

Important

Use the input path when referencing workflow inputs: {{ payload.fibernode_id }}

Do not reference the parameter name directly: {{ entity_key }}

Workflow inputs can be supplied when executing a workflow manually or through the Execute via API capability.

Workflow Structure

1. start_step

Description

Every workflow must have exactly one start_step. It defines the entry point of the workflow execution.

Behavior

• Must match the id of a step defined in the steps list
• Determines which step executes first
• Best practice: use the name "start_step", though any legal step name is permitted.

Example

start_step: start_step

2. steps

Description

Defines the sequence of steps executed in the workflow.

Each step follows a common structure. The fields listed below are available across all step types, with config varying based on the step type.

Configuration Schema

steps:
  - id: <step_id>
    type: <step_type>
    name: <step_name>
    config: {}
    next: <next_step_id>

Supported Keys

Behavior

• Workflow execution starts from start_step
• Each step executes based on its type
• The next field determines the next step
• If next is not defined, workflow execution ends

Notes

• The structure shown above is common to all step types.
• The config section varies depending on the step type.
• description is an optional workflow-level field and not required for execution.
  • Best practice: use clear names and don't include any description at all in most steps.

Step Categories and Types

1. Flow Lifecycle

1.1 Start

Description

Represents the entry point of the workflow. This step initializes execution and defines the first step to be executed.

Configuration Schema

- id: <step_id>
  name: <string>
  description: <string>
  type: start
  next: <step_id>

Supported Keys

Behavior

• This is always the first step in the workflow.
• It does not perform any processing.
• It routes execution to the next step using next.

Example

- id: start_step
  name: Initialize Workflow
  type: start
  next: next_step

1.2 End

Description

Represents the final step of the workflow. This step completes execution and can optionally send notifications.

Configuration Schema

- id: <step_id>
  name: <string>
  type: end
  config:
    summarize: <boolean>
    notify:
      - channel: <email|teams|sms>
        to:
          - <recipient>

Supported Keys

Configuration Keys

notify Keys

Supported Channels

• Email
• Teams
• SMS

Behavior

• Marks the completion of the workflow
• Optionally summarizes execution results
• Sends notifications via configured channels
• No further steps are executed after this

Behavior Notes

• This is the final step in the workflow
• Notification behavior depends on configuration
• Summary content is system-generated

Example

- id: end_step
  name: Finalize Workflow
  type: end
  config:
    summarize: true
    notify:
      - channel: email
        to:
          - "user@example.com"
      - channel: teams
      - channel: sms
        to:
          - "+1234567890"

2. Process Steps

2.1 Call API

Description

Executes a REST API operation using a configured API connection and endpoint.

This step allows workflows to interact with external systems by sending HTTP requests and processing responses.

Behavior:

• Select API Collection
• Select API Operation

• Required parameters are displayed dynamically
• Executes as a standard REST call

For more information on creating API collection refer to the article Creating a API Collection

Configuration Schema

config:
  endpoint_id: number
  connection_id: number
  connection_name: string
  path_params:
    <param_name>: <value>

Supported Configuration Keys

Parameter Handling

Path Parameters

Path parameters are defined in the API endpoint using {} syntax.

Example endpoint:

/users/{user_id}

To pass values:

path_params:
  user_id: "{{ user_id }}"

Additional Parameters

• Request body, query parameters, and headers are derived from the selected API operation configuration
• These fields are dynamically resolved based on the endpoint definition

Note: The exact structure of these parameters depends on how the API operation is defined in the API Collection.

Behavior

• Executes the configured API operation using the associated connection
• Automatically applies endpoint configuration (method, URL, headers, etc.)
• Resolves dynamic values using Jinja expressions
• Sends request and waits for response

Output Behavior

• The API response is stored in the variable defined in the output field
• The response can be accessed by downstream steps

Minimum Working Example

- id: get_user
  name: Get User
  type: call_api
  config:
    endpoint_id: 101
    connection_id: 10
    connection_name: user_api

Example: API Call with Path Parameter

- id: fetch_user
  name: Fetch User Details
  type: call_api
  config:
    endpoint_id: 101
    connection_id: 10
    connection_name: user_api
    path_params:
      user_id: "{{ input_user_id }}"
  output: user_response
  next: process_user

2.2 Execute Database Query

Description

Executes a SQL query against a configured data source and returns the result set.

Configuration Schema

config:
  connection_id: <connection_id>
  sql: <query>
  timeout: <seconds>

Supported Keys

Config Keys

Query Support

• The sql field supports dynamic expressions
• Expressions are evaluated at runtime using workflow variables

Example

SELECT * FROM orders WHERE customer_id = {{ customer_id }}

Behavior

• Executes the SQL query using the specified connection
• Retrieves query results from the data source
• Stores the result set in the output variable (if defined)

Behavior Notes

• The query must be valid for the selected data source
• Dynamic values are resolved before execution
• Result format depends on the underlying data source

Minimum Working Example

- id: fetch_orders
  name: Fetch Orders
  type: db_action
  config:
    connection_id: 1001
    sql: "SELECT * FROM orders"

Example: Query with Dynamic Value

- id: fetch_customer_orders
  name: Fetch Customer Orders
  type: db_action
  config:
    connection_id: 1001
    sql: |
      SELECT *
      FROM orders
      WHERE customer_id = {{ customer_id }}
  output: customer_orders
  next: process_orders

2.3 Execute JDBC Operation

Description

Executes a predefined database operation using a configured JDBC connection and registered operation.

The operation is defined within a JDBC collection and referenced in the workflow using system-generated identifiers.

Configuration Schema

config:
  endpoint_id: <endpoint_id>
  connection_id: <connection_id>
  connection_name: <connection_name>
  sql_params:
    <param_name>: <value>

Supported Keys

Config Keys

Operation Selection

• The step executes a predefined operation from a JDBC collection
• The selected operation determines:
  • The underlying SQL logic
  • Required input parameters (if any)
• The workflow references the selected operation using:
  • endpoint_id
  • connection_id
  • connection_name

Parameter Handling

• Input parameters are defined as part of the JDBC operation configuration
• Values for these parameters are passed using sql_params
• Parameter values can be static or dynamically evaluated

Example

sql_params:
  customer_id: "{{ customer_id }}"
  status: "ACTIVE"

Behavior

• Executes the selected JDBC operation using the configured connection
• Resolves input parameters before execution
• Runs the predefined SQL logic associated with the operation
• Stores the result in the output variable (if defined)

Behavior Notes

• The SQL logic is predefined and not editable within the workflow
• Required parameters depend on the selected operation
• Missing required parameters may result in execution failure

Minimum Working Example

- id: fetch_customers
  name: Fetch Customers
  type: db_registry_action
  config:
    endpoint_id: 2001
    connection_id: 3001
    connection_name: customer_db

Example: JDBC Operation with Parameters

- id: fetch_active_customers
  name: Fetch Active Customers
  type: db_registry_action
  config:
    endpoint_id: 2001
    connection_id: 3001
    connection_name: customer_db
    sql_params:
      status: "ACTIVE"
  output: active_customers
  next: process_data

For more information on creating JDBC query collection refer to the article Creating a Query Collection

2.4 Execute Code

Description

Executes custom code within the workflow using the specified runtime.
This step enables dynamic data processing and transformation using Python or JavaScript.

Configuration Schema

inputs:
  <variable_name>: <source_variable>

config:
  language: <python|javascript>
  code: <string>
  requirements:
    - name: <library_name>
      version: <version>
  expected_keys:
    - <key_name>

The requirements field supports explicit version installation for non-preinstalled Python libraries. Libraries that are already preinstalled in the runtime environment will continue using the bundled version regardless of the specified version. The requirements section is not supported for JavaScript code steps.

# Preinstalled Python libraries in the runtime environment

PRE_INSTALLED = {
    "aioboto3",
    "authlib",
    "aws-cdk-lib",
    "boto3",
    "botocore",
    "cachetools",
    "cryptography",
    "geopandas",
    "httpx-oauth",
    "importlib",
    "jinja2",
    "markdown",
    "mypy-boto3-sqs",
    "numpy",
    "openai",
    "pandas",
    "paramiko",
    "psycopg2-binary",
    "pydantic",
    "pydantic-settings",
    "pyproj",
    "pyyaml",
    "python-dateutil",
    "pytz",
    "quickjs",
    "redis",
    "requests",
    "shapely",
    "six",
    "structlog",
    "tenacity",
    "twilio",
    "urllib3",
    "websocket-client",
    "websockets",
}

Supported Keys

Step-Level Keys

Config Keys

Step-Level Inputs

Description

Defines variables that will be available inside the code during execution.

Behavior

• Each key in inputs becomes a variable inside the code
• The value maps to an existing workflow variable
• These variables can be directly used without Jinja expressions

Example

inputs:
  orders: customer_orders

Python usage:

len(orders)

JavaScript usage:

orders.length

Behavior

• Executes the provided code using the selected language
• Input variables are injected into the execution context
• The code must return:
  • Python → a dictionary 
  • JavaScript → an object
• The returned output is validated against expected_keys
• If validation passes, the result is stored in the output variable

Output Validation

• The returned result must include all keys defined in expected_keys
• If any expected key is missing, the step execution fails

Language-Specific Requirements

Python

• Code must return a dictionary

Example:

return {
  "result": value
}

JavaScript

• Code must return an object

Example:

return {
  result: value
};

Minimum Working Example (Python)

- id: process_data
  name: Process Data
  type: code
  config:
    language: python
    code: |
      return {
        "message": "Hello World"
      }
    expected_keys:
      - message

Example: Using Inputs & requirements

- id: set_sample_orders
    type: variable_operation
    name: Set Sample Orders
    config:
      set:
        customer_orders:
          - amount: 120
          - amount: 80
          - amount: 150
          - amount: 50
    output: customer_orders
    next: calculate_order_summary

  - id: calculate_order_summary
    type: code
    name: Calculate Order Summary
    inputs:
      orders: customer_orders
    config:
      language: python
      requirements:
        - name: numpy
          version: "1.26.0"
      expected_keys:
        - total_orders
        - total_amount
        - average_amount
      code: |
        import numpy as np

        orders = inputs["orders"]["customer_orders"]

        total_orders = len(orders)

        amounts = [order.get("amount", 0) for order in orders]

        total_amount = sum(amounts)

        average_amount = float(np.mean(amounts)) if amounts else 0

        result = {
            "total_orders":   total_orders,
            "total_amount":   total_amount,
            "average_amount": average_amount
        }

    output: order_summary
    next: end_step

Example: Using Inputs (JavaScript)

- id: process_customer_issues
  name: Process Customer Issues
  type: code
  inputs:
    issues: customer_issues
  config:
    language: javascript
    code: |
      const high_priority = [];
      const normal_priority = [];

      for (const issue of issues) {
        if (issue.priority === "HIGH") {
          high_priority.push(issue);
        } else {
          normal_priority.push(issue);
        }
      }

      return {
        high_priority,
        normal_priority
      };
    expected_keys:
      - high_priority
      - normal_priority
  output: processed_issues
  next: end_step

2.5 Send Email

Description

Sends an email notification during workflow execution.

Configuration Schema

config:
  to:
    - <email_address>
  cc:
    - <email_address>
  subject: <string>
  message: <string>

Supported Keys

Config Keys

Behavior

• Sends an email to all recipients defined in to
• Includes additional recipients from cc (if provided)
• Evaluates dynamic expressions in subject and message (if used)
• Continues workflow execution after sending the email

Expression Support

• subject and message support dynamic expressions
• Expressions are evaluated using workflow variables

Behavior Notes

• At least one recipient must be defined in to
• Email formatting and delivery depend on system configuration

Example

- id: send_notification
  name: Send Notification Email
  type: email_action
  config:
    to:
      - "user@example.com"
      - "team@example.com"
    cc:
      - "admin@example.com"
    subject: "Order Processed"
    message: |
      Order {{ order_id }} has been successfully processed.
  next: end_step

2.6 Monitor Status

Description

Monitors external execution or system state and resumes the workflow based on defined conditions.

Supports polling-based monitoring.

Configuration Schema

config:
  strategy: <poll>
  endpoint_id: <endpoint_id>
  connection_id: <connection_id>
  interval_seconds: <number>
  max_duration_seconds: <number>
  max_retries: <number>
  check_expression: <expression>
  on_timeout: <step_id>

Configuration Fields

• strategy: Monitoring strategy. Supported values: poll
• endpoint_id: Identifier used to check status
• connection_id: Connection used for monitoring
• interval_seconds: Time between checks (used for polling)
• max_duration_seconds: Maximum duration for monitoring
• max_retries: Maximum number of monitoring attempts
• check_expression: Expression evaluated during each polling cycle
  • If true → monitoring stops and workflow proceeds to the next step
  • If false → monitoring continues until condition is met or timeout occurs
• on_timeout: Step executed if monitoring exceeds defined limits

Behavior

• Monitoring starts using polling
• For poll:
  • Periodically checks status using interval_seconds
  • Evaluates check_expression on each iteration
• Workflow resumes when the condition evaluates to true
• If monitoring exceeds limits (max_duration_seconds or max_retries):
  • Execution moves to on_timeout

Behavior Notes

• Monitoring is based on polling using check_expression
• Monitoring continues until a condition is satisfied or timeout occurs
• Expressions support dynamic evaluation

Example

- id: monitor_job
  name: Monitor Job Status
  type: monitor
  config:
    strategy: poll
    endpoint_id: 2001
    connection_id: 3001
    interval_seconds: 60
    max_duration_seconds: 3600
    max_retries: 10
    check_expression: "{{ status == 'COMPLETED' }}"
    on_timeout: failure_step
  output: monitor_result
  next: success_step

3. Prompt AI

3.1 DvSum AI Agent

Description

Executes a configured DvSum AI Agent within the workflow and returns a generated response based on the provided input.

Configuration Schema

config:
  endpoint_id: <endpoint_id>
  connection_id: <connection_id>
  connection_name: <connection_name>
  analysis_request:
    messages:
      human_message: <string>
    analysis_id: <string>
    audience_type: <string>
    response_type: <string>

Supported Keys

Config Keys

analysis_request Keys

Message Structure

The AI Agent expects input in the following format:

messages:
  human_message: <string>

• The value supports dynamic expressions (Jinja expressions)

Behavior

• Sends the configured request to the selected AI Agent
• Processes the input message
• Executes predefined agent logic
• Returns a response in the format defined by response_type
• Stores the result in the output variable (if defined)

Behavior Notes

• The agent logic is predefined and managed within the platform
• Input supports dynamic expressions
• Output structure depends on response_type

Minimum Working Example

- id: run_agent
  name: Run AI Agent
  type: ai_agent
  config:
    endpoint_id: 51596398
    connection_id: 51590185
    connection_name: DvSum Basic Auth
    analysis_request:
      messages:
        human_message: "Analyze this dataset"
      analysis_id: "45878166"
      audience_type: INTERNAL
      response_type: JSON

Example: Dynamic Input

- id: analyze_customer
  name: Analyze Customer
  type: ai_agent
  config:
    endpoint_id: 51596398
    connection_id: 51590185
    connection_name: DvSum Basic Auth
    analysis_request:
      messages:
        human_message: "Analyze customer {{ customer_id }}"
      analysis_id: "45878166"
      audience_type: CUSTOMER_FACING
      response_type: JSON
  output: analysis_result
  next: process_results

3.2 LLM Call

Description

Executes a direct prompt against a Large Language Model (LLM) and returns the generated response.

Unlike the AI Agent step, this step directly invokes the model without predefined agent logic.

Configuration Schema

config:
  parameters:
    max_tokens: <number>
    temperature: <number>
    top_p: <number>
    response_format: <string>
    presence_penalty: <number>
    frequency_penalty: <number>
  prompt_template: <string>

Supported Keys

Config Keys

parameters Keys

Behavior

• Sends the prompt_template to the LLM
• Evaluates dynamic expressions in the prompt (if used)
• Applies parameters to control generation behavior (if provided)
• Returns generated output
• Stores the result in the output variable (if defined)

Behavior Notes

• prompt_template supports dynamic expressions (Supported values:Jinja)
• If parameters are not provided, default model settings are used
• Output structure depends on response_format

Minimum Working Example

- id: generate_text
  type: llm_call
  config:
    prompt_template: "Summarize this data"

Example: LLM Call with Parameters

- id: analyze_customer
  type: llm_call
  config:
    parameters:
      max_tokens: 300
      temperature: 0.2
      top_p: 1
      response_format: json
      presence_penalty: 0
      frequency_penalty: 0
    prompt_template: "Analyze customer {{ customer_id }}"
  output: llm_result
  next: process_results

4. External Systems

4.1 Jira Cloud

Description

Executes a predefined Jira operation to create or update issues within a workflow.

Configuration Schema

config:
  endpoint_id: <endpoint_id>
  connection_id: <connection_id>
  connection_name: <connection_name>
  body:
    project: <string>
    issue_type: <string>
    summary: <string>
    description: <string>
    labels:
      - <string>
    priority: <string>
    fields:
      <key>: <value>
    attachments:
      - filename: <string>
        content_type: <string>
        context_path: <string>
    attachment_path: <string>

Supported Keys

Config Keys

Body Keys

Attachments Structure

Each attachment must include:

Behavior

• Executes the selected Jira operation using the configured connection
• Creates or updates a Jira issue based on body
• Evaluates dynamic expressions in all fields (if used)
• Uploads attachments if provided
• Stores the response in the output variable (if defined)

Behavior Notes

• The operation type (create/update) depends on the selected endpoint
• Required fields depend on the Jira configuration
• Custom fields can be passed via fields
• Attachment handling depends on system configuration

Minimum Working Example

- id: generate_text
  name: Generate Text
  type: llm_call
  config:
    prompt_template: "Summarize this data"

Example: Jira Issue with Dynamic Data

- id: analyze_customer
  name: Analyze Customer
  type: llm_call
  config:
    parameters:
      max_tokens: 300
      temperature: 0.2
      top_p: 1
      response_format: json
      presence_penalty: 0
      frequency_penalty: 0
    prompt_template: "Analyze customer {{ customer_id }}"
  output: llm_result
  next: process_results

5. Flow Controls

5.1 Decision

Description

Introduces conditional branching in the workflow by evaluating conditions and routing execution to the appropriate step.

Configuration Modes

The decision step supports two configurations:

• Case-based evaluation (`cases`)  
• Switch-based evaluation (`switch`)

1. Case-Based Decision

Configuration Schema

config:
  cases:
    - case: <expression>
      next: <step_id>
  fallback:
    next: <step_id>

Supported Keys

Behavior

• Evaluates cases sequentially (top to bottom)
• Each case is evaluated as a condition
• The first matching case is executed
• If no cases match:
  - Executes fallback.next if defined 
  - Otherwise, workflow execution ends

Expression Support

• Conditions support dynamic expressions (Jinja-style expressions)
• Expressions are evaluated using workflow variables

Example

- id: check_amount
  name: Check Amount
  type: decision
  config:
    cases:
      - case: "{{ total_amount > 1000 }}"
        next: high_value_step
      - case: "{{ total_amount > 0 }}"
        next: low_value_step
    fallback:
      next: end_step

2. Switch-Based Decision

Configuration Schema

config:
  switch: <variable_name>
  cases:
    - case: <value>
      next: <step_id>

Supported Keys

Behavior

• Evaluates the value of switch
• Compares it against each case value
• Executes the first matching next step
• If no match is found:
  - No fallback behavior is explicitly defined in the configuration

Example

- id: route_by_status
  name: Route by Status
  type: decision
  config:
    switch: order_status
    cases:
      - case: "SUCCESS"
        next: success_step
      - case: "FAILED"
        next: failure_step

5.2 Fan-Out

Description

Executes a child workflow for each item in a collection, enabling parallel processing of multiple inputs.

Configuration Schema

inputs:
  <variable_name>: <source_variable>

config:
  workflow: <workflow_id>
  iterate: <expression>
  item_name: <variable_name>
  on_error: <behavior>
  pass_context:
    <key>: <value>
  interval: <seconds>

Supported Keys

Step-Level Keys

Config Keys

Behavior

• Evaluates iterate to extract a list of items
• For each item:
  • Invokes the specified child workflow
  • Passes the item using item_name
  • Passes additional variables defined in pass_context (if provided)
• Executes all child workflow instances in parallel
• Monitors execution status using interval (if configured)
• Collects results from all executions
• Stores aggregated results in the output variable (if defined)

Input Mapping

• The current item is always passed using item_name
• Additional variables can be passed using pass_context
• Keys within pass_context are user-defined and not restricted to a fixed set

Error Handling

• on_error controls behavior when a child workflow execution fails
• Example:
  • continue → continues processing remaining items
  • fail → stops execution on first failure

Behavior Notes

• iterate must resolve to a list
• Each item is processed independently
• Execution is parallel and does not guarantee order of completion

Example 1: Basic Fan-Out (Item Only)

- id: process_orders
  name: Process Orders
  type: fanout
  inputs:
    orders: customer_orders
  config:
    workflow: 51589198
    iterate: orders
    item_name: order
    on_error: continue
  output: fanout_results

Example 2: Fan-Out with Additional Context

- id: process_orders_with_context
  name: Process Orders with Context
  type: fanout
  inputs:
    orders: customer_orders
    user_email: email
  config:
    workflow: 51589198
    iterate: orders
    item_name: order
    on_error: continue
    interval: 30
    pass_context:
      email: "{{ user_email }}"
  output: fanout_results

 Notes

• pass_context is optional and should only be used when additional variables (beyond the iterated item) are required
• Keys inside pass_context are dynamic and depend on the workflow design

5.3 Composite

Description

Executes multiple steps as a grouped unit, allowing parallel or sequential execution of tasks within a single step.

Configuration Schema

config:
  mode: <string>
  tasks:
    - id: <task_id>
      kind: <string>
      inputs: {}
      step_id: <step_id>

Supported Keys

Config Keys

tasks Keys

Behavior

• Executes all tasks defined in tasks
• Execution depends on mode:
  • parallel → tasks run simultaneously 
  • sequential → tasks run one after another
• Each task references an existing step using step_id
• Inputs can be passed to each task using inputs

Behavior Notes

• All referenced step_id values must exist in the workflow
• Task execution is controlled entirely by the mode
• Output handling depends on workflow design

Example

- id: composite_step
  name: Execute Tasks in Parallel
  type: composite
  config:
    mode: parallel
    tasks:
      - id: task1
        kind: step
        step_id: fetch_data_step
      - id: task2
        kind: step
        step_id: process_data_step

5.4 ForEach

Description

Processes a collection of items by grouping them based on a specified key and routing each group to a corresponding step.

Configuration Schema

inputs:
  <variable_name>: <source_variable>

config:
  items: <jmespath_expression>
  group_by: <jmespath_expression>
  routes:
    <group_value>:
      step: <step_id>

Supported Keys

Step-Level Keys

Config Keys

Behavior

• Evaluates items to extract a list of items
• Applies group_by expression to each item to determine its group
• Groups items based on the evaluated key
• For each group:
  • Matches the group value with a key in routes
  • Routes the grouped items to the configured step

Routing Logic

• Each key in routes represents a possible group value
• Each route defines a target step using:

step: <step_id>

Example Mapping

routes:
  HIGH:
    step: high_priority_step
  LOW:
    step: low_priority_step

Behavior Notes

• items must resolve to a list
• group_by must return a value for each item
• If a group value does not match any route:
  • Behavior is not explicitly defined and must be handled in workflow design

Example

- id: composite_step
  name: Composite Step Execution
  type: composite
  config:
    mode: parallel
    tasks:
      - id: task1
        kind: step
        step_id: fetch_dataset_1
      - id: task2
        kind: step
        step_id: fetch_dataset_2

5.5 Human in the Loop

Description

Introduces a manual intervention point in the workflow, allowing user input or approval before execution continues.

Configuration Schema

config:
  notify:
    - channel: <string>
      to:
        - <recipient>
      subject: <string>
      message: <string>
  choices:
    - id: <string>
      label: <string>
  decision:
    cases:
      - case: <string>
        next: <step_id>
        set:
          <variable_name>: <value>

Supported Keys

Config Keys

notify Keys

choices Keys

decision Keys

Choice Mapping

• The selected choice.label is used to evaluate decision.cases
• Each case must match a label value
• Routing is determined based on this match

Behavior

• Sends a notification via the configured channel. Supported values: email, teams
• Pauses workflow execution
• Waits for user input (selection from choices)
• Once a choice is selected:
  • Matches the selected label with decision.cases
  • Optionally assigns variables using set
  • Routes execution to the corresponding next step

Behavior Notes

• Workflow remains paused until user input is received
• set allows dynamic variable assignment based on user decision
• Notification content supports dynamic expressions

Example 1: Email Approval

- id: approval_step
  name: Approval Step
  type: human_in_loop
  config:
    notify:
      - channel: email
        to:
          - "approver@example.com"
        subject: "Approval Required"
        message: |
          Approve request for {{ customer_id }}

          {{ hitl_choices_table }}
    choices:
      - id: approve
        label: APPROVED
      - id: reject
        label: REJECTED
    decision:
      cases:
        - case: APPROVED
          next: approved_step
        - case: REJECTED
          next: rejected_step

Example 2: With Variable Assignment

- id: approval_with_flag
  name: Approval with Flag
  type: human_in_loop
  config:
    notify:
      - channel: teams
        to:
          - "team@example.com"
        subject: "Decision Required"
        message: |
          Select action

          {{ hitl_choices_table }}
    choices:
      - id: choice_a
        label: Case A
      - id: choice_b
        label: Case B
    decision:
      cases:
        - case: Case A
          next: step_a
        - case: Case B
          set:
            approval_status: "rejected"
          next: step_b

Notes

• Supports multiple notification channels (email, teams)
• Choice labels must align with decision cases
• Variable assignment using set is optional and dynamic

5.6 Variable Operation

Description

The variable_operation step is used to create or update workflow variables during execution.

It enables dynamic value assignment using static values or expressions, allowing downstream steps to consume computed or transformed data.

Configuration Schema

config:
  set:
    <variable_name>: <value>

Supported Configuration Keys

Behavior

• Each entry under set assigns a value to a variable
• If a variable already exists, its value is overwritten
• Variables defined in this step are available to all downstream steps

Supported Value Types

The following value types are supported:

• Static values
  (string, number, boolean)
• Jinja expressions
  Evaluated at runtime using available workflow variables

Expression Support

Jinja expressions must be defined using:

{{ expression }}

Example:

total_amount: "{{ order_values.item_price * order_values.quantity }}"

• Expressions can reference variables from previous steps
• Expressions are evaluated during execution

Output Behavior

• If the output field is defined at the step level, the result of the step is stored under the specified variable
• If output is not defined, variables assigned in set remain available within the workflow context

Note: The set variables themselves are accessible to downstream steps regardless of whether output is defined

Minimum Working Example

- id: set_status
  name: Set Status
  type: variable_operation
  config:
    set:
      status: "processed"

Example: Calculating a Value

- id: calculate_total
  name: Calculate Total
  type: variable_operation
  config:
    set:
      total_amount: "{{ order_values.item_price * order_values.quantity }}"
  output: total_result
  next: end_step

What this Example Does

• Reads item_price and quantity from order_values
• Calculates the total amount using a Jinja expression
• Assigns the result to total_amount
• Stores the step result in total_result (if used)
• Makes the computed value available for subsequent steps

Notes

• This step is typically used for:
  • Data transformation
  • Intermediate calculations
  • Preparing values for API or database steps
• Only the set configuration key is currently supported for this step type based on validated usage patterns