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 (or another step that needs an outside party, such as a Script, Send, User or Receive 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	`INCIDENT` is a process instance state: the run failed and cannot move (a job failed with no retries left, or a condition or decision could not be evaluated). A job failure also creates an incident record, listed by `GET /api/v1/incidents`. There is currently no REST call that retries or resumes an instance in `INCIDENT`.
Deployment	The act of uploading a process definition to Priostack so it can be instantiated. Redeploying changed XML under the same process id creates version n+1; deploying byte-identical XML returns the existing version.
Correlation Key	A unique identifier used to route incoming messages to the correct process instance. Used with Message Catch Events and Receive Tasks. The engine supports it, but the hosted API has no route to publish or correlate a message yet: message waits are handed to workers as ordinary jobs.
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	A set of EIP (Enterprise Integration Patterns) models, such as message channels, routers, filters, aggregators and pipelines, in the qubit-core library. It is usable embedded in Go through the SDK camel runtime; it is not a hosted Priostack feature.

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 POST /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"
             xmlns:zeebe="http://camunda.org/schema/zeebe/1.0"
             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 id="flow_start_validate" sourceRef="start" targetRef="validate" />
    <sequenceFlow id="flow_validate_end" 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`	The run failed and cannot move: a job failed with no retries left, a condition or decision could not be evaluated, or a step could not be charged. There is currently no REST call to resume it, so it stays `INCIDENT`.
`COMPLETED`	All tokens have reached end events. The instance is finished successfully.
`TERMINATED`	The instance was cancelled with `DELETE /api/v1/process-instances/{key}` while `ACTIVE` (an `INCIDENT` instance cannot be cancelled).

The state field of an instance record takes exactly these four values. List the instances in one state with GET /api/v1/process-instances?filter.state=INCIDENT.

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 instance goes to the INCIDENT state when:

A worker calls POST /api/v1/jobs/{key}/fail with retries at 0 or below (a job's retries start at 3 unless the task sets another value)
A gateway condition fails to evaluate, for example because it reads a variable that was never set
A business rule task's decision cannot be evaluated, for example because the DMN was never deployed

Only job failures also create an incident record, listed by GET /api/v1/incidents; find every stuck instance with GET /api/v1/process-instances?filter.state=INCIDENT. There is currently no REST call that retries or resumes an INCIDENT instance: PATCH /api/v1/incidents/{id} marks the record resolved and leaves the instance where it is. See Incidents.