Service task

A Service Task represents work performed automatically by a system, without human involvement. In ZenBPM a Service Task does not call the external system itself — when a token reaches the task, the engine creates a job and waits. A job worker (your application) picks the job up, executes the business logic, and completes it, after which the token continues along the outgoing sequence flow.

Rendered as a rounded rectangle with a gear icon in the top-left corner.

Use cases

• Call an external system — charge a credit card through a payment gateway, send a request to a shipping provider, or query a customer record from a CRM.
• Run background processing — generate a PDF invoice, resize an image, or transform a dataset as part of the process.
• Update another system of record — write the process result to an ERP, a database, or a legacy application so downstream systems stay in sync.

Usage in BPMN

To make a Service Task executable, define the job type in a zenbpm:taskDefinition extension element. Optionally, control the data that flows into and out of the task with a zenbpm:ioMapping.

Extension element	Attribute	Required	Description
zenbpm:taskDefinition	type	yes	The job type. The engine creates a job of this type when the task is activated; workers subscribe to this type to receive the job.
zenbpm:taskDefinition	retries	no	How many attempts the job gets; the failure without an error code which uses the last one creates an incident: a non-negative integer, or a FEEL expression starting with = evaluated when the job is created. Default jobs.defaultRetries (1). See Failures and retries.
zenbpm:taskDefinition	retryBackoff	no	How long the job waits after such a failure before it is handed out again: an ISO-8601 duration (PT10S), a comma-separated list with one entry per failure, the last repeating (PT10S,PT1M,PT10M), or a FEEL expression starting with =. Default jobs.defaultRetryBackoff (PT0S).
zenbpm:ioMapping → zenbpm:input	source, target	no	Maps process variables into the task's local scope, visible to the job worker. See Variables.
zenbpm:ioMapping → zenbpm:output	source, target	no	Maps the job's result variables back to the process scope. See Variables.

Execution flow:

1. A token arrives at the Service Task and the engine creates a job with the configured type, carrying the task's variables.
2. A worker activates the job via the REST or gRPC API (or an internal task handler registered on the engine), performs the work, and completes or fails it.
3. On completion, output mappings are applied and the token moves on. Without output mappings, no variables returned by the worker are propagated to the process scope — define an output mapping for every value you want to keep.
4. On failure with an error code, the error is routed to a matching error boundary event or error event sub-process, or creates an incident. On failure without one, the job spends a retry and is handed out again after its backoff; the failure which leaves no retries creates an incident. See Failures and retries.

Related documentation

• Jobs — how jobs are created, distributed, and completed over the REST and gRPC APIs.
• Variables — variable scoping and output mapping propagation rules for activities.

XML example

A Service Task that creates a job of type charge-card with three attempts, waiting ten seconds after the first failure and a minute after the second. The input mapping passes the order total to the worker as amount; the output mapping stores the worker's transactionId result in the process variable paymentTransactionId.

<bpmn:serviceTask id="Activity_ChargeCard" name="Charge credit card">
  <bpmn:extensionElements>
    <zenbpm:taskDefinition type="charge-card" retries="3" retryBackoff="PT10S,PT1M" />
    <zenbpm:ioMapping>
      <zenbpm:input source="=order.totalAmount" target="amount" />
      <zenbpm:output source="=transactionId" target="paymentTransactionId" />
    </zenbpm:ioMapping>
  </bpmn:extensionElements>
  <bpmn:incoming>Flow_In</bpmn:incoming>
  <bpmn:outgoing>Flow_Out</bpmn:outgoing>
</bpmn:serviceTask>