Skip to Content
DocsCore Components⚙️ Workflows

⚙️ Workflows

Workflows are the core building blocks of a Loopstack automation. They define the specific steps, logic, and tool interactions that make up your business processes. Workflows in Loopstack use a state machine pattern to create predictable, reliable automation with clear execution paths.

Overview

Every workflow in Loopstack follows a state machine pattern with:

  • Places: Represent states in the workflow (like start, dataExtracted, and end)
  • Transitions: Actions that move the workflow from one place to another
  • Tool Calls: Operations performed during transitions

State Machine and Transitions

A workflow is a directed graph that represents a business process as a series of states and transitions. Each workflow has a defined starting (start) and ending (end) point, with transitions that connect these states and specify the actions to be performed.

workflows:
  - name: document_processor_workflow
    type: stateMachine
    transitions:
 
      # First transition
      - name: extract_data
        from: start
        to: data_extracted
 
      # Second transition
      - name: transform_data
        from: data_extracted
        to: end

Tool Calls

At every transition one or more tool calls can be triggered. These tools do the actual work of retrieving, generating, manipulating and storing data.workspace

workflows:
  - name: document_processor_workflow
    title: "Document Processing Workflow"
    type: stateMachine
    transitions:
      - name: extract_data
        from: start
        to: data_extracted
        call:
 
          - tool: data_extraction_tool          # Tool call at first transition
            arguments:
              source: ${ context.variables.SOURCE_DOCUMENT }
            as: EXTRACTED_DATA
 
      - name: transform_data
        from: data_extracted
        to: end
        call:
 
          - tool: debug_tool                    # First tool call
            arguments:
              log: ${ EXTRACTED_DATA }
 
          - tool: data_transformation_tool      # Second tool call
            arguments:
              data: ${ EXTRACTED_DATA }

Workflow Configuration

Workflow Properties

A workflow definition requires the following properties:

  • name: (mandatory) Unique identifier
  • title: (optional) Display name in Studio
  • type: (mandatory) Type of workflow (currently only stateMachine)
  • transitions: (optional) List of transitions between places
  • extends: (optional) A workflow template to use
  • options: (optional) Options used in extended templates

Transitions

Transitions are the heart of workflow definitions. They define how the workflow moves from one state to another and what actions are performed during that movement.

Basic Transition Structure

transitions:
  - name: process_document               # Unique transition identifier
    from: start                          # Source place
    to:
     - document_processed                 # Target place when successful
     - processing_failed                  # Error state as alternative path
    onError: processing_failed            # Target place when an error occurs (optional)
    call:                                 # Tools to execute during transition (optional)
      - tool: document_processor_tool     # Tool to call
        arguments:                        # Arguments to pass to the tool
          input: ${ context.variables.SOURCE_DOCUMENT }       # Previously defined document
        as: PROCESSED_DOCUMENT                      # Variable to store the result (optional)

Transition Properties

Every transition must define these core properties:

  • name: Unique identifier for the transition
  • from: A single or multiple source places (states) for the transition
  • to: A single or multiple target place(s) (states) after the transition successfully completes.

Optional properties include:

  • onError: Target place to transition to if an error occurs during execution. If not error place is defined, the workflow will stop at the current place and their status set to error.
  • when: Condition type for the transition (e.g., manual for user interaction. Defaults to onEntry)

Why multiple “to” place definitions?

Loopstack allows defining multiple target places for transitions, providing advanced control over workflow execution paths When multiple target places are defined, the workflow engine resolves the next place using this process:

  • If a tool in the transition returns a nextPlace property, that value is used to select from the available target places
  • If no nextPlace is provided but multiple targets are defined, the first place in the list is used
  • If an error occurs during transition execution, the appropriate error place from the onError property is used

Tool Calls

Tool calls define the operations executed during a transition:

call:
  - tool: email_sender_tool       # Reference to a tool definition
    arguments:                    # Arguments required by the tool
      recipient: john@example.com
      subject: "Meeting Reminder"
      body: ${ context.variables.RENDERED_CONTENT }
    as: EMAIL_RESULT        # Store result in a variable

Multiple tool calls can be chained in a single transition:

call:
  - tool: data_extraction_tool
    arguments:
      source: ${ context.variables.SOURCE_DOCUMENT }
    as: EXTRACTED_DATA
    
  - tool: data_transformation_tool
    arguments:
      input: ${ EXTRACTED_DATA }
    as: TRANSFORMED_DATA

