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; only instance.id is populated (status/created_at are not available here). Usable not only in conditions, but in the expression fields of element handlers (taskHeaders, ioMapping.*.source, assignee/candidateGroups/candidateUsers, conditionExpression, keyExpression) — see Variable Expressions for the full per-field reference
• session.* — The Frontend Gateway user whose action is advancing the process (who started the instance, completed the task or sent the event): session.userId and session.userDisplay. Stateway takes these from the session, not from variables. They are empty when no end user is acting, such as REST API calls, timers and signals. Not available in data store expressions (keyExpression, stateFilter). See Assigning to Whoever Started the Instance
• 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, UNIQUE, ALL, RULE_ORDER, COLLECT (OUTPUT_ORDER and PRIORITY are planned — currently fall back to ALL / FIRST)
• Conditions: structured { operator, value } per input in json / yaml; positional FEEL (comparison, ranges, lists, negation) in dmn_xml sources
• 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 the headers/authorization fields of taskHeaders, for serviceTask/sendTask only — see Credentials for the full scope
• 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