Workflows

Define state machines with transitions to model process flows.

Keywords

  • workflow - Define a workflow/state machine
  • state - Define a state and its transitions
  • transition - Alternative keyword for state transitions
  • initial - Mark a state as the initial/starting state
  • final - Mark a state as a final/terminal state

workflow Keyword

Define state machines that model process flows with explicit state transitions.

Syntax

workflow WorkflowName {
    state stateName -> targetState1, targetState2
    state anotherState -> finalState
}
✨ Edit in Studio

State Transitions

Use the arrow operator -> to define transitions:

  • Single transition: state a -> b
  • Multiple transitions: state a -> b, c, d
  • No transitions: state terminal (final state)

Examples

Basic Workflow

workflow OrderProcessing {
    state pending -> processing
    state processing -> shipped
    state shipped -> delivered
}
✨ Edit in Studio

Workflow with Branching

workflow OrderFlow {
    state pending -> processing, cancelled
    state processing -> shipped, failed
    state shipped -> delivered
    state failed -> retry, refunded
    state delivered
    state cancelled
    state refunded
}
✨ Edit in Studio

Document Lifecycle

workflow DocumentLifecycle {
    state draft -> review
    state review -> approved, rejected
    state approved -> published
    state published -> archived
    state rejected -> draft
    state archived
}
✨ Edit in Studio

initial and final Keywords

Mark special states in the workflow.

Initial State

workflow UserJourney {
    state initial landing -> signup, login
    state signup -> verify_email
    state verify_email -> dashboard
    state login -> dashboard
    state dashboard -> profile, settings, logout
}
✨ Edit in Studio

Final State

workflow PaymentFlow {
    state initiated -> processing
    state processing -> completed, failed
    state failed -> retry, cancelled
    state retry -> processing
    state final completed
    state final cancelled
}
✨ Edit in Studio

transition Keyword

Alternative syntax for defining transitions (less common).

workflow ProcessFlow {
    state start
    transition start -> validate
    
    state validate
    transition validate -> process
    transition validate -> error
    
    state process
    transition process -> complete
    
    state complete
    state error
}
✨ Edit in Studio

Advanced Patterns

Multi-Stage Approval

workflow ApprovalProcess {
    state submitted -> level1_review
    state level1_review -> level1_approved, level1_rejected
    state level1_approved -> level2_review
    state level2_review -> level2_approved, level2_rejected
    state level2_approved -> published
    state level1_rejected -> revision
    state level2_rejected -> revision
    state revision -> submitted
    state published
}
✨ Edit in Studio

E-Commerce Order Flow

workflow CompleteOrderFlow {
    # Order placement
    state cart -> checkout
    state checkout -> payment_pending
    
    # Payment
    state payment_pending -> payment_processing
    state payment_processing -> payment_completed, payment_failed
    state payment_failed -> payment_retry, order_cancelled
    state payment_retry -> payment_processing
    
    # Fulfillment
    state payment_completed -> preparing
    state preparing -> ready_to_ship
    state ready_to_ship -> shipped
    state shipped -> in_transit
    state in_transit -> delivered, delivery_failed
    state delivery_failed -> return_to_sender
    
    # Completion
    state delivered -> completed
    state return_to_sender -> refund_initiated
    state refund_initiated -> refunded
    
    # Final states
    state final completed
    state final order_cancelled
    state final refunded
}
✨ Edit in Studio

Content Publishing

workflow ContentPublishing {
    state initial draft -> ready_for_review
    state ready_for_review -> in_review
    state in_review -> approved, needs_changes
    state needs_changes -> draft
    state approved -> scheduled, published
    state scheduled -> published
    state published -> updated, archived
    state updated -> in_review
    state final archived
}
✨ Edit in Studio

Integration with Agents

Workflows can be combined with agents to create state-aware systems.

workflow TicketFlow {
    state open -> assigned
    state assigned -> in_progress
    state in_progress -> resolved, escalated
    state escalated -> assigned
    state resolved -> closed, reopened
    state reopened -> assigned
    state final closed
}

agent TicketAgent {
    can create ticket when submitted
    must assign ticket when open
    can update status to in_progress when assigned
    should escalate when complex
    must resolve ticket when fixed
    can close ticket when resolved
}
✨ Edit in Studio

Best Practices

Naming Conventions

  • PascalCase for workflow names: OrderProcessing, UserOnboarding
  • snake_case for state names: pending, in_progress, payment_completed
  • Descriptive state names that indicate status

Workflow Design

  1. Keep it simple - Start with core states
  2. Handle errors - Include failure states and recovery paths
  3. Define terminal states - Make final states explicit
  4. Avoid cycles unless necessary for business logic
  5. Document complex flows with comments

State Organization

workflow WellStructuredFlow {
    # 1. Initial/Entry states
    state initial new -> validation
    
    # 2. Processing states
    state validation -> approved, rejected
    state approved -> processing
    state processing -> completed, failed
    
    # 3. Error/Recovery states
    state failed -> retry, cancelled
    state retry -> processing
    state rejected -> revision
    state revision -> validation
    
    # 4. Final states
    state final completed
    state final cancelled
}
✨ Edit in Studio

Common Patterns

Linear Flow

workflow LinearProcess {
    state step1 -> step2
    state step2 -> step3
    state step3 -> completed
    state final completed
}
✨ Edit in Studio

Branching Flow

workflow BranchingProcess {
    state start -> option_a, option_b, option_c
    state option_a -> merge
    state option_b -> merge
    state option_c -> merge
    state merge -> completed
}
✨ Edit in Studio

Loop Flow

workflow LoopProcess {
    state process -> validate
    state validate -> success, retry
    state retry -> process
    state success -> completed
}
✨ Edit in Studio

Parallel Flow

workflow ParallelProcess {
    state start -> task_a, task_b, task_c
    state task_a -> sync_point
    state task_b -> sync_point
    state task_c -> sync_point
    state sync_point -> completed
}
✨ Edit in Studio

Complete Example

# Comprehensive Task Management Workflow

workflow TaskManagement {
    # Creation phase
    state initial created -> assigned
    
    # Assignment phase
    state assigned -> in_progress, on_hold
    
    # Execution phase
    state in_progress -> code_review, testing, blocked
    state blocked -> in_progress
    
    # Review phase
    state code_review -> approved, changes_requested
    state changes_requested -> in_progress
    
    # Testing phase
    state testing -> passed, failed
    state failed -> in_progress
    
    # Completion phase
    state approved -> merged
    state passed -> merged
    state merged -> deployed
    state deployed -> verified
    state verified -> completed
    
    # Alternative outcomes
    state on_hold -> assigned, cancelled
    
    # Final states
    state final completed
    state final cancelled
}

agent TaskManager {
    can create task
    must assign task when created
    can start work when assigned
    should update status when progress_made
    must request review when ready
    can deploy when approved
    must verify deployment
    can mark completed when verified
}
✨ Edit in Studio

Related Keywords

  • agent - Agents execute workflows
  • enum - Enums can represent states
  • Control Flow - Conditional logic in workflows

Next Steps