Skip to content

YAML Flow Structure

Jean-Marc Strauven edited this page Aug 6, 2025 · 1 revision

πŸ“– YAML Flow Structure

← Understanding YAML Flows | Home | PHP Steps β†’

Complete reference for Laravel Flowpipe YAML flow syntax and structure.

πŸ“‹ Complete YAML Schema

# =============================================================================
# FLOW METADATA
# =============================================================================
flow: string                    # Required: Unique flow identifier
description: string             # Required: Human-readable description
version: string                 # Optional: Flow version (e.g., "1.0", "2.1")
tags: [string, ...]            # Optional: Categories/labels
timeout: integer               # Optional: Max execution time in seconds
author: string                 # Optional: Flow author
created_at: string             # Optional: Creation date
updated_at: string             # Optional: Last update date

# =============================================================================
# INITIAL DATA
# =============================================================================
send:                          # Optional: Initial payload data
  key: value                   # Any valid YAML data structure
  nested:
    data: value
  arrays:
    - item1
    - item2

# =============================================================================
# WORKFLOW STEPS
# =============================================================================
steps:                         # Required: Array of steps
  - type: action|closure|group|nested|foreach
    name: string               # Optional: Step identifier
    description: string        # Optional: Step description
    class: string              # For action steps: PHP class name
    action: string             # For closure steps: closure identifier
    config: {}                 # Optional: Step-specific configuration
    timeout: integer           # Optional: Step timeout in seconds
    on_error: stop|continue|retry  # Optional: Error handling behavior
    retry_attempts: integer    # Optional: Number of retry attempts
    when: condition            # Optional: Conditional execution

πŸ—οΈ Step Types Reference

Action Steps

Execute PHP classes implementing FlowStep:

- type: action
  name: validate-input           # Optional: Step identifier
  class: App\Steps\ValidateStep  # Required: Fully qualified class name
  description: Validate user input data
  config:                       # Optional: Passed to step constructor
    rules:
      - required
      - email
    timeout: 30
  timeout: 60                   # Optional: Step-specific timeout
  on_error: stop               # Optional: stop|continue|retry
  retry_attempts: 3            # Optional: Number of retries
  when:                        # Optional: Conditional execution
    field: validation_enabled
    operator: equals
    value: true

Closure Steps

Execute predefined PHP closures:

- type: closure
  name: transform-data
  action: uppercase_name        # Closure identifier
  description: Convert name to uppercase
  config:                       # Passed to closure
    case: upper
  when:
    field: transform_enabled
    operator: equals
    value: true

Group Steps

Execute reusable step collections:

- type: group
  name: user-validation         # Group name (references groups/user-validation.yaml)
  description: Validate user data
  config:                       # Passed to all group steps
    strict_mode: true
  when:
    field: validation_required
    operator: equals
    value: true

Nested Steps

Create inline sub-workflows:

- type: nested
  name: payment-processing
  description: Process payment securely
  timeout: 120                  # Timeout for entire nested flow
  steps:                        # Inline step definitions
    - type: action
      class: ValidatePaymentStep
    - type: action
      class: ProcessPaymentStep
      config:
        gateway: stripe
  on_error: stop               # Error handling for nested flow

Foreach Steps

Iterate over arrays:

- type: foreach
  name: process-items
  array: items                 # Field name containing array
  description: Process each item individually
  timeout: 300                 # Total timeout for all iterations
  steps:                       # Steps executed for each item
    - type: action
      class: ValidateItemStep
    - type: action
      class: ProcessItemStep
  on_error: continue           # continue|stop (what to do if one item fails)

πŸ”€ Conditional Execution

Basic Conditions

when:
  field: status                # Field to check in payload
  operator: equals             # Comparison operator
  value: active               # Value to compare against

Available Operators

# Equality
operator: equals             # field == value
operator: not_equals         # field != value

# Comparison  
operator: greater_than       # field > value
operator: less_than         # field < value
operator: greater_than_or_equal  # field >= value
operator: less_than_or_equal     # field <= value

# String operations
operator: contains          # string contains substring
operator: not_contains      # string does not contain substring
operator: starts_with       # string starts with value
operator: ends_with         # string ends with value

# Array operations
operator: in                # value in array
operator: not_in           # value not in array

# Existence
operator: exists           # field exists in payload
operator: not_exists       # field does not exist in payload

# Type checking
operator: is_null          # field is null
operator: is_not_null      # field is not null
operator: is_empty         # field is empty ([], "", null, 0)
operator: is_not_empty     # field is not empty

Complex Conditions

# Multiple conditions (AND)
when:
  all:
    - field: status
      operator: equals
      value: active
    - field: verified
      operator: equals
      value: true

# Multiple conditions (OR)
when:
  any:
    - field: role
      operator: equals
      value: admin
    - field: role
      operator: equals
      value: moderator

# Nested conditions
when:
  all:
    - field: user_type
      operator: equals
      value: premium
    - any:
        - field: country
          operator: equals
          value: US
        - field: country
          operator: equals
          value: CA

