Workers Overview

Workers are the executors of Service Tasks in your BPMN processes. When the Priostack engine reaches a Service Task, it creates a Job. Workers poll the API to claim and process jobs, then report completion (or failure) back to the engine.

The Polling Pattern

Priostack uses an outbound job worker pattern: workers actively poll the engine for available jobs. This design means workers can run anywhere — behind firewalls, on-premise, or in any cloud — without requiring inbound connectivity to the engine.


  Worker                         Priostack Engine · POST /api/v1/jobs/activate · { "type": "payment-processor", · "maxJobsToActivate": 5, · "requestTimeout": 30000 } · ---------------------------------> · (waits up to 30s for a job) · HTTP 200 { "jobs": [...] } · <--------------------------------- · [Worker processes the job] · POST /api/v1/jobs/{key}/complete · { "variables": { "result": ... } } · ---------------------------------> · HTTP 200 · <--------------------------------- · [Token advances in process]       |

Job Activation

POST /api/v1/jobs/activate
Content-Type: application/json
X-API-Key: your_key

{
  "type": "payment-processor",
  "maxJobsToActivate": 10,
  "requestTimeout": 30000,
  "fetchVariables": ["orderId", "amount", "currency"]
}
FieldTypeDescription
typestringRequired. Matches the zeebe:taskDefinition type in the BPMN service task.
maxJobsToActivatenumberMax jobs to return in one response. Default: 1. Max: 100.
requestTimeoutnumberLong-poll timeout in milliseconds. Default: 30000. Max: 60000.
fetchVariablesstring[]Optional subset of variables to include. Omit to receive all variables.

Activation Response

{
  "jobs": [
    {
      "key": 2251799813685290,
      "type": "payment-processor",
      "processInstanceKey": 2251799813685281,
      "bpmnProcessId": "order-processing",
      "processDefinitionVersion": 1,
      "processDefinitionKey": 2251799813685249,
      "elementId": "processPayment",
      "elementInstanceKey": 2251799813685295,
      "variables": {
        "orderId": "ORD-001",
        "amount": 149.99,
        "currency": "EUR"
      },
      "retries": 3,
      "deadline": 1746456780000
    }
  ]
}

Completing a Job

POST /api/v1/jobs/{key}/complete
Content-Type: application/json
X-API-Key: your_key

{
  "variables": {
    "transactionId": "txn_abc123",
    "paymentStatus": "success"
  }
}

Failing a Job

POST /api/v1/jobs/{key}/fail
Content-Type: application/json
X-API-Key: your_key

{
  "retries": 2,
  "errorMessage": "Payment gateway returned 503",
  "retryBackoff": 5000
}

Throwing a BPMN Error

To trigger an Error Boundary Event, throw a BPMN error from your worker:

POST /api/v1/jobs/{key}/error
Content-Type: application/json
X-API-Key: your_key

{
  "errorCode": "PAYMENT_DECLINED",
  "errorMessage": "Card was declined",
  "variables": { "declineReason": "insufficient_funds" }
}

Variable Passing

  • Input: Use fetchVariables to receive only the variables your worker needs. Omit for all variables.
  • Output: Variables in the complete request are merged into the process instance. Use BPMN zeebe:ioMapping to control variable scope.

Concurrency

  • Run multiple goroutines/threads each polling independently
  • Each activation call atomically reserves jobs — no double-processing
  • Set maxJobsToActivate based on your processing capacity
  • Monitor the deadline field — if processing exceeds the deadline, the job returns to the queue
Idempotency: Design job handlers to be idempotent. If a worker crashes after completing a job but before receiving HTTP 200, it may re-activate and re-process the same job. Use the key field to deduplicate.

Language-Specific Guides