Connection Worker

The Connection Worker is the tSM integration worker for calling a configured external REST, SOAP, or TCP interface from a process. It is useful when the interface definition, request template, response mapping, and technical logging should be centrally configured and reused by multiple processes.

In the Process Designer it is available as the Connection Worker task — a Task Template applied to a BPMN Receive Task. The palette entry comes from the template (showInPalette), so it appears once the Connection Worker Task Template is present in the environment. The template dispatches the configured worker call when the task starts, while the Receive Task supplies the durable wait state for the correlated ProcessingResult. Do not model a Connection Worker call as a Service Task — a Service Task has no wait state.

When to use it

Use Connection Worker when the integration is a configured protocol call and the same endpoint or mapping may be shared by several processes. Prefer a SpEL REST or SOAP connector for a small, local, synchronous call that does not need the worker configuration. Prefer an External Task for independently deployed or long-running custom logic.

Configure the worker method

The process invokes a method by its code. Before deploying the process, configure the following items.

Configuration	Purpose
Register value Om.Methods	Defines the method under chars.method: protocol type, networkDevice, URL/path, request template, response-mapping script, and protocol-specific settings.
Register value Om.NetworkDevice	Defines the target device under chars.device, including its Kafka request topic and technical-log configuration.
Connector configuration	Supplies the endpoint, credentials, timeouts, TLS/mTLS settings, and other transport values in tsm.connector.rest, tsm.connector.soap, or tsm.connector.tcp.
DMS template (optional)	Generates the request body from the supplied input data. Without it, the worker serializes the input data as JSON.
SpEL response-mapping script	Receives request and result and must return a ProcessingResult. result contains the HTTP/TCP response status, headers, and body.

The networkDevice selects the connector configuration key: its value is lower-cased and dots are replaced with underscores. For example, Acme.Core uses tsm.connector.rest.acme_core (or the SOAP/TCP equivalent).

important

Keep passwords, client certificates, and endpoint-specific TLS settings in environment or Config Server configuration, not in the process, request template, or Om.Methods value.

Configure the Connection Worker task

1. Add a Connection Worker task in the Process Designer. It creates a Receive Task with the Connection Worker Task Template; do not replace it with a generic Service Task.
2. In the template form, select the Request script and the Response script. The Request script performs the worker call: it selects the configured worker method and builds the input data from process variables. The Response script maps the correlated result after the message arrives.
3. Select the BPMN response message in the task properties panel. A task template cannot carry the message reference (bpmn:messageRef is a diagram-level element), so the message must be selected manually on every Connection Worker task; without it the task never receives the correlated response. Define any task-specific mapping in the template form.
4. Keep asyncBefore enabled and attach an interrupting boundary timer if the business flow has a deadline.
5. After the task, use a gateway to branch on the returned ProcessingResult.

The template's start execution listener runs the selected Request script (through the script listener executor); the Request script invokes the worker, typically through #execution.connectionWorkerCall(...). The client resolves the Kafka request topic from the selected method and network device and adds the execution, process-instance, business-key, and canonical correlationId headers. The end execution listener runs the selected Response script to map the correlated result. The Receive Task persists the correlation before it waits. messageType remains a legacy alias for the BPMN message name.

The receiving process service must enable Connection Worker compatibility for the Kafka Task listener and subscribe to every actual response topic:

tsm:
  process:
    kafka-task:
      enabled: true
      connector-worker-compatibility-enabled: true
      # Add every non-default Connector Worker response topic here.
      response-topics:
        - connector-response

See Kafka Task for topic defaults, correlation, consumer groups, and response handling. The listener makes object-valued response fields available as process variables and also stores the complete response under the BPMN message name.

Reliability and error handling

The call is asynchronous from the process perspective. The Connection Worker Task Template sets camunda:asyncBefore="true" on its Receive Task (an asyncBefore attribute binding in the template), so a Kafka send failure uses the normal Camunda job retry and incident handling without leaving an ambiguous committed process state. Keep that binding in place when you customize the template.

The Connector Worker converts the technical response through the configured response-mapping script. A failed worker record is still returned as a ProcessingResult; it is not a replacement for a BPMN timeout or business recovery path. Use a gateway after the Connection Worker task to branch on the mapped result, and use a boundary timer to handle a missing or late response. Consumers must tolerate at-least-once delivery and deduplicate by the correlation identifier when they implement their own responder.

Synchronous API

Backend code can call POST /api/v2/connector-requests/call-sync (or ConnectorWorkerClient.callSync) when it must receive the mapped ProcessingResult in the same request. This is a backend integration API, not the process-modeling pattern. Processes use the Connection Worker task and its Receive Task wait state.