Core Concepts

This page introduces the fundamental building blocks of Priostack. Understanding these concepts will help you design, deploy, and operate workflows effectively.

Glossary of Terms

Term	Definition
Process Definition	A BPMN 2.0 XML document that describes the structure of a workflow: its start events, tasks, gateways, and end events. Think of it as the blueprint for a business process.
Process Instance	A single running execution of a process definition. Each time you start a workflow, you create a new instance with its own state, variables, and execution path.
Job	A unit of work generated when a Service Task is reached during execution. Jobs are activated by external workers, processed, and then completed via the API.
Task	A step within a process. Priostack supports Service Tasks (automated), User Tasks (human-assigned), Script Tasks, Send Tasks, and Receive Tasks.
Token	A conceptual marker that represents the current position of execution within a process instance. When a parallel gateway splits, multiple tokens flow through concurrent paths.
Variable	A named value stored on a process instance. Variables carry data between tasks, can be read/written by workers, and are used in FEEL expressions for routing decisions.
Service Task	A task executed automatically by an external worker. The engine creates a Job, which a worker activates, processes, and completes. No human interaction is required.
User Task	A task that requires human action. It appears in the Tasklist UI and must be claimed and completed by a user before the process advances.
Incident	A failure state created when a job cannot be completed (e.g., after retries are exhausted, or a worker reports an error). An incident blocks forward progress and requires manual intervention or retry.
Deployment	The act of uploading a process definition to Priostack so it can be instantiated. Each deployment creates a versioned snapshot of the BPMN.
Correlation Key	A unique identifier used to route incoming messages to the correct process instance. Used with Message Catch Events and Receive Tasks.
FEEL	Friendly Enough Expression Language. The standard expression language used in BPMN/DMN for conditions, mappings, and decision tables. See the FEEL Reference.
Hit Policy	A rule in a DMN decision table that determines what happens when multiple rows match. Common policies: UNIQUE, FIRST, RULE ORDER, COLLECT.
Layer 1	The BPMN/DMN/CMMN execution engine that interprets and runs process definitions.
Layer 2	The EIP (Enterprise Integration Patterns) message routing layer that manages message channels, routing, aggregation, and correlation between processes.

How Concepts Relate

The diagram below illustrates the relationship between the core concepts:


  Process Definition (BPMN XML) · deploy via POST /api/v1/process-definitions
        v
  [ Priostack Engine ] · start via POST /api/v1/process-instances
        v
  Process Instance (running execution) · +-- Variables { orderId: "123", amount: 99.99, ... }
     |
     v
  Execution Token moves through BPMN graph:

  [Start Event] --> [Service Task] --> [Gateway] --> [User Task] --> [End Event]
                         |
                         v
                       Job (pending) · Worker polls GET /api/v1/jobs/activate
                         v
                       Job (active) --> Worker processes · POST /api/v1/jobs/{key}/complete
                         v
                       Job (completed) --> Token advances

Process Definition

A process definition is authored as BPMN 2.0 XML. You can use the Priostack Designer or any BPMN-compatible modeler (e.g., Camunda Modeler, bpmn.io). Once deployed, each definition is assigned a unique key and version number.

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
             targetNamespace="http://priostack.com">
  <process id="order-processing" name="Order Processing" isExecutable="true">
    <startEvent id="start" />
    <serviceTask id="validate" name="Validate Order">
      <extensionElements>
        <zeebe:taskDefinition type="validate-order" />
      </extensionElements>
    </serviceTask>
    <endEvent id="end" />
    <sequenceFlow sourceRef="start" targetRef="validate" />
    <sequenceFlow sourceRef="validate" targetRef="end" />
  </process>
</definitions>

Process Instance Lifecycle

A process instance passes through these states:

State	Description
`ACTIVE`	The instance is running and tokens are advancing through the process.
`INCIDENT`	Execution is blocked due to a failed job. Requires manual intervention.
`COMPLETED`	All tokens have reached end events. The instance is finished successfully.
`TERMINATED`	The instance was manually cancelled before reaching an end event.

Variables

Variables are key-value pairs attached to a process instance. They are typed (string, number, boolean, object, array) and can be read and written at any point during execution.

Best Practice: Use structured variable names like order.id, order.amount to group related data. Avoid storing large binary payloads — store a reference (URL, ID) instead.

Variables can be set when starting an instance:

POST /api/v1/process-instances
{
  "bpmnProcessId": "order-processing",
  "variables": {
    "orderId": "ORD-2026-001",
    "amount": 149.99,
    "currency": "EUR",
    "customer": { "email": "alice@example.com", "tier": "gold" }
  }
}

Jobs and Workers

When the execution engine reaches a Service Task, it creates a Job. External workers poll the API to activate and process jobs. This decoupled architecture means your workers can be written in any language and run anywhere.

See the Workers Overview for the full polling protocol, or jump straight to the language guide: Go, Python, JavaScript.

Incidents

An incident is created when:

A job exceeds its retry count (default: 3)
A worker calls POST /api/v1/jobs/{key}/fail with retries: 0
A FEEL expression fails to evaluate
A required variable is missing

Incidents appear in the Console under the Incidents tab. You can resolve an incident by updating variables and triggering a retry.