Version: 2.4

External Task

External Tasks in tSM delegate execution to an external worker instead of running logic inside the process engine. This enables clean separation of responsibility, independent scaling, and integration with systems outside tSM.

When to Use an External Task

Use an External Task when:

the action should not run inside the process engine
you want clear separation of responsibility
the logic is implemented in a separate service (e.g. an AI agent, integration connector, or third-party system)
retries, failures, and scaling should be handled outside the engine

Do not use External Tasks for:

BPMN listeners (they are lifecycle hooks, not jobs)
simple in-process logic (use Service Tasks with scripts or delegates instead)

How It Works

An External Task is a standard Service Task configured with the type External. Instead of running logic directly:

The tSM Process Engine creates an external task instance with a specific topic
An external worker subscribes to that topic and fetches the task via REST (fetchAndLock)
The worker performs the work
The worker completes (or fails) the task, optionally returning output variables

The external worker is a separately implemented service — it defines a strict contract: which topic it listens to, what input variables it expects, and what output it produces.

Task Templates and External Tasks

Because external workers expect a specific contract (topic, input variables, structure), you cannot set arbitrary properties — the configuration in the BPMN model must match exactly what the worker understands.

For this reason, external task workers are typically delivered together with a Task Template. In most cases, you do not need to configure external tasks manually. Instead, you:

Select a Task Template from the palette in the tSM Designer (e.g. "AI Agent Call")
Fill in the template form — the template guides you through the required parameters
The template generates the correct BPMN configuration automatically (topic, input mapping, defaults)

This approach:

prevents misconfiguration that would cause the worker to fail
provides a guided UI so you don't need to know the worker's internal contract
applies consistent defaults and validates inputs
makes external tasks accessible to process designers without deep technical knowledge

tip

If a Task Template is available for the external worker you want to use, always prefer the template over manual configuration. Manual setup is described below for reference and for cases where no template exists.

Manual Configuration

The rest of this page describes how to configure an External Task manually in the tSM Designer. This is the baseline — everything here also applies when a Task Template generates the configuration for you.

Step 1: Add a Service Task

Drag a Service Task into the process and give it a meaningful name (e.g. AI Agent Call).

An External Task uses the standard Service Task BPMN element — no custom elements are needed.

Step 2: Set execution type to External

In the Service Task properties:

Set Implementation / Type to External Task
Set Topic to a string identifying the operation

Example:

Topic: ai.agent.call

This topic is what the external worker will subscribe to.

Passing Input Data

External workers read process variables. All input for the external task must be provided as process variables.

Input Mapping

Use Input Mapping on the Service Task to:

define variables explicitly
compute values using expressions
keep the process readable

Example

In the Service Task → Input/Output section:

<camunda:inputOutput>
  <camunda:inputParameter name="aiAgentId">support-triage</camunda:inputParameter>

  <camunda:inputParameter name="aiInput">
    <camunda:map>
      <camunda:entry key="prompt">
        Summarize the ticket and propose next actions
      </camunda:entry>
      <camunda:entry key="context">
        #{ { ticketId: execution.processBusinessKey, text: ticketText } }
      </camunda:entry>
    </camunda:map>
  </camunda:inputParameter>

  <camunda:inputParameter name="aiOptions">
    <camunda:map>
      <camunda:entry key="temperature">#{0.2}</camunda:entry>
      <camunda:entry key="maxTokens">800</camunda:entry>
    </camunda:map>
  </camunda:inputParameter>

  <camunda:inputParameter name="aiResultVar">aiResponse</camunda:inputParameter>
</camunda:inputOutput>

Notes:

Expressions use SpEL syntax #{...}
Maps and lists are allowed
Values are evaluated when the task is reached
Variables are available to the external worker

What the External Worker Receives

When the worker fetches the task, it receives:

the topic
the process instance context
all mapped input variables

Example variables payload:

{
  "aiAgentId": "support-triage",
  "aiInput": {
    "prompt": "Summarize the ticket and propose next actions",
    "context": {
      "ticketId": "INC-123",
      "text": "Customer cannot log in"
    }
  },
  "aiOptions": {
    "temperature": 0.2,
    "maxTokens": 800
  },
  "aiResultVar": "aiResponse"
}

Completing the External Task

After performing the work, the worker must:

complete the task
optionally set output variables

Example completion payload:

{
  "aiResponse": {
    "summary": "...",
    "recommendations": ["..."]
  }
}

These variables become available to the rest of the process.

Error Handling and Retries

Recoverable errors

If the worker encounters a recoverable error:

report failure
let the process engine retry according to the retry policy

Non-recoverable errors

set retries to 0
optionally set error details

The process engine stops retrying and creates an incident.

Best Practices

Use Task Templates whenever available — they ensure correct configuration
Use clear, stable topic names
Keep input payloads reasonably small
Prefer structured objects over large strings
Treat External Tasks as integration boundaries

Summary

To use an External Task in tSM:

Preferred: Select a Task Template for the external worker from the palette and fill in the form
Manual: Create a Service Task, set it to External Task, define a topic, and configure input mapping
An external worker fetches the task, performs the work, and completes it

When to Use an External Task​

How It Works​

Task Templates and External Tasks​

Manual Configuration​

Step 1: Add a Service Task​

Step 2: Set execution type to External​

Passing Input Data​

Input Mapping​

Example​

What the External Worker Receives​

Completing the External Task​

Error Handling and Retries​

Recoverable errors​

Non-recoverable errors​

Best Practices​

Summary​