Conditional Steps with Then/Else

steps:
  - condition:
      field: payment_required
      operator: equals
      value: true
    then:                      # Steps executed if condition is true
      - type: action
        class: ProcessPaymentStep
      - type: action
        class: SendReceiptStep
    else:                      # Steps executed if condition is false
      - type: action
        class: MarkAsFreeStep
      - type: action
        class: SendConfirmationStep

βš™οΈ Configuration Options

Global Configuration

flow: my-flow
description: Example flow
timeout: 300                   # Global timeout for entire flow
parallel: true                 # Enable parallel execution where possible
trace: true                   # Enable detailed tracing
queue:                        # Queue configuration
  connection: redis
  queue: workflows
  delay: 60                   # Delay in seconds

Step Configuration

- type: action
  class: ApiCallStep
  config:                     # Passed to step constructor/handle method
    endpoint: https://api.example.com
    method: POST
    timeout: 30
    headers:
      Authorization: Bearer token
      Content-Type: application/json
    retry:
      attempts: 3
      delay: 1000             # Milliseconds
      backoff: exponential    # linear|exponential

🚨 Error Handling

Step-Level Error Handling

- type: action
  class: ApiCallStep
  on_error: retry              # stop|continue|retry
  retry_attempts: 3
  retry_delay: 1000           # Milliseconds between retries
  retry_backoff: exponential  # linear|exponential
  fallback:                   # Fallback step if all retries fail
    type: action
    class: UseCachedDataStep

Flow-Level Error Handling

flow: my-flow
description: Example with error handling
on_error: compensate          # stop|continue|compensate
compensation:                 # Steps to run if flow fails
  - type: action
    class: RollbackChangesStep
  - type: action
    class: NotifyAdminStep

πŸ“Š Advanced Features

Parallel Execution

steps:
  - type: parallel
    name: concurrent-operations
    description: Run steps in parallel
    steps:
      - type: action
        class: SendEmailStep
      - type: action
        class: UpdateCacheStep
      - type: action
        class: LogEventStep
    wait_for: all              # all|any|number (e.g., 2)
    timeout: 60               # Timeout for parallel execution

Dynamic Step Generation

- type: dynamic
  name: generate-steps
  generator: generate_user_steps  # PHP method that returns step array
  config:
    template: user_processing
    count: "{{ user_count }}"    # Template variable

Variable Substitution

send:
  user_id: 123
  environment: production

steps:
  - type: action
    class: ApiCallStep
    config:
      endpoint: "https://{{ environment }}.api.example.com/users/{{ user_id }}"
      timeout: "{{ timeout | default: 30 }}"

πŸ“ Comments and Documentation

YAML Comments

# This is a full-line comment
flow: my-flow  # This is an inline comment

# Multi-line comments
# can span multiple lines
# for detailed explanations

description: |
  This is a multi-line description
  that preserves line breaks and
  can contain detailed documentation.

Self-Documenting YAML

flow: ecommerce-order-processing
description: |
  Complete e-commerce order processing workflow.
  
  This flow handles:
  1. Order validation and inventory checks
  2. Payment processing with retry logic  
  3. Fulfillment and shipping
  4. Customer notifications
  
  Expected payload structure:
  - order_id: string
  - items: array of {sku, quantity, price}
  - customer: {id, email, address}
  - payment_method: string

version: "2.1"
author: "Development Team"
tags: [ecommerce, orders, payment, fulfillment]

# Initial test data for development
send:
  order_id: "ORD-12345"
  # ... rest of test data

🎯 Best Practices

1. Consistent Naming

# Use kebab-case for names
- type: action
  name: validate-user-input
  class: ValidateUserInputStep

# Use descriptive, action-oriented names
- type: action
  name: send-welcome-email
  class: SendWelcomeEmailStep

2. Logical Step Organization

steps:
  # Group validation steps
  - type: group
    name: input-validation
    
  # Group business logic steps  
  - type: group
    name: order-processing
    
  # Group notification steps
  - type: group
    name: notifications

3. Comprehensive Error Handling

- type: action
  class: CriticalOperationStep
  on_error: retry
  retry_attempts: 3
  retry_backoff: exponential
  fallback:
    type: action
    class: SafeFallbackStep

4. Documentation

flow: complex-workflow
description: |
  Detailed description of what this workflow does,
  when it should be used, and any important considerations.
  
steps:
  - type: action
    name: critical-step
    class: CriticalStep
    description: |
      This step performs a critical operation that:
      - Must not fail in production
      - Has a 30-second timeout
      - Requires admin permissions

πŸ”— What's Next?

πŸš€ Laravel Flowpipe

🏠 Home

🏁 Getting Started

πŸ“š Core Concepts

πŸš€ Advanced Features

πŸ› οΈ Tools & Configuration

πŸ“– Examples


πŸ”— GitHub Repository

Clone this wiki locally