Note:

While chaining multiple tool calls within a single transition is technically possible, it’s generally better to use separate transitions for distinct business operations. This approach offers several benefits:

  • Improved Visibility: Each transition appears as a distinct step in the Studio UI, making execution flow easier to track
  • Better Error Handling: When each operation has its own transition, errors are isolated to specific steps
  • Easier Debugging: The state between operations is captured and inspectable
  • Simplified Recovery: Failed workflows can be resumed from the specific transition that failed

Use tool call chaining primarily for closely related operations or for adding supplementary information (like logging or debugging messages) to a primary operation.

Error Handling with onError

The onError property directs workflow execution to a different place when an error occurs:

transitions:
  - name: process_data
    from: start
    to:
     - data_processed
     - processing_failed
    onError: processing_failed      # Go here if an error occurs
    call:
      - tool: data_processor
        arguments:
          input: ${ context.variables.SOURCE_DOCUMENT }
        as: PROCESS_RESULT
 
  - name: handle_success
    from: data_processed
    to: end
    call:
      - tool: success_handler
 
  - name: handle_error
    from: processing_failed
    to: end
    call:
      - tool: error_handler
        arguments:
          error_message: "Data processing failed"

Manual Transitions

Use the when: manual property to create transitions that require user input:

transitions:
  - name: request_user_approval
    from: document_prepared
    to: waiting_for_approval
    call:
      - tool: create_document
        arguments:
          document: approval_form
  
  - name: process_user_approval
    from: waiting_for_approval
    to: approved
    when: manual         # Workflow pauses, waiting for user input
    call:
      - tool: approval_processor
        arguments:
          approval_data: ${ transition.payload } # Access the data from the user form

Data Flow

Workflows manage data through various mechanisms:

Using Template Variables

Data is passed between transitions using variables:

transitions:
  - name: extract_data
    from: start
    to: data_extracted
    call:
      - tool: data_extraction_tool
        as: EXTRACTED_DATA    # Export result to variable
  
  - name: process_data
    from: data_extracted
    to: end
    call:
      - tool: data_processor
        arguments:
          input: ${ EXTRACTED_DATA }    # Use variable

Accessing Pipeline Context

Workflows can access data from the pipeline context object:

transitions:
  - name: process_input
    from: start
    to: end
    call:
      - tool: data_processor
        arguments:
          customer_id: ${ context.custom.customerId }    # Access pipeline context

Using Template Options

A workflow template can access the parent workflow’s options like this:

transitions:
  - name: process_input
    from: start
    to: end
    call:
      - tool: data_processor
        arguments:
          customer_id: ${ options.customerId }    # Access template options

See more about extending workflows here.

Working with Documents

Documents are a powerful tool to store and retrieve data globally from other workflows of the same or parent pipelines or even any other pipeline within the same workspace.

Documents are loaded here using the built-in load_document tool and manipulated using the create_document or update_document tools.

 
# Workflow A:
...
transitions:
  - name: create_document
    from: start
    to: document_created
    call:
      - tool: create_document
        arguments:
          document: customer_profile
          update:
            content: "Hello"
 
# Workflow B:
...
transitions:
  - name: load_document
    from: start
    to: document_loaded
    call:
      - tool: load_document
        arguments:
          where:
            name: customer_profile

Please see the Documents section for more details about working with documents.

Workflow Execution States

Workflows can be in various states during execution:

  • pending: Workflow is queued for execution
  • running: Currently executing a transition
  • waiting: Paused, waiting for external input (e.g., manual action)
  • completed: Successfully reached an end state
  • failed: Execution stopped due to an error
  • cancelled: Manually stopped by a user

Further Information

Please see our Advanced Workflow Pattern section for many more examples including implementation guides and templates.

Best Practices

Workflow Design

  • Single Responsibility: Each workflow should focus on a specific business process
  • Clear State Naming: Use descriptive names for places that reflect the workflow state
  • Error Handling: Define error states and transitions for all critical operations
  • Modular Design: Break complex processes into smaller, reusable workflows
  • Documentation: Use the title and description property to provide clear descriptions

Next Steps

Now that you understand how to design and implement workflows, you’re ready to explore the powerful tools that make your workflows perform actual work.

Continue to Tools →

Last updated on
Batch Processing (factory)Transitions and Tool calling