Core Concepts

This page introduces the fundamental concepts of Stateway's process model.

Process Definition

A process definition is a versioned blueprint for a business process. It describes the sequence of activities, gateways, events, and their connections.

• Formats: BPMN 2.0 XML, JSON, or YAML
• Versioning: Each update creates a new version; previous versions remain accessible
• Key: A unique string identifier (e.g., expense-approval)

# Create a definition
POST /v1/definitions
{
  "key": "expense-approval",
  "name": "Expense Approval",
  "source_type": "bpmn",
  "source": "..."
}

Process Instance

A process instance is a running execution of a process definition. Each instance has:

• Status: running, completed, error, suspended, terminated
• Variables: A JSON object holding process data (e.g., amounts, decisions, payloads)
• Tokens: Execution pointers that move through the process graph

# Start an instance
POST /v1/instances
{
  "definition_key": "expense-approval",
  "variables": { "amount": 500, "requester": "john@acme.com" }
}

Execution Tokens

An execution token is a pointer that moves through the process graph. When a token arrives at an element (task, gateway, event), the engine executes that element and advances the token to the next connected element.

• Parallel gateways fork a single token into multiple tokens
• Join gateways wait for all incoming tokens before proceeding
• Exclusive gateways route a single token based on conditions

Element Types

Stateway supports the following BPMN element types:

Element	Type	Description
startEvent	Event	Entry point of a process
endEvent	Event	Terminal point; completes the instance
task	Activity	Generic automated task
userTask	Activity	Human task requiring manual completion
serviceTask	Activity	Calls an external HTTP service
sendTask	Activity	Fire-and-forget HTTP request
businessRuleTask	Activity	Evaluates a DMM decision model
exclusiveGateway	Gateway	Routes based on conditions (XOR)
parallelGateway	Gateway	Fork/join parallel paths (AND)
timerEvent	Event	Delays execution by duration, date, or cycle

Expressions

Stateway uses a secure expression syntax for conditions and dynamic values:

{{expression}}

Expressions can reference:

• variables.* — Process instance variables
• instance.* — Instance metadata (id, status, created_at)
• now() — Current timestamp

Examples:

# Gateway condition
condition: "{{variables.amount > 1000}}"

# String comparison
condition: "{{variables.status == 'approved'}}"

# Date check
condition: "{{variables.deadline > now()}}"

info

Expressions use a safe evaluator — no arbitrary code execution. Only variable access, comparisons, and basic operations are supported.

Human Tasks

A human task (userTask) pauses the process execution until a user completes it manually.

Lifecycle:

pending ──→ claimed ──→ completed
  ↑            │
  └───────────←┘ (unclaim / delegate)

• Claim: A user takes ownership of the task
• Complete: The user provides output variables and the process continues
• Delegate: Reassign the task to another user (returns to pending)
• Unclaim: Release the task back to the pool (pending)

Timers

Timer events support three ISO 8601 patterns:

Pattern	Example	Description
Duration	PT1H	Wait 1 hour before continuing
Date	2026-04-01T09:00:00Z	Wait until a specific timestamp
Cycle	R3/PT1H	Repeat 3 times, every 1 hour

Webhooks

Webhooks notify external systems when process events occur:

• Triggers: instance.started, instance.completed, instance.error, task.created, task.completed, task.overdue, timer.fired
• Security: HMAC-SHA256 signature on every delivery
• Reliability: Exponential backoff retry (up to 8 attempts)

Decision Models (DMM)

Stateway evaluates Decision Model (DMM) tables — similar to DMN but in JSON/YAML format:

• Hit Policies: FIRST, ALL, UNIQUE, RULE_ORDER, COLLECT, OUTPUT_ORDER, PRIORITY
• FEEL Expressions: Comparison, ranges, lists, negation
• Standalone or Embedded: Evaluate directly via API or as a businessRuleTask

Credentials

Credentials store secrets (API keys, passwords, tokens) that service tasks need to call external services. Storing secrets in credentials keeps them out of process definitions.

• Storage: Encrypted at rest with AES-256-GCM
• Reference: Use {{credentials.name}} in taskHeaders at design time
• Resolution: The engine resolves the credential value at execution time — never written to logs or audit records
• Value privacy: The credential value is never returned by any API response

See Credentials for the full management API.

Monitoring

The monitoring API exposes operational metrics scoped to the current tenant:

• Instance counts by status (running, completed, error, …)
• Human task counts by status
• Service task job counts (pending, running, failed, timeout)
• Timer job counts (scheduled, overdue)
• Webhook delivery counts (pending, success, failed)

A single endpoint — GET /v1/monitoring/summary — returns all metrics. No special scope is required; any valid API key can call it.

See Monitoring for full documentation.

Multitenancy

Every resource in Stateway is isolated by tenant:

• All queries are automatically filtered by tenant
• The tenant is resolved from the API key — never passed explicitly
• Complete data isolation between tenants

Next Steps

• Processes — Create processes in any format
• Human Tasks — Implement user task workflows
• Decision Models — Build and evaluate decision tables
• MCP — Integrate with LLM-based automation