Event Listeners

You can use notifications of user tasks to send in-app messages and emails when a task is created, assigned, completed or deleted. Use the listeners described on this page for other reactions to process events.

You can make your code react to what happens in a process in three ways:

Listeners on BPMN Elements

Execution and task listeners are part of the process definition. You set them on BPMN elements, and the engine calls them at points in the lifecycle of these elements.

Execution Listeners

You can set execution listeners on the elements that have the Execution listeners property, see the element pages in the Element Reference.

In the Modeler view, the Execution listener editor has the following fields:

  • Event: start when the process execution reaches the element, end when it leaves the element, or take when it follows a sequence flow (sequence flows only).

  • Type:

    • Java class: a class that implements org.flowable.engine.delegate.ExecutionListener or org.flowable.engine.delegate.JavaDelegate. Select it in the Class name drop-down list.

    • Expression: an expression that the engine evaluates, for example, a call of a Spring bean method.

    • Delegate expression: an expression that returns a Spring bean, such as ${myListener}. The drop-down list contains the Spring beans that implement ExecutionListener or JavaDelegate. You can also enter another expression.

  • Fields: values for the listener fields.

The Class name drop-down list contains the classes of your application and Jmix add-ons that implement ExecutionListener or JavaDelegate themselves, not through a superclass. When you select a class, or a bean in the Delegate expression field, the editor adds the class fields of the org.flowable.common.engine.api.delegate.Expression type to the Fields section, so you only enter their values. The engine injects these values into the fields when it calls the listener, see field injection.

Task Listeners

A task listener is called on user task events: create, assignment, complete and delete. Only user tasks have task listeners.

For the order of the events, the task listener editor and an XML example, see Setting Task Listeners.

Engine Events

The process engine dispatches a typed event for each of its operations, for example, PROCESS_STARTED, ACTIVITY_STARTED, TASK_ASSIGNED, TIMER_FIRED, JOB_EXECUTION_FAILURE or VARIABLE_UPDATED. Events about engine entities also have an entity type, such as task or process instance. See Event handlers in the Flowable documentation.

A listener of engine events implements org.flowable.common.engine.api.delegate.event.FlowableEventListener. Its isFailOnException() method sets what happens if the listener throws an exception: with true, the exception fails the engine operation; with false, the engine logs the exception and continues.

Engine-Wide Event Listeners

You can register a listener for the engine events of all processes in the process engine configuration, see Process Engine Configuration. For the seven events that Jmix BPM publishes as Spring events, a Spring event listener is simpler: it needs no engine configuration.

Process Event Listeners

A process can have Flowable event listeners. The engine calls them only for the events of this process definition and its process instances, such as TASK_ASSIGNED or TIMER_FIRED. See Adding listeners to process definitions in the Flowable documentation.

In the Modeler view, you add process event listeners in the Event listeners section of the process properties. The Event listener editor has the following fields:

  • Type:

    • Java class: a class that implements org.flowable.common.engine.api.delegate.event.FlowableEventListener.

    • Delegate expression: an expression that returns a Spring bean that implements FlowableEventListener.

  • Entity type: the type of the entity whose events the listener receives, such as Task or Process instance.

  • Events: the engine event types that the listener receives.

Jmix BPM Spring Events

The BPM add-on publishes seven engine events as Spring application events of the io.jmix.bpm.engine.events package. You receive them for all processes in a method of a Spring bean annotated with @EventListener, without any settings in the process.

Spring event Published when

ProcessStartedEvent

A process instance starts.

ProcessCompletedEvent

A process instance completes.

ActivityStartedEvent

The process execution reaches an activity.

ActivityCompletedEvent

An activity completes.

UserTaskCreatedEvent

A user task is created.

UserTaskAssignedEvent

The assignee of a user task changes.

UserTaskCompletedEvent

A user task is completed.

The engine publishes these events synchronously, in the thread that changes the process and before the change is finished. So a listener runs with the permissions of the user whose action changed the process, and without an authenticated user when a timer or an asynchronous job changed it. If a listener throws an exception, the engine logs a warning and the process continues, but the remaining listeners of this event aren’t called.

UserTaskAssignedEvent is also published when a task is created with an assignee and when a task is unassigned.

Logging User Task Assignments

The following listener writes a message to the log each time the assignee of a user task changes:

@Component
public class TaskAssignmentLogger {

    private static final Logger log = LoggerFactory.getLogger(TaskAssignmentLogger.class);

    @EventListener
    public void onTaskAssigned(UserTaskAssignedEvent event) {
        Task task = event.getTask(); (1)
        log.info("Task '{}' of process '{}' is assigned to {}",
                task.getName(),
                event.getProcessDefinition().getKey(), (2)
                event.getUsername()); (3)
    }
}
1 The event contains the Task object with information about the user task.
2 getProcessDefinition() returns the definition of the process that the task belongs to.
3 getUsername() returns the username of the new assignee, or null if the task is unassigned.

Reading a Process Variable in an Event Listener

To get a process variable value in the listener, pass the execution id of the task to RuntimeService:

@Autowired
private RuntimeService runtimeService;

@EventListener
public void onTaskAssigned(UserTaskAssignedEvent event) {
    Order order = (Order) runtimeService.getVariable(event.getTask().getExecutionId(), "order");
    // ...
}

Filtering Events by Process in the Listener Method

By default, a listener is called when the user task is assigned in any process. To handle the events of a specific process definition only, check the process definition key in the listener method body:

@EventListener
protected void onOrderApprovalTaskAssigned(UserTaskAssignedEvent event) {
    if ("order-approval".equals(event.getProcessDefinition().getKey())) {
        // ...
    }
}

Filtering Events by Process with a SpEL Condition

Instead of checking the process definition in the method body, you can define a SpEL (Spring Expression Language) condition in the @EventListener annotation. Spring calls the method only for the events that match the condition:

@EventListener(condition = "#event.processDefinition.key == 'order-approval'")
protected void onOrderApprovalTaskAssigned(UserTaskAssignedEvent event) {
    // ...
}