📝 Configuration with YAML

Loopstack uses YAML (YAML Ain’t Markup Language) as its primary configuration format for defining automations. YAML’s human-readable syntax makes it ideal for creating and maintaining complex automation configurations while keeping them accessible to both technical and non-technical users.

Basic YAML Structure

YAML uses indentation (spaces, not tabs) to represent hierarchy and structure:


# Comments start with hash symbols
key: value                    # Simple key-value pair
number: 42                   # Numbers
boolean: true                # Boolean values
text: "quoted string"        # Strings (quotes optional for simple strings)
 
# Nested objects
parent:
  child: value
  another_child: "another value"
 
# Arrays/Lists
items:
  - first_item
  - second_item
  - third_item
 
# Array of objects
records:
  - name: "Alice"
    age: 30
  - name: "Bob"
    age: 25

Configuration Organization

Single File Structure

A typical Loopstack configuration file contains multiple sections:


# Include external files
include:
  - core/tools/create-document.yaml
  - core/tools/create-chat-message.yaml
 
# Define workspaces
workspaces:
  - name: my_workspace
    title: "My Automation Workspace"
 
# Define pipelines
pipelines:
  - name: my_pipeline
    type: root
    workspace: my_workspace
    sequence:
      - workflow: my_workflow
 
# Define workflows
workflows:
  - name: my_workflow
    type: stateMachine
    transitions:
      - name: first_step
        from: start
        to: end
 
# Define tools
tools:
  - name: my_tool
    execute:
      - handler: MyServiceHandler
        arguments:
          param: value
 
# Define documents
documents:
  - name: my_document
    schema:
      type: object
      properties:
        field:
          type: string

Modular Configuration

Use the include directive to split configurations across multiple files:


# main-config.yaml
include:
  - tools/data-processing-tools.yaml    # External tool definitions
  - workflows/customer-workflows.yaml   # External workflow definitions
 
pipelines:
  - name: customer_onboarding
    sequence:
      - workflow: verify_customer        # Defined in included file
      - workflow: create_account         # Defined in included file

This approach enables code reuse, team collaboration, and better maintainability through logical separation of concerns.

Best Practices

Naming Conventions

Use consistent, descriptive naming:


# Good: Clear, descriptive names
pipelines:
  - name: customer_onboarding_pipeline
  - name: order_processing_pipeline
 
# Avoid: Vague or cryptic names
pipelines:
  - name: pipeline1
  - name: proc_pipe

Documentation

Include meaningful comments and descriptions:


# Customer onboarding automation
pipelines:
  - name: customer_onboarding
    title: "Customer Onboarding Pipeline"
    description: "Automated customer registration and welcome process"
    sequence:
      - workflow: identity_verification          # Verify customer identity
      - workflow: account_creation              # Create customer account

File Organization

Structure your configuration files logically:


src/config/
├── core/                    # Shared, reusable components
│   ├── tools/
│   └── workflows/
├── projects/                # Project-specific configurations
│   ├── customer-service/
│   └── sales-automation/
└── examples/                # Example configurations

Validation

Loopstack automatically validates YAML configurations during startup:

Syntax validation: Ensures proper YAML formatting
Schema validation: Verifies configuration structure
Reference validation: Checks that referenced components exist

Invalid configurations will prevent execution and display clear error messages to help identify issues.