Skip to main content

State Machine Nodes

This guide covers all state machine nodes for managing workflows with states and transitions.

Overview​

State machine nodes let you create and manage workflows that progress through different stages. Perfect for:

  • Support tickets (open → assigned → resolved → closed)
  • Orders (pending → paid → shipped → delivered)
  • User trials (trial → active → premium)
  • Game quests (locked → available → active → completed)

Reduction: 90% fewer nodes - What took 25-30 nodes now takes 3-5 nodes.

state.create​

Create a new state machine instance

Configuration​

FieldTypeRequiredDescription
machine_typeString✅Workflow identifier (e.g., "support_ticket")
instance_idStringOptionalUnique ID (auto-generated if empty)
statesObject✅State definitions with transitions
initial_stateString✅Starting state name
dataObjectOptionalInitial metadata

State Definition Format​

{
  "state_name": {
    "transitions": ["allowed_state_1", "allowed_state_2"],
    "guards": {
      "allowed_state_1": "condition_expression"
    },
    "on_enter": "action_name",
    "on_exit": "action_name",
    "timeout": {
      "duration": "24h",
      "to_state": "next_state"
    }
  }
}

Outputs​

  • NEXT: Instance created successfully
    • InstanceID (String): Unique instance ID
    • State (String): Initial state
    • Instance (Object): Full instance data
  • Error: Creation failed
    • ErrorText (String): Error message

Example​

{
  "machine_type": "support_ticket",
  "instance_id": "ticket_{{var.counter}}",
  "states": {
    "open": {
      "transitions": ["assigned", "cancelled"]
    },
    "assigned": {
      "transitions": ["resolved", "escalated"],
      "timeout": {
        "duration": "24h",
        "to_state": "escalated"
      }
    },
    "resolved": {
      "transitions": ["closed", "reopened"]
    }
  },
  "initial_state": "open"
}

state.transition​

Transition to a new state with validation

Configuration​

FieldTypeRequiredDescription
instance_idString✅Instance to transition
to_stateString✅Target state name
metadataObjectOptionalTransition metadata
skip_guardsBooleanOptionalBypass guard validation

Outputs​

  • Success: Transition succeeded
    • FromState (String): Previous state
    • ToState (String): New state
    • Instance (Object): Updated instance
    • OnExitAction (String): On-exit action name
    • OnEnterAction (String): On-enter action name
  • Invalid: Transition not allowed
    • FromState, ToState, ErrorMessage
  • GuardFailed: Guard condition failed
    • FromState, ToState, ErrorMessage, GuardExpr
  • NotFound: Instance doesn't exist
    • ErrorMessage

Example​

{
  "instance_id": "{{var.ticket_id}}",
  "to_state": "assigned",
  "metadata": {
    "assigned_to": "{{admin.id}}",
    "notes": "Urgent issue"
  }
}

state.get​

Query current state and metadata (Pure)

Configuration​

FieldTypeRequiredDescription
instance_idString✅Instance to query

Outputs​

  • Found: Instance exists
    • CurrentState (String): Current state name
    • MachineType (String): Machine type
    • Data (Object): Instance metadata
    • Instance (Object): Full instance
    • CreatedAt (String): ISO timestamp
    • UpdatedAt (String): ISO timestamp
  • NotFound: Instance doesn't exist

Example​

{
  "instance_id": "{{var.ticket_id}}"
}

state.history​

Get transition audit trail (Pure)

Configuration​

FieldTypeRequiredDescription
instance_idString✅Instance to query
limitNumberOptionalMax entries to return

Outputs​

  • Found: Instance exists
    • History (Array): Transition log
    • Count (Number): Total transitions
    • LastTransition (Object): Most recent
  • NotFound: Instance doesn't exist

History Entry Format​

{
  "from": "open",
  "to": "assigned",
  "timestamp": "2025-12-25T20:00:00Z",
  "user_id": 12345,
  "metadata": {"notes": "Urgent"}
}

Example​

{
  "instance_id": "{{var.ticket_id}}",
  "limit": 10
}

state.delete​

Remove instance from context

Configuration​

FieldTypeRequiredDescription
instance_idString✅Instance to delete

Outputs​

  • NEXT: Instance deleted
    • InstanceID (String): Deleted ID
  • NotFound: Instance doesn't exist

Example​

{
  "instance_id": "{{var.order_id}}"
}

Use Cases:

  • Clean up completed workflows
  • Cancel abandoned processes
  • Reset user state

state.list​

List/filter instances (Pure)

Configuration​

FieldTypeRequiredDescription
machine_typeStringOptionalFilter by type
stateStringOptionalFilter by current state

Outputs​

  • NEXT: Query complete
    • Instances (Array): Matching instances
    • Count (Number): Number of matches

Example​

Find all pending tickets:

{
  "machine_type": "support_ticket",
  "state": "pending"
}

Find all orders:

{
  "machine_type": "order"
}

state.update_data​

Update instance metadata

Configuration​

FieldTypeRequiredDescription
instance_idString✅Instance to update
dataObjectOptionalData to merge

Outputs​

  • NEXT: Data updated
    • Instance (Object): Updated instance
    • Data (Object): Current data
  • NotFound: Instance doesn't exist
    • ErrorMessage (String)

Example​

{
  "instance_id": "{{var.ticket_id}}",
  "data": {
    "priority": "high",
    "customer_email": "user@example.com"
  }
}

Behavior:

  • Merges data (doesn't replace)
  • New keys are added
  • Existing keys are updated

Advanced Features​

Guards​

Conditional transitions based on expressions.

{
  "states": {
    "pending": {
      "guards": {
        "completed": "payment_confirmed && items_shipped"
      }
    }
  }
}

If guard fails → GuardFailed output with expression details.

Actions​

Trigger events on state changes.

{
  "states": {
    "assigned": {
      "on_enter": "notify_assignee",
      "on_exit": "log_reassignment"
    }
  }
}

Actions returned in OnEnterAction/OnExitAction outputs.

Timeouts​

Auto-transition after duration.

{
  "states": {
    "pending_approval": {
      "timeout": {
        "duration": "48h",
        "to_state": "auto_approved"
      }
    }
  }
}

Duration formats: 24h, 30m, 2h30m

See Also​