Skip to main content

External Worker Task

Introduction​

The external worker is an alternative when it's not possible to integrate via events. In this case, Flowable provides REST endpoints for external services. The external service can poll for tasks and notify Flowable once the tasks are completed.

Properties​

General​

AttributeTypeDescriptionCategory
Model Id Text

Model Id identifies the element within the process model.

The model id, name and documentation properties can be found on any element. They are used respectively to uniquely identify the external worker task, to give it a user-friendly name and to add a free-form description.

Name Expression usage possibleText

The name of the element. This is the name displayed in the diagram.

Documentation Multiline Text

A free-form text that can be used to explain details about the particular element.

Job topic RequiredExpression usage possibleText

The job topic that the external worker will query jobs on

When reaching this task an external job will be created, which is supposed to be executed by another (external) system. These systems can poll, query and acquire new external worker jobs on a certain Job topic, that effectively categorizes the type of external work needed. The external system is responsible for completing the external job, and can hold a lock on a job while it's executing. All of the above is done either through the Flowable Java or REST API.

An external job can also be made exclusive, which means that no other external worker jobs can be acquired and locked in the same process instance.

Exclusive Boolean

Determines whether the activity or process is run as an exclusive job. An exclusive job makes sure that no other asynchronous exclusive activities within the same process are performed at the same time. This helps to prevent failing jobs in concurrent scenarios.

Candidate users Expression usage possibleUser Selection

By selecting one or more candidate users, the task might be taken by one of those external worker users.

Besides the job topic, an external worker job can also be available for certain candidate users or candidate groups. The external system will need to pass the user of group information when using the Flowable API when querying and acquiring the external worker job(s).

Candidate groups Expression usage possibleGroup Selection

By selecting one or more groups as the candidate groups, shares the task with all external worker users belonging to at least one of the groups.

Variable Mapping​

AttributeTypeDescriptionCategory
In Parameter List

To restrict the variables to a specific set for the worker, specify them as in parameters.

By default the external worker tasks transmits all variables to the consumer of the job.

This dialog allows to overwrite the variable mapping and provide only the specific variables. In case no variables are required, simply check the 'Do not include variables'.

The source field takes a variable name while the source expression allows to evaluate an expression using any variables of the current scope. The target is the name of the variable as the external worker consumer will see it.

Do not include variables Boolean

By default, if no input mapping is provided it will send the entire scope of the activity. When this is checked and no variable is provided, no data will be sent to the consumer acquiring the job.

Out Parameter List

Allows a mapping of the variables provided by the external job worker to new process variables.

By default the external worker tasks will save all variables specified by the consumer to the current scope. With this mapping the list of variables can be filtered to the required variables.

Source is the variable as it is transmitted from the external worker client, while source expression allows to compute an expression based on the data from the external worker. Target is the name of the variable as it should be created on the current scope.

Multi Instance​

Multi instance​

AttributeTypeDescriptionCategory
Multi instance type RequiredSelection:
  • None
  • Parallel
  • Sequential

The type of multi-instance: default is 'None' meaning a single instance is created at runtime. Select either 'Parallel' or 'Sequential' if you want multiple instances to be created.

Multi-instance is used to define the repetition of this external worker task at runtime.

With multi-instance it is possible to have multiple external jobs available, either sequentially after each other or in parallel.

For example, when referencing a collection one external job is created for each element of that collection.

Collection Text

References a collection variable (for example a JSON array variable) by its name or using an expression that resolves to a collection.

Element variable Text

The name of the variable where the currently processed element from the multi-instance collection configured above will be stored (for example, 'invoicePosition').

The element can then be accessed through an expression, e.g., ${invoicePosition}.

Element index variable Text

The name of the variable where the index of the currently processed item from the multi-instance collection will be stored, for example, 'itemIndex'. The index is a number starting with 0 which is increased with every element that is being created. The index can then be accessed through an expression, e.g., ${itemIndex} further on in the process.

Cardinality Text

A fixed number or an expression that resolved to an integer that controls the number of instances that will be created.

This is typically used when there is no collection available or needed.

Completion condition Text

An expression that should resolve to a boolean value. When evaluating to true, the remaining activity instances will be removed and the process instance will continue.

Variable aggregation​

AttributeTypeDescriptionCategory
Variable Aggregations List

Define an aggregation. Each element in this list will result in one aggregation variable.

When using repetition, there is often a need to create an aggregation of the variables created and/or updated in each instance.

With variable aggregation, a JSON variable can be created that after all instances have been completed contains the summary of all the used variables. This is needed because for repetition, variables are persisted locally, to avoid clashes on the case instance level.

Alternatively, an 'overview' variable can be created while the instances are still unfinished.

Each aggregation consists of one or multiple definitions that map instance variables of one instance of the repetition to the aggregation variable.

Advanced​

AttributeTypeDescriptionCategory
Optimize for only automatic steps Boolean

(Advanced setting, only check it if you understand the implications) If checked, this instructs the Flowable engine that the multi-instance only contains automatic tasks and no wait states. In this situation, an asynchronous job is created when the multi-instance activity is entered that keeps checking if all instances are completed and completes the multi-instance. The benefit of this approach is that it is light on resources versus alternatives and doesn't lead to optimistic locking exceptions.

Advanced​

Execution​

