Stats
Actions
Tags
From camunda-skills
Implements Camunda 8 job workers in Java, Spring Boot, or TypeScript — handler code that activates jobs, runs business logic, and completes, fails, or throws BPMN errors.
How this skill is triggered — by the user, by Claude, or both
Slash command
/camunda-skills:camunda-job-workersThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Implement job workers for Camunda 8.8+ in Java, Camunda Spring Boot, or TypeScript. A job worker is the handler that the Zeebe engine hands an activated job to — it runs business logic, then signals success, failure, or a BPMN error back to the engine.
Implement job workers for Camunda 8.8+ in Java, Camunda Spring Boot, or TypeScript. A job worker is the handler that the Zeebe engine hands an activated job to — it runs business logic, then signals success, failure, or a BPMN error back to the engine.
<zeebe:taskDefinition type="..."/> matching the worker's job type (see camunda-bpmn)zeebe:taskDefinition, plus the boundary events that catch the worker's BPMN errorszeebe:taskHeaders and for the gateway conditions that consume the worker's output variablesWalk camunda-development first. The short version of the matrix as it applies here:
A worker's contract with the engine has four states:
type (polling) or receives them on a streamed connection. Each activation has a timeout (the lease the engine grants before it will hand the same job to another worker if the first doesn't respond) and a fetch-variables list (which process variables the engine ships with the job).job (variables, headers, retries remaining, key).complete (or returns a value with autoComplete=true). The engine merges the worker's output variables into the process scope and advances the token. Variables propagate from the job's scope up to the enclosing scopes per BPMN rules.fail explicitly with a remaining-retries count and an optional back-off, or throws. If retries reach zero, the engine raises an incident and the instance pauses until an operator resolves it (see camunda-process-mgmt).Activation timeout vs. retries are independent. A timeout means the engine reassigns the job without decrementing retries; a fail with retries left means the same job will be redelivered after the back-off. Long-running handlers should extend the timeout via UpdateJobTimeout rather than racing the lease.
The engine's at-least-once delivery guarantees that a handler may run more than once for the same job.key. Activation timeouts, network blips, and retries after a failed complete call all cause redelivery. Handlers must be idempotent.
Two patterns work well:
job.key (or a deterministic value derived from process variables) as a request id / Idempotency-Key header / database unique constraint. A retry of the same job hits the same key and is suppressed.Storing local "has this job ran?" state in the worker process is not idempotency — the process can crash, scale out, or be replaced.
The choice depends on whether the failure is a transient infrastructure problem, a modelled business outcome, or an unexpected programming error:
Transient failure → fail with retries and back-off. Network timeout, downstream 5xx, broker unreachable. The handler decrements retries and asks the engine to redeliver after a back-off. Reaching zero retries raises an incident.
Business outcome → BPMN error. The handler succeeded in identifying a failure modelled in the BPMN — payment declined, inventory empty, license rejected. Throw a BPMN error with a code that an error boundary event (or error end event in a subprocess) catches. The job is not retried — the engine takes the error path.
Programming error → unhandled exception. A NullPointerException, an unhandled promise rejection, a type error. SDKs fall back to fail-with-zero-back-off — the engine redelivers immediately, burns retries, and raises an incident. Never use unhandled exceptions as a control-flow signal: the zero back-off thrashes the cluster, and a future SDK change could redefine the default.
The SDK-specific call signatures (CamundaError.jobError / CamundaError.bpmnError for Spring, newFailCommand / newThrowErrorCommand for the Java client, job.fail / job.error for TypeScript) are in the per-SDK references.
The Camunda Spring Boot Starter's @JobWorker auto-completes by default: the handler's return value is serialised as the job's output variables. Set autoComplete = false when the handler needs to call complete itself (conditional variables, asynchronous response, ownership transfer).
The Java client and TypeScript SDK do not auto-complete — the handler must call complete, fail, or error on every code path. Missing a terminal call leaks the job's lease until activation timeout.
| SDK | When to pick |
|---|---|
Camunda Spring Boot Starter — camunda-spring-boot-starter (ref) | New Java applications. Annotation-driven (@JobWorker), auto-complete, config via application.yaml. The default Java path. |
Java client — camunda-client-java (ref) | Standalone JVM applications, non-Spring frameworks, libraries embedding Zeebe access. Lower-level builder API. Replaces the deprecated Zeebe Java Client (removed in 8.10). |
TypeScript — @camunda8/orchestration-cluster-api (ref) | Node.js workers, browser-hosted clients, 8.9+ projects. Fall back to @camunda8/sdk (Node-only) only when gRPC streaming, sub-8.8 targets, or migration friction explicitly require it. |
The default Camunda Spring Boot Starter (
camunda-spring-boot-starter) is bundled with and requires Spring Boot 4.0.x.
Applications still on Spring Boot 3.5.x use camunda-spring-boot-3-starter as a migration bridge — Spring's OSS support for the 3.5.x line ends June 2026. Don't mix the two starters on one classpath: the SB4 starter won't start on a Spring Boot 3 app, and the SB3 starter pulls conflicting transitive deps into a Spring Boot 4 app.
All starter modules require OpenJDK 17+.
autoComplete = true covers happy-path returns; failure paths still need an explicit signal.retries - 1 and retryBackoff = 0 — the engine redelivers immediately, burns retries, and raises an incident.For SDK-specific detail, read from references/:
camunda-client-java: client bootstrap, JobWorkerBuilder, command builders, streaming, multi-tenancy, OAuth config@JobWorker parameter reference, @Variable / @VariablesAsType, CamundaError, configuration property tree, Spring Boot 4 vs 3 starter selection@camunda8/orchestration-cluster-api: createJobWorker / createThreadedJobWorker, job-handler return shapes, when to fall back to @camunda8/sdknpx claudepluginhub camunda/skills --plugin camunda-skillsGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.