Core Concepts

Workflow Definition vs Workflow Instance

Workflow Definition

A workflow definition is a template that describes the structure of a business process. It includes: - State machines (one or more per workflow) - States and transitions - ETL chain references for actions - Guard conditions for conditional logic - Configuration (database, collection, chainset)

Think of it as a class in object-oriented programming - it defines the structure but doesn’t hold runtime data.

Workflow Instance

A workflow instance is a specific execution of a workflow definition. It includes: - Current state in each state machine - Instance-specific data (public and private) - History of state transitions - Unique identifier

Think of it as an object - a specific instance with its own data and state.

Example: A “Leave Request” workflow definition might have 1000 instances, one for each employee’s leave request.

State Machines

A state machine is a computational model consisting of: - States - Discrete conditions or stages in a process - Transitions - Paths between states - Events - Triggers that cause transitions

States

States represent stages in your business process. Every workflow has at least two states:

  • Start State - Entry point (automatically created)
  • Stop State - Exit point (automatically created)
  • Regular States - Your business process stages

State Properties: - Label - Human-readable name - OnEntry - ETL chain executed when entering this state - OnExit - ETL chain executed when leaving this state - OnAfter - Deferred event scheduled after entering this state - Super State - Parent state for nesting (optional) - History - Remember last sub-state for re-entry (optional)

Transitions

Transitions define how the workflow moves between states.

Transition Properties: - Label - Human-readable name - Event - Event name that triggers this transition (optional - empty means any event) - Guard - Condition that must be true for transition to fire - OnTransition - ETL chain executed during the transition

Transition Flow: 1. Event arrives at workflow instance 2. Current state’s outgoing transitions are evaluated 3. First transition matching the event name (or with empty event) is checked 4. Guard condition is evaluated (if present) 5. If guard passes, transition fires: - Current state’s OnExit chain executes - Transition’s OnTransition chain executes - Target state’s OnEntry chain executes 6. Workflow instance state is updated

Events

Events are messages sent to workflow instances to trigger transitions.

Event Structure:

{
  "name": "approve",
  "data": {
    "approver": "john.smith",
    "comments": "Approved with conditions",
    "timestamp": "2026-02-28T10:00:00Z"
  }
}

Event Sources: - REST API calls (sendEvent) - ETL chains (workflow.SendEvent step) - Deferred events (scheduled via OnAfter property) - Workflow creation (sendCreate - implicit event)

Event Matching: - If transition has specific event name, only that event triggers it - If transition has empty event name, any event can trigger it - First matching transition fires (order matters)

Data Model

Workflow instances store data in a structured JSON document with reserved fields:

elxPublic

Purpose: Data shared with the browser/client application

Use Cases: - Form data visible to users - Display information - Non-sensitive business data

Example:

{
  "elxPublic": {
    "employeeName": "Jane Doe",
    "leaveType": "Annual",
    "startDate": "2026-03-01",
    "endDate": "2026-03-05",
    "days": 5,
    "status": "Pending Approval"
  }
}

elxPrivate

Purpose: Server-side only data, never sent to browser

Use Cases: - Sensitive information (salary, SSN, etc.) - Internal processing data - System-generated values - Approval notes

Example:

{
  "elxPrivate": {
    "approverComments": "Approved due to exceptional circumstances",
    "salaryImpact": 2500.00,
    "internalNotes": "Manager override applied"
  }
}

elxHistory

Purpose: Audit trail of all state transitions

Structure: Array of history entries, each containing: - user - Who triggered the transition - startState - State before transition - transitionEvent - Event that triggered transition - endState - State after transition - ts - Timestamp

Example:

{
  "elxHistory": [
    {
      "user": "jane.doe",
      "startState": ["Start"],
      "transitionEvent": "submit",
      "endState": ["Pending Approval"],
      "ts": "2026-02-28T09:00:00Z"
    },
    {
      "user": "manager.smith",
      "startState": ["Pending Approval"],
      "transitionEvent": "approve",
      "endState": ["Approved"],
      "ts": "2026-02-28T10:00:00Z"
    }
  ]
}

elxRedirect

Purpose: Control browser navigation after workflow operations

Use Cases: - Redirect to confirmation page after submission - Navigate to dashboard after approval - Return to form on validation failure

Example:

{
  "elxRedirect": "/leave-requests/confirmation"
}

elxEvent

Purpose: Current event data being processed

Lifecycle: Present during event processing, removed after

Example:

{
  "elxEvent": {
    "approver": "john.smith",
    "decision": "approved"
  }
}

elxAppId

Purpose: Application context identifier

Use Cases: - Multi-tenant applications - Application-specific routing - Context preservation

Workflow Lifecycle

1. Design Phase

  • Create workflow definition in Workflow Designer
  • Define states, transitions, and ETL integration
  • Configure database and collection
  • Test with sample data

2. Instance Creation

  • REST API call: sendCreate(workflowId, initialData)
  • ETL chain: workflow.CreateInstance step
  • Initial state set to Start state
  • OnEntry chain of first state executes
  • Instance stored in configured database/collection

3. Event Processing

  • Event sent via REST API or ETL
  • Workflow engine evaluates transitions
  • Guard conditions checked
  • ETL chains execute (OnExit, OnTransition, OnEntry)
  • State updated
  • History recorded

4. Deferred Events

  • OnAfter property schedules future events
  • Agenda system manages scheduled events
  • Events fire at specified time
  • Normal event processing occurs

5. Completion

  • Workflow reaches Stop state
  • Final OnEntry chain executes
  • Instance remains in database for audit
  • Can be archived or cleaned up via ETL

ETL Integration Points

Workflows integrate with ETL chains at multiple points:

OnEntry (State Property)

When: Entering a state Use Cases: - Send notification emails - Update external systems - Calculate derived values - Initialize state-specific data

OnExit (State Property)

When: Leaving a state Use Cases: - Cleanup temporary data - Log state exit - Validate data before transition

OnTransition (Transition Property)

When: During state transition Use Cases: - Validate transition data - Transform data for next state - Update related records - Send notifications

Guard (Transition Property)

When: Before transition fires Purpose: Conditional logic - transition only fires if guard returns true Types: - ETL Chain guard - Chain must return success - State Machine guard - Another state machine must be in specific state

OnAfter (State Property)

When: Scheduled time after entering state Use Cases: - Timeout handling - Reminder notifications - Escalation - Auto-approval after deadline

Multiple State Machines

A single workflow can contain multiple state machines that execute in parallel.

Use Cases: - Main process + audit trail - Primary workflow + SLA tracking - Parallel approval paths - Independent sub-processes

Execution Model: - All state machines process the same event - Each maintains its own state - Guards can check state of other state machines - Useful for complex coordination

Example: Leave request workflow with two state machines: 1. Approval Flow: Draft → Pending → Approved → Closed 2. SLA Tracker: On Time → Warning → Overdue

Next Steps

Next: Quick Start Guide