AttributeTypeDescriptionCategory
Skip expression Expression usage possibleText

If the Skip expression evaluates to true, the flow is taken regardless of any condition.

It is required to opt-in to this feature by setting a variable _FLOWABLE_SKIP_EXPRESSION_ENABLED with the Boolean value true on the process instance.

When the Skip expression resolves to true, this external worker task will not be executed at runtime.

The Include in history flag can be used to store the historical entry of this external worker task when running with a history level that normally would not store the execution of the service task.

Note that this flag has no effect when running with history level 'none'.

Include in history Boolean

When the history level is set to "instance" or "task" level with this property it can be configured if this activity instance should be included in the historic activity data.

Is for compensation Boolean

Determines whether the activity can serve as a compensation for another activity.

A BPMN transaction is a set of activities that logically belongs together. Transactions can be cancelled through the Cancel End Event and handled through the Cancel Intermediate Boundary Event.

The Is for compensation field can be used to indicate that the external worker task is meant as compensation steps for another activity.

Listeners​

AttributeTypeDescriptionCategory
Execution listeners List

Allows invoking custom after certain lifecycle events.

Start: Executes after the activity has been started.

End: Executes after the activity was completed.

Transition: When defined on a sequence flow, executes once the flow is transition is taken.

Execution listeners are used to add logic on certain lifecycle events.

Typically it is used to add extra technical logic which shouldn't be visible in the BPMN process model.

Visual​

AttributeTypeDescriptionCategory
Background color RequiredColor

The background color of the element in the diagram.

Visual properties that determine how the external worker task is shown in the diagram.

This has no impact on the runtime execution.

Font size Selection:
  • 8
  • 9
  • 10
  • 11
  • 12
  • 14
  • 18
  • 20
  • 24
  • 36
  • 48
  • 72

Font size.

Font weight Selection:
  • Normal
  • Bold

Select the style between bold and normal.

Font style Selection:
  • Normal
  • Italic

Select the style between italic and normal.

Font color Color

Select a font color.

Border color RequiredColor

The border color of the element in the diagram.

List Attribute Details​

In Parameter​

AttributeTypeDescription
Source variable Expression usage possibleText

The name of the variable that should be mapped to the target variable

Source Expression Expression usage possibleText

Instead of a variable, an expression can be used to resolve to a value, which is used to map into the target variable.

Target variable RequiredExpression usage possibleText

The name of the variable into which the source variable or expression is mapped.

Out Parameter​

AttributeTypeDescription
Source variable Expression usage possibleText

The name of the variable that should be mapped to the target variable

Source Expression Expression usage possibleText

Instead of a variable, an expression can be used to resolve to a value, which is used to map into the target variable.

Target variable RequiredText

The name of the variable into which the source variable or expression is mapped.

Variable Aggregations​

AttributeTypeDescription
Target (Variable / Expression) RequiredExpression usage possibleText

The name of the target variable or an expression that gives the variable name

Type RequiredSelection:
  • Default
  • Custom

The type of aggregation. Use 'default' to use the standard behavior of creating an aggregation JSON variable. Use 'custom' to define a delegate expression that will handle the aggregation. Please see the documentation for more information.

Delegate Expression Expression usage possibleText

Define a delegateExpression that will resolve to an instance of VariableAggregator (for BPMN) or PlanItemVariableAggregator (for CMMN). This instance will then be responsible for aggregating the variables.

Class String

A class that implements VariableAggregator (for BPMN) or PlanItemVariableAggregator (for CMMN). This instance will then be responsible for aggregating the variables.

Target variable creation RequiredSelection:
  • Default
  • Create overview variable
  • Store as transient variable

Configures the way the aggregation variable is created. The 'Default' option creates the aggregation variable when all instances of the multi-instance have been completed. Use 'Create overview variable' to create a variable at the start of the multi-instance and keep it up to date during multi-instance exeution. Once all the instances are completed it will create a JSON variable in the same way as for Default target variable creation. Use the 'Store as transient variable' option to have the default behavior, but store the resulting aggregation variable transiently.

Variable Definitions BasicFormList

property.loopVariableAggregation.definitions.description

Variable Definitions​

AttributeTypeDescription
Source (Variable / Expression) RequiredExpression usage possibleText

The name of the source variable or an expression that provides the value

Target (Variable / Expression) Expression usage possibleText

The name of the aggregation variable or an expression that resolves to a variable name.

Execution listeners​

AttributeTypeDescription
Event RequiredSelection:
  • Start
  • End
  • Take

The lifecycle event. The 'Take' event is only available for sequence flow.

Class Text

Fully qualified classname of a class to be invoked when executing the task. The class must implement either JavaDelegate or ActivityBehavior.

Expression Text

JUEL Expression to be executed when the task is started. Expressions allow you to interact with the backend by calling services, making calculations etc. You can find more information about expressions in the documentation.

Delegate expression Text

Delegate Expression to be executed when the task is started. A delegate expression must resolve to a Java object, for instance a Spring bean. The object's class must implement either JavaDelegate or ActivityBehavior.

Fields List

Fields​

AttributeTypeDescription
Name Text

The name of the element. This is the name displayed in the diagram.

String value Text
Expression Text

JUEL Expression to be executed when the task is started. Expressions allow you to interact with the backend by calling services, making calculations etc. You can find more information about expressions in the documentation.

String Text