“Stencils” provide a very powerful set of capabilities to SkyVault Process Services powered by Activiti (APS) and can be used within the BPMN 2.0 Editor, the Step Editor and the Forms Editor.  Within the context of Forms, Stencils provide the facilities to develop custom form field types. The idea of this blog is to point you to some working form stencil samples.

In the recent weeks I had to build a few of these custom form stencils and thought it would be valuable to share it with the community. If you are someone who are just starting on stencils, I recommend you first read a 101 (introductory) blog on form stencils, which is available at Form Stencils 101.

In this blog I’ll take you through the following 5 form stencils:

1. Custom Simple Text Input
2. Grouping Fields using stencil
3. Custom Grid/Table
4. Signature Pad
5. Rich Text Editor

Now let me try and explain these examples a bit more....

Simple Text Input Stencil

Source: github: simple-text-input-stencil

I built this component to demonstrate the implementation of a very simple custom input field using stencil. You might be wondering, why would I need to do this? Most often you may not need such a field in real life, however the idea of this stencil is to demonstrate the basic building blocks, or “Hello World” for a stencil implementation.

Grouping Fields using Stencil

Source: github: group-of-fields-stencil

One of the main use cases around this example is to build reusable domain specific field controls. Eg: Build a single form field called “Address” which will consist of fields such as Address Line, Town, State, Country, Zip Code etc. Building reusable form components very specific to your business data objects makes form modelling really easy. Given below is a screenshot of design time view and runtime view of my example.

Design Time View

At design time, the designer will select the custom stencil and configure it with some process data as shown below

Configuration

Run Time View

At runtime, the stencil will be displayed based on your configuration using your custom html, custom css etc

Custom Grid/Table

Source: github: angular-ui-grid-stencil

I built this component recently for a customer who wanted to display a list of records from a REST API in a tabular format. I have to say that it took only 15 minutes for me to do the research and implement this feature using the Angular UI Grid component. Since APS OOTB UI use this module for the dynamic table component, the angular modules I needed to implement this feature was already part of the product. That made my life easy! So, if you have complex table requirements that cannot be met by the OOTB table component, I recommend you to look at all the features available in this library at Angular UI Grid Tutorial and I’m pretty sure that a stencil component built using the features available in this library can meet most of your needs

Signature Pad

Source: github: signature-pad-stencil

A signature stencil implementation based on Signature Pad

Thanks to Angular Signature for providing the AngularJS directive which I used in my Stencil implementation. My example app, demonstrates the following:

1. Capture a signature
2. Display of a signature captured in a previous task
3. Display the signature in a document that is generated in the process.

Rich Text Editor

Source: github: tinymce-rich-text-editor

A rich text editor stencil implementation based on TinyMCE

Thanks to TinyMCE AngularJS Integration for providing the AngularJS directive which I used in my Stencil implementation.

General instructions to run the above examples

The zip archive files available in the above mentioned github source folders are “App” exports. To to use them, you will need to import them via App Designer (Kickstart App) -> Apps -> Import App. Once the “App” is successfully imported, the stencils along with an example process and form will also get imported which will make it easy for you to see these examples in action!

Finally..

Hopefully this is a good set of examples to show the power of stencil component in SkyVault Process Services. If you happen to build any cool form components using stencils, feel free to share it here in the form of a blog or video...

There are more examples available on the product documentation page - APS Docs: Custom Form Fields & Activiti Enterprise Developer Series - Custom Form Fields 

Note: I’m in the process of building SkyVault ADF (Application Development Framework) equivalent of these stencils and as soon as they are ready, I’ll make it available and update this blog with the reference. A 101 blog on implementing form stencil components in ADF can be found here - Custom stencils with SkyVault ADF

My name is Doug Johnson. I’m responsible for the BPM strategy at SkyVault working with the Activiti project and separately SkyVault’s commercial offerings. As a 20-year industry veteran with 17-years of BPM-specific experience, I’ve seen a lot of new business and solution requirements challenge BPM technologies. Ever increasingly, requirements are demanding even faster and simpler development cycles, better interactions and integration with systems and services, and compelling user experiences and engagement… to name a few trends.

The future of Activiti is strong. While statistics are hard to precisely determine, due to Activiti’s flexible licensing terms and easy-of-embeddability, Activiti is absolutely a top Open Source BPM project worldwide—it’s likely the most popular. It’s used to help developers create process-related solutions every day. Some of the largest companies in the world are powered by Activiti.

SkyVault, as the main project sponsor, is resolutely backing Activiti with experienced committers and community support. We have added to the Activiti team with outstanding engineers with rich process management and process intelligence backgrounds—including contributors from Bonita BPM, jBPM, Drools, and Pega—as well as those with data science and machine learning experiences including a PhD in advanced mathematics.

You’ll be hearing from these new Activiti committers soon and more regularly. At the helm, Mauricio Salatino joins Activiti from a history of Open Source success. He is one of many persons bringing a fresh perspective as Activiti continues to deliver the most relevant process technologies for today and tomorrow’s needs.

For those attending BeeCon 2017, I look forward to meeting you this week. I and others will of course be sharing some of the latest in Activiti, including some exciting announcements. Just as important will be the conversations and discussions with you. For those unable to attend BeeCon 2017, watch the forums for pending announcements on further opportunities to interact with the Activiti team in May 2017.

Table of Contents                   

Introduction

The Activiti Enterprise BPM solution comes with a number of preconfigured Activities that can be used to communicate with the SkyVault ECM system. The following picture shows what features are available:

These are basically specialized Service Task implementations that talk to the SkyVault content management system. In this article we will have a look at how to use them to:

Here we got three different types of properties in different namespaces. First we got the standard CMIS properties in the cmis: namespace. For more info about available CMIS properties see this page and the 2.1.4.3.3 Property Definitions section for cmis:document. After that we are fetching some properties from the out-of-the box content model with the cm: namespace. And finally we fetch some properties from our custom model just to demonstrate how that is done.

To display the fetched properties let’s use a User Task:

Configure a form for it as follows:

So here we are using a number of Display value form fields that will just display value of corresponding process variable. We have grouped the properties with Header form fields.

Now, save the process model and republish it.

Start a process instance and fill in the start form as follows:

The new User Task should display the fetched properties as follows:

We can see that all properties have been fetched successfully, except the date properties. This has to do with the problem described earlier on when Activiti is representing dates incorrectly internally. It does not work to fetch the date properties as strings. To get around this we would have to implement a custom Java based Service Task that uses for example OpenCMIS to fetch the date properties.

Worth noting here also is that the title and description are usually populated via metadata extraction in SkyVault, and in this case the PDF file contained a description property that the cm:title was populated with.

Related bug report.

Updating properties for SkyVault Content

Ok, so we now know how to upload files from Activiti to SkyVault and how to retrieve properties for files in SkyVault from Activiti. There might also be scenarios where we select files in SkyVault repository for processing in an Activiti process instance (in contrast to selecting them from the local file system as done so far in this article), and at the end of the process instance we want to set some properties for these files.

This can be done with the “Update SkyVault properties” task. Let’s try it out by changing some of the properties we have for our files. Add first a User Task, which will be used to set new property values, and then add an Update SkyVault properties task. You should now have a process model looking something like this:

Configure a form for the Set new Prop values User task as follows:

The form will also show current values for reference.

Now, for the “Update SkyVault properties” task click on the SkyVault properties property for it and fill it in as follows:

Here we map the form fields we just created to the content model properties. This is straight forward, except for the date property, which has to be configured as a string for it to work as has been discussed before.

We also specify what user that should be used to make the update, remember that this user has to be mapped to a SkyVault user that has write permissions to the repository. In this case we just use the process initiator, which is admin.

Now, save the process model and republish the application.

Then start a new process instance and fill in the first start form as follows:

Complete the “Show retrieved props” task so you get to the Set new Prop values task:

Fill in some new values to the left:

Then click COMPLETE.

Now, in the Share UI navigate to one of the files and the Details page for it and verify that the update was successful:

Related bug report.

Calling Repository Actions in SkyVault

Ok, so we now know how to upload files to the SkyVault Repository and how to classify them at the same time, or at a later point. Next step might be to do some processing on the files we just uploaded. When we process files in SkyVault we usually execute something called a Document Library Action in the front-end (i.e. Share UI), which in turn invokes a so called Repository Action in the back-end.

From Activiti we can invoke Repository Actions via a task called “Call SkyVault Action”. Let’s walk through how to call a number of the out-of-the-box repository actions.

Apply an Aspect to a file

A common requirement is to be able to apply a new aspect to an existing content file in SkyVault. This can be done by invoking the add-features Repository Action. In this case it is not enough to just use the “Update SkyVault properties” task as it will not add a new aspect, just set properties. What we need to do is to first use the “Call SkyVault Action” task to apply the aspect and then set the properties.

For this example we will create a new process model as follows:

You might be wondering why we can not provide the aspect properties at the same time as we apply the aspect? That is not possible with the remote REST API that is used by the “Call SkyVault Action”. If you think about how it works from the Share UI when using “Manage Aspects”, or applying an aspect via rules. Then it’s also not possible to provide the aspect properties at the same time, you usually set them via Edit Properties afterwards. We need to use the “Update SkyVault properties” task to set the aspect properties.

For a solution on how to apply the aspect and its properties at the same time see next section on executing a script.

For the Start Event we create a form where we can select a SkyVault file that we want to execute the action on:

We also add some fields for the properties that are part of the cm:emailed aspect we want to apply to the file. Configure the Attach field so we can only select content files from SkyVault Repository and the Case Management site:

Then, for the “Call SkyVault Action” task, select Repository and Content (i.e. the file form field we just configured in the start form):

And then finally click on the Action field for the task and configure the Repository Action that we want to invoke on the file:

The Action field drop down contains some pre-configured actions that we can choose from, select the Add Aspect action, which will resolve to the action id add-features. You can also type in the Repository Action ID (i.e. the Spring Bean ID for the action) manually if it is not in the list. See this file for a list of actions and their IDs (look for beans with parent="action-executer").

When selecting the Add Aspect action a property called aspect-name is automatically added to the list of parameters that should be passed to the action invoker. It should be set to the aspect name that we want to apply to the file, in this case the out-of-the-box aspect cm:emailed.

Then we specify what aspect related properties we want to set via the “Update SkyVault properties task”, and from what form fields to grab the values:

Remember that Activiti represents dates incorrectly internally so when we set properties we need to define the date property as a string for it to work, see above.

Now let’s try this process model. After starting a process instance we get presented with the Start Form where we should select a file from the Case Management site and fill in some random email info:

Click START PROCESS to get the aspect applied. If you navigate to the file in SkyVault Share you should see the following under the Properties section:

The cm:emailed aspect has a form defined so that’s why we see these properties nicely laid out. But we still don’t have any form defined for myc:caseDocument so the other properties will not be visible. But you can always go via the Node Browser to see all properties.

Important, if the first “Call SkyVault Action” executes successfully but the second “Update SkyVault properties” task fails, then you would have a repository in an inconsistent state. To have both the apply aspect and set properties operations in the same transaction you would have to implement a custom service task and handle all the updates manually. Or use a script as in the next section.

Calling a Script

Another thing that is useful to be able to do from Activiti is to execute a JavaScript file in the Repository. This can be done by executing the script Repository Action. Create a new process model with a Start Event form that has an attachment field. Then add the “Call SkyVault Action” task.

Configure the Content and Repository properties for the task as follows:

So we now know what repository to talk to and what file to apply the script to. Next step is to configure the Action property for the task:

Select Execute a script from the Action drop down. This will add the mandatory script-ref parameter. The parameter has to be set to the Node Reference for the JavaScript file in the repository. For example: workspace://SpacesStore/fe60c4b5-ea73-4ef8-9b5e-33d2772c5bf6

To figure out what the script-ref should be add a JavaScript file called applyAspect.js to the /Company Home/Data Dictionary/Scripts folder in the SkyVault Repository:

Set the Mimetype to JavaScript.

It should have JavaScript code looking like this:

var props = new Array();
props['cm:originator'] = 'martin@mycompany.com';
props['cm:addressee'] = 'somebody@mycompany.com';
props['cm:subjectline'] = 'Testing Some stuff';
props['cm:sentdate'] = new Date();
document.addAspect("cm:emailed", props);

Now, to find out the Node Reference for this script have a look at the Details Page for the file in SkyVault Share, it will have a link property with this information:

Copy the nodeRef value and set it as the value for the script-ref action parameter.

Now run this process model. We should see a similar effect on the file as in the Apply Aspect action execution.

Being able to execute a script like this gives you almost unlimited possibilities in processing the Repository content. However, it is not possible to pass parameters to the script, so this action probably needs to work in conjunction with some other task.

Set Content Type for a file

Another very useful thing to be able to do from Activiti is to set a new type for a content file in SkyVault. This can be done by executing the specialise-type Repository Action. Create a new process model with a Start Event form that has an attachment field. Then add the “Call SkyVault Action” task.

Configure the Content and Repository properties for the task as follows:

So we now know what repository to talk to and what file to set the content type on. Next step is to configure the Action property for the task:

Select Specialise type from the Action drop down. This will add the mandatory type-name parameter. The parameter has to be set to the content model type name. For example: myc:caseDocument. Note that for this action to have any effect the type we set must extend the type already set on the content file.

Because the files in the Case Management site already have the myc:caseDocument type set, we will have to upload a new file to the Case Management site’s Document Library before we try this out.

Moving a file

One quite useful thing to be able to do from Activiti is to move a file in the SkyVault Repository after some processing have been done on it in the workflow, maybe something like a review and approval. This can be done by executing the move Repository Action. Create a new process model with a Start Event form that has an attachment field. Then add the “Call SkyVault Action” task.

Configure the Content and Repository properties for the task as follows:

So we now know what repository to talk to and what file to move. Next step is to configure the Action property for the task:

Select Move from the Action drop down. This will add the mandatory destination-folder parameter. The parameter has to be set to the SkyVault Node Reference for the folder where you want to move the file. For example: workspace://SpacesStore/2a8052aa-e5ec-4546-85bf-49f55f6b7e81

In this sample I have just created an Approved folder in the Case Management site’s Document Library:

Now, to find out the Node Reference for this folder have a look at the Folder Details Page in SkyVault Share, it will have a link property with this information:

Copy the nodeRef value and set it as the value for the destination-folder action parameter.

Now run this process model. We should see that the selected file is moved into the Approved folder.

Table of Contents                   

Introduction

The Activiti Enterprise application comes with an extensive REST API. However, sometimes it might be useful to add your own REST API, to for example support a domain specific workflow implementation. However, before starting any major REST API development, make sure that you are familiar with the REST API that is available out of the box, so you don’t implement stuff that is already supported. It might also at this point be a good idea to read up a bit on the Spring Web MVC framework, which is what the Activiti REST API is based on.

Here is a quick summary to get you going. Spring’s annotation based MVC framework simplifies the process of creating RESTful web services. The key difference between a traditional Spring MVC controller and the RESTful web service controller is the way the HTTP response body is created. While the traditional MVC controller relies on the View technology, the RESTful web service controller simply returns the object and the object data is written directly to the HTTP response as JSON or XML.

In the traditional workflow the ModelAndView object is forwarded from the controller to the client. Spring lets you return data directly from the @Controller, without looking for a view, using the @ResponseBody annotation on a method. When you use the @ResponseBody annotation on a method, Spring converts the return value and writes it to the HTTP response automatically. Each method in the Controller class must be annotated with @ResponseBody.

Beginning with Spring version 4.0, this process is simplified even further with the introduction of the @RestController annotation. It is a specialized version of the controller which is a convenience annotation that does nothing more than adding the @Controller and @ResponseBody annotations. By annotating the controller class with @RestController annotation, you no longer need to add @ResponseBody to all the methods that should map to requests. The @ResponseBody annotation is active by default. You can read more about it here.

Source Code

Source code for the Activiti Developer Series can be found here.

Prerequisites

Before starting with your REST API implementation make sure to set up a proper Activiti Extension project.

Implementing a Custom REST API

This section walks you through the process of creating a "Hello World" REST API with Spring.

We will build a REST endpoint that accepts the following HTTP GET requests:

http://localhost:8080/activiti-app/app/hello:

http://localhost:8080/activiti-app/app/hello?name=Martin:  

http://localhost:8080/activiti-app/app/hello/martin:

As you can see, we can make a GET request to the endpoint in three different ways, without any parameters with /hello, with a query parameter like /hello?name={name}, and with a path parameter like /hello/martin. The response to all these requests will be XML. We will see later on how to change it to also support JSON.

Implementing the REST Controller

In Spring’s approach to building web sites, HTTP requests are handled by a controller. You can easily identify these request classes by the @RestController annotation. In the following example, the HelloWorldController handles GET requests for /hello by returning XML.

package com.activiti.extension.rest;

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/hello")
public class HelloWorldRestController {

  @RequestMapping(value = "/", method= RequestMethod.GET)
  public GreetingMessage sayHello(@RequestParam(value="name", required=false,
                                                defaultValue="World") String name) {
      GreetingMessage msg = new GreetingMessage(name, "Hello " + name + "!");
      return msg;
  }

  @RequestMapping(value = "/{name}", method= RequestMethod.GET)
  public GreetingMessage sayHelloAgain(@PathVariable String name) {
      GreetingMessage msg = new GreetingMessage(name, "Hello " + name + "!");
      return msg;
  }
}

Note here in which Java package this class is located in: com.activiti.extension.rest. This will register this endpoint as available under /activiti-app/app URL path. It is then meant to be used in the application UI. And it will use cookie based authentication. So if we are logged into the Activiti Application when trying this REST endpoint, then there will be no need to authenticate.

The use of the @RestController annotation marks this class as a controller where every method returns a domain object/POJO instead of a View. All URLs will start with /hello for this controller. We are responding with a domain object converted into format understood by the consumers. In our case, due to the Jackson library being included in the class path, the GreetingMessage object will be converted into XML format (or into JSON as we will see later on).

The @RequestMapping annotation specifies the exact request that will map to the class and method, for example /app/hello/martin will map to the class and the sayHelloAgain method. The request method (i.e. GET, POST etc) has no default value so we need to set it to something, HTTP GET in this case.

For the response to be converted into XML we also provide the following data transfer object class:

package com.activiti.extension.rest;

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import java.io.Serializable;

@XmlRootElement(name = "greeting")
public class GreetingMessage implements Serializable {
  String name;
  String text;

  public GreetingMessage() {}

  public GreetingMessage(String name, String text) {
      this.name = name;
      this.text = text;
  }

  @XmlElement(name = "name")
  public String getName() {
      return name;
  }

  @XmlElement(name = "text")
  public String getText() {
      return text;
  }
}

This class uses the JAXB annotations to tell Spring MVC what XML elements to use in the responses.

Making the REST endpoint part of Public API

So far we created a REST endpoint that is available in the Activiti Application context with cookie based authentication. This is not ideal for the public REST API. We would like to instead have it available under /activiti-app/api and supporting basic authentication.

To make this happen we need to do just a few changes, here is the updated controller:

package com.activiti.extension.api;

import com.activiti.extension.rest.GreetingMessage;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/enterprise")
public class HelloWorldRestController {

  @RequestMapping(value = "/hello", method= RequestMethod.GET)
  public GreetingMessage sayHello(@RequestParam(value="name", required=false, 
                                                defaultValue="World") String name) {
      GreetingMessage msg = new GreetingMessage(name, "Hello " + name + "!");
      return msg;
  }

  @RequestMapping(value = "/hello/{name}", method= RequestMethod.GET)
  public GreetingMessage sayHelloAgain(@PathVariable String name) {
      GreetingMessage msg = new GreetingMessage(name, "Hello " + name + "!");
      return msg;
  }
}

The class has been moved into the com.activiti.extension.api package. This package is scanned automatically by Activiti and any components are instantiated as custom REST endpoints in the public REST API, protected by basic authentication. Note that the endpoint needs to have /enterprise as first element in the URL, as this is configured in the SecurityConfiguration to be protected with basic authentication (more specifically, the api/enterprise/* path).

Now, with basic auth available, it is easy to use other clients than the browser, such as Postman, curl etc. We can also in an easy way request JSON responses by setting the Accept header.

Let’s look at a couple of calls using Postman. First we need to set up the Authorization:

Then configure the Accept header to application/json to see that we can get responses in JSON format:

Now, click Send button with the http://localhost:8080/activiti-app/api/enterprise/hello?name=Martin GET URL specified as above:

We can see the JSON response. To have responses in XML, just remove the Accept header:

Using curl is as easy:

$ curl -u admin@app.activiti.com:admin http://localhost:8080/activiti-app/api/enterprise/hello?name=Martin |xmlstarlet fo

 % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current

                                Dload  Upload   Total   Spent    Left  Speed

100   121    0   121    0     0   7330      0 --:--:-- --:--:-- --:--:--  7562

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<greeting>

 <name>Martin</name>

 <text>Hello Martin!</text>

</greeting>

Here we are piping the XML response into the xmlstarlet tool for formatting. To get JSON responses, do something like this:

$ curl -u admin@app.activiti.com:admin -H "Accept: application/json" http://localhost:8080/activiti-app/api/enterprise/hello?name=Martin |jq '.'

 % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current

                                Dload  Upload   Total   Spent    Left  Speed

100    40    0    40    0     0   3587      0 --:--:-- --:--:-- --:--:--  3636

{

 "name": "Martin",

 "text": "Hello Martin!"

}

In this case we are using the jq command line tool for formatting of the JSON response.

Injecting Spring Beans into the REST Controller

So far we have used a REST controller class that was not dependent on any other component. In a real scenario we are likely to have to wire in custom beans and out-of-the-box beans.

Take the following custom Spring Bean:

package com.activiti.extension.bean.service;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;

@Service
public class HelloWorldService {
  private static Logger logger = LoggerFactory.getLogger(HelloWorldService.class);

  public String greeting() {
      logger.info("Custom Service method greeting() was called");
     
      return "Hello World from Service!";
  }
}

It’s defined in a sub-package to the com.activiti.extension.bean package so it will be picked up by Activiti during scanning and registered as a Spring bean with the helloWorldService name.

We can now wire this bean into our REST Controller as follows:

package com.activiti.extension.api;

import com.activiti.domain.idm.User;
import com.activiti.extension.bean.service.HelloWorldService;
import com.activiti.extension.rest.GreetingMessage;
import com.activiti.service.api.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/enterprise")
public class HelloWorldRestController {

  @Autowired
  HelloWorldService helloWorldService;

  @Autowired
  UserService userService;

  @RequestMapping(value = "/hello", method= RequestMethod.GET)
  public GreetingMessage sayHello(@RequestParam(value="name", required=false,
                                                defaultValue="World") String name) {
      long userId = 1; // Admin
      User user = userService.findUser(userId);
      String username = user.getFirstName() + " " + user.getLastName();

      GreetingMessage msg = new GreetingMessage(name, "Hello " + name +
                ", service message: " + helloWorldService.greeting() +
                ", userId = 1 = " + username);

      return msg;
  }

  @RequestMapping(value = "/hello/{name}", method= RequestMethod.GET)
  public GreetingMessage sayHelloAgain(@PathVariable String name) {
      GreetingMessage msg = new GreetingMessage(name, "Hello " + name + "!");

      return msg;
  }
}

As you can see, we also wire in one of the out-of-the-box services called UserService, and use it to get the first name and last name of the Administrator user.

Making a call via curl now shows the following response, that have involved to external beans:

$ curl -u admin@app.activiti.com:admin -H "Accept: application/json" http://localhost:8080/activiti-app/api/enterprise/hello?name=Martin |jq '.'

 % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current

                                Dload  Upload   Total   Spent    Left  Speed

100   116    0   116    0     0   1509      0 --:--:-- --:--:-- --:--:--  1526

{

 "name": "Martin",

 "text": "Hello Martin, service message: Hello World from Service!, userId = 1 = null Administrator"

}

The administrator user has no first name, hence it is null.

Calling a REST endpoint from a Process

Closely related to implementing a custom REST API is calling out to REST endpoints from a process. This can be done with the out-of-the-box REST call task:

Read more about it here and watch this video for a detailed walkthrough. The custom REST call task does not have to be configured to call an external web service, such as a weather service. It can also call back into the Activiti public REST API. This means it could actually call the custom REST API we created in this article.

Table of Contents                   

Introduction

Listeners are an Activiti extension to the BPMN 2.0 standard that implement hook points inside a process definition. These are triggered by events during workflow execution. There are two type of listeners, task and execution.

Execution listeners can be configured on the process itself, as well as on activities and on transitions. Task listeners can only be configured on user tasks.

Listeners enable you to run code during the execution of the process instance. This can be script code or a call to a Java class. The following diagram shows the events in a process definition where you can configure a listener:

This picture also illustrates the order in which the event listeners will be invoked. Note for example that an assign task listener is invoked before a create task listener, which might be a bit surprising.

Listeners are described in more detail in the Activiti user guide, see the execution listeners docs and the task listeners docs.

Source Code

Source code for the Activiti Developer Series can be found here.

Prerequisites

Before starting with your listener implementation make sure to set up a proper Activiti Extension project.

Implementing Java backed Listeners

Let’s implement one execution listener and one task listener in Java and configure them for all the events shown for the process definition in the introduction section. The listeners will not do much more than print a log message.

Coding the Java classes

This section goes through how to implement both the execution and the task listener.

Implementing the Execution Listener

Here is the implementation of the Execution Listener class:

package com.activiti.extension.bean;

import org.activiti.engine.delegate.DelegateExecution;
import org.activiti.engine.delegate.ExecutionListener;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class HelloWorldExecutionListener implements ExecutionListener {
  private static Logger logger = LoggerFactory.getLogger(HelloWorldExecutionListener.class);

  @Override
  public void notify(DelegateExecution execution) throws Exception {
      logger.info("[Process=" + execution.getProcessInstanceId() +
                  "][event=" + execution.getEventName() +
                  "][ExecutionListener=" + this +
                  "][ActivityId=" + execution.getCurrentActivityId() + "]");
  }
}

The class has been created in the com.activiti.extension.bean package, but it does not have to be located in this package. It is just good practice to put the class in this package if it ever needs to be converted to a Spring Bean backed listener in the future. Then this package is scanned automatically by Activiti and any beans are instantiated.

An Execution Listener needs to implement the org.activiti.engine.delegate.ExecutionListener interface, which contains the notify method. This methods takes one parameter of type org.activiti.engine.delegate.DelegateExecution, which is how we get access to the process instance that is invoking this Listener. An Execution Listener object instance is shared between process instances, so the DelegateExecution parameter is our way of finding out information about the active process instance.

Notice how we use an external class here for logging and that the logger.info method could be called concurrently by multiple threads. So it needs to be thread safe, which it is. Same thing applies for other class members that we define and use in the notify method. We can do whatever we want inside the notify method as all threads have independent call stacks.

Implementing the Task Listener

Here is the implementation of the Task Listener class:

package com.activiti.extension.bean;

import org.activiti.engine.delegate.DelegateExecution;
import org.activiti.engine.delegate.DelegateTask;
import org.activiti.engine.delegate.TaskListener;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class HelloWorldTaskListener implements TaskListener {
  private static Logger logger = LoggerFactory.getLogger(HelloWorldTaskListener.class);

  @Override
  public void notify(DelegateTask task) {
      DelegateExecution execution = task.getExecution();

      logger.info("[Process=" + execution.getProcessInstanceId() +
                  "][event=" + task.getEventName() +
                  "][TaskListener=" + this +
                  "][ActivityId=" + execution.getCurrentActivityId() +
                  "][TaskAssignee=" + task.getAssignee() +
                  "][TaskForm=" + task.getFormKey() + "]");
  }
}

The class has been created in the com.activiti.extension.bean package, but it does not have to be located in this package. It is just good practice to put the class in this package if it ever needs to be converted to a Spring Bean backed listener in the future. Then this package is scanned automatically by Activiti and any beans are instantiated.

A Task Listener needs to implement the org.activiti.engine.delegate.TaskListener interface, which contains the notify method. This methods takes one parameter of type org.activiti.engine.delegate.DelegateTask, which is how we get access to the user task instance that is invoking this Listener. We can also get to the process execution via the task.getExecution method.

Via the passed in DelegateTask object you can also get to more details around the user task, such as who it is assigned to, its description, event, when it was created, what form it is using etc.

A Task Listener object instance is shared between process instances, so the DelegateTask parameter is our way of finding out information about the active process instance and user task instance.

Note. Task Listeners work only on User tasks, they will have no effect on for example a Service Task.

Testing the Listeners

Now to test the Listener implementations create a process model looking like this:

Then set up the listeners as follows, start by clicking on the canvas (not on any activity or event) so you can set the process level execution listener:

Clicking on the No execution listeners configured property brings up the following dialog:

Add the com.activiti.extension.bean.HelloWorldExecutionListener implementation for the start and end events. Then click on the User Task 1 activity:

Clicking on the No execution listeners configured property brings up the following dialog where we can set up listener for start and end event for activity User Task 1:

Save the execution listener configuration and then click on the task listeners property:

This bring up a dialog where we can configure task listeners for the different events:

Here we are using the com.activiti.extension.bean.HelloWorldTaskListener implementation. We can also see a new task event called delete that we can attach a task listener to, it will be invoked when the task instance is completed and deleted.

Now, for the sequence flow between the User Task 1 and the Simple Script Task set up an execution listener on the take event. First, click on the transition:

Then click on the No execution listeners configured property, which brings up the Execution Listener configuration dialog:

Use the com.activiti.extension.bean.HelloWorldExecutionListener implementation for the take event.

For the Simple Script Task set up execution listeners for the start and end event:

The configuration will look like this:

We also need to configure a script and script format for the Script task as it currently is failing validation:

Add a simple Groovy script that just prints a log message:

In BPMN 2.0 XML this will look like:

<process id="TestingListeners" name="Testing Listeners" isExecutable="true">
  <extensionElements>
      <activiti:executionListener event="start"
          class="com.activiti.extension.bean.HelloWorldExecutionListener"/>
      <activiti:executionListener event="end"
          class="com.activiti.extension.bean.HelloWorldExecutionListener"/>
  </extensionElements>

  <startEvent id="startEvent" name="Start Event"></startEvent>

  <sequenceFlow id="transitionStart2UserTask" 
                sourceRef="startEvent"
                targetRef="userTask1"></sequenceFlow>

  <userTask id="userTask1" name="User Task 1" activiti:assignee="$INITIATOR">
      <extensionElements>
          <activiti:executionListener event="start"
              class="com.activiti.extension.bean.HelloWorldExecutionListener"/>
          <activiti:executionListener event="end"
              class="com.activiti.extension.bean.HelloWorldExecutionListener"/>
          <activiti:taskListener event="create"
              class="com.activiti.extension.bean.HelloWorldTaskListener"/>
          <activiti:taskListener event="assignment"
              class="com.activiti.extension.bean.HelloWorldTaskListener"/>
          <activiti:taskListener event="complete"
              class="com.activiti.extension.bean.HelloWorldTaskListener"/>
          <activiti:taskListener event="delete"
              class="com.activiti.extension.bean.HelloWorldTaskListener"/>
      </extensionElements>
  </userTask>

  <sequenceFlow id="transitionUserTask2ScriptTask" 
                sourceRef="userTask1"
                targetRef="scriptTask">
      <extensionElements>
          <activiti:executionListener event="take"
              class="com.activiti.extension.bean.HelloWorldExecutionListener"/>
      </extensionElements>
  </sequenceFlow>

  <scriptTask id="scriptTask" name="Simple Script Task" 
              scriptFormat="groovy"
              activiti:autoStoreVariables="false">
      <extensionElements>
          <activiti:executionListener event="start"
              class="com.activiti.extension.bean.HelloWorldExecutionListener"/>
          <activiti:executionListener event="end"
              class="com.activiti.extension.bean.HelloWorldExecutionListener"/>
      </extensionElements>
      <script><![CDATA[print "Hello from Script Task"]]></script>
  </scriptTask>

  <sequenceFlow id="transitionScriptTask2EndEvent" 
                sourceRef="scriptTask"
                targetRef="endEvent"></sequenceFlow>

  <endEvent id="endEvent"></endEvent>
</process>

Note that the process definition has been updated so each element has a more descriptive ID. This will make it easier to see what is going on when we do logging. It is also easier to read the process definition.

When we start this process it will print similar logs to the following:

08:01:52,361 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=132501][event=start][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@47c496c6][ActivityId=startEvent]

08:01:52,368 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=132501][event=start][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@4dcb7e48][ActivityId=userTask1]

08:01:52,378 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - [Process=132501][event=assignment][TaskListener=com.activiti.extension.bean.HelloWorldTaskListener@3df0a8c4][ActivityId=userTask1][TaskAssignee=1][TaskForm=null]

08:01:52,379 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - [Process=132501][event=create][TaskListener=com.activiti.extension.bean.HelloWorldTaskListener@5cac7332][ActivityId=userTask1][TaskAssignee=1][TaskForm=null]

Here we can see that the execution listener set on the process level is invoked first when we get the process start event. Then we get the execution listener invoked again on the task start event. Then it moves on with task assignment and create event, invoking the task listener. All as expected. What might be unexpected is that there is actually one listener instance created for each event it is registered on. So here we have four unique listener objects (i.e. 47c496c6, 4dcb7e48, 3df0a8c4, and 5cac7332).

When we complete the User Task 1 the following logs are printed:

08:08:01,566 [http-nio-8080-exec-7] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - [Process=132501][event=complete][TaskListener=com.activiti.extension.bean.HelloWorldTaskListener@1d06918c][ActivityId=userTask1][TaskAssignee=1][TaskForm=null]

08:08:01,567 [http-nio-8080-exec-7] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - [Process=132501][event=delete][TaskListener=com.activiti.extension.bean.HelloWorldTaskListener@59681d0f][ActivityId=userTask1][TaskAssignee=1][TaskForm=null]

08:08:01,573 [http-nio-8080-exec-7] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=132501][event=end][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@1687fdbb][ActivityId=userTask1]

08:08:01,577 [http-nio-8080-exec-7] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=132501][event=take][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@4e282041][ActivityId=userTask1]

08:08:01,578 [http-nio-8080-exec-7] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=132501][event=start][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@7224678f][ActivityId=scriptTask]

08:08:02,281 [http-nio-8080-exec-7] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=132501][event=end][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@65230b79][ActivityId=scriptTask]

08:08:02,282 [http-nio-8080-exec-7] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=132501][event=end][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@24183909][ActivityId=endEvent]

As expected, we can see the task complete and delete events, followed by the end of user task. Then we get the invocation of the execution listener for the take event on the transition. Then we get the execution listener invoked for the start and end event of the script task activity. And finally the end event for the whole process.

Note again that each registration of a listener will get its own listener instance during runtime. Let’s see what happens if we start two processes in parallel, without completing the User task. Here is the logs from process one:

08:13:43,809 [http-nio-8080-exec-7] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=132509][event=start][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@47c496c6][ActivityId=startEvent]

08:13:43,811 [http-nio-8080-exec-7] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=132509][event=start][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@4dcb7e48][ActivityId=userTask1]

08:13:43,812 [http-nio-8080-exec-7] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - [Process=132509][event=assignment][TaskListener=com.activiti.extension.bean.HelloWorldTaskListener@3df0a8c4][ActivityId=userTask1][TaskAssignee=1][TaskForm=null]

08:13:43,812 [http-nio-8080-exec-7] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - [Process=132509][event=create][TaskListener=com.activiti.extension.bean.HelloWorldTaskListener@5cac7332][ActivityId=userTask1][TaskAssignee=1][TaskForm=null]

And then we start the second process:

08:15:00,808 [http-nio-8080-exec-9] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=132515][event=start][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@47c496c6][ActivityId=startEvent]

08:15:00,809 [http-nio-8080-exec-9] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=132515][event=start][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@4dcb7e48][ActivityId=userTask1]

08:15:00,810 [http-nio-8080-exec-9] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - [Process=132515][event=assignment][TaskListener=com.activiti.extension.bean.HelloWorldTaskListener@3df0a8c4][ActivityId=userTask1][TaskAssignee=1][TaskForm=null]

08:15:00,811 [http-nio-8080-exec-9] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - [Process=132515][event=create][TaskListener=com.activiti.extension.bean.HelloWorldTaskListener@5cac7332][ActivityId=userTask1][TaskAssignee=1][TaskForm=null]

Important thing to be aware of here is that listener instances will be re-used between processes.

Listeners and Thread Safety

When using execution and task listeners, things are not thread safe even if each event the listener is registered for results in a unique listener instance. This is because listener instances are shared between process instances. This could potentially lead to library code used in the listener implementation being called concurrently, and as a result it needs to be thread-safe, as the log library we used in our example. Same thing for any class member variables, access needs to be synchronized.

So use thread-safe libraries and avoid class members.

Using Process Variables in a Listener

Most of the time when you implement a listener you would want to use some process variable values. Process variables are typically set when the process instance is started, through the API, or by different activities in the process. They are stored in the database for each process instance.

So how do you pass these process variable values into the listener? It is not necessary to pass any value, you can access all process instance variables via the DelegateExecution object, or the DelegateTask object, and the getVariable method.

What variables that are available in a listener depends on if it is an execution listener or a task listener. So let’s talk about them separately.

Using Process Variables in an Execution Listener

This is very similar to how you read and write process variables in a Java Delegate, read the docs here.

Let’s say we got the following execution listener implementation:

public void notify(DelegateExecution execution) throws Exception {
  logger.info("[Process=" + execution.getProcessInstanceId() +
              "][event=" + execution.getEventName() +
              "][ExecutionListener=" + this +
              "][ActivityId=" + execution.getCurrentActivityId() + "]");

  String initiator = (String)execution.getVariable("initiator");
  logger.info("Initiator of the process has user ID = " + initiator);

  execution.setVariable("greeting1Proc", "Hello World!");
  execution.setVariableLocal("greeting1ProcLocal", "Hello World Local!");

  logger.info("--- Process variables:");
  Map<String, Object> procVars = execution.getVariables();
  for (Map.Entry<String, Object> procVar : procVars.entrySet()) {
      logger.info("   [" + procVar.getKey() + " = " + procVar.getValue() + "]");
  }
}

It will result in the following log messages if we look at for example the output from the execution listener attached to the process start event:

09:10:02,994 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=140005][event=start][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@25c1060a][ActivityId=startEvent]

09:10:02,994 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - Initiator of the process has user ID = 1

09:10:02,994 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - --- Process variables:

09:10:02,994 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  -    [greeting1Proc = Hello World!]

09:10:02,994 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  -    [greeting1ProcLocal = Hello World Local!]

09:10:02,994 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  -    [initiator = 1]

Using Process Variables in a Task Listener

When it comes to using process variables in a task listener we have to take into account a new scope. The user task is created in a sub-scope to the process instance. So if we got process variables, will they get propagated to the task scope, yes they will, automatically.

Take the following task listener implementation:

public void notify(DelegateTask task) {
  DelegateExecution execution = task.getExecution();

  logger.info("[Process=" + execution.getProcessInstanceId() +
              "][event=" + task.getEventName() +
              "][TaskListener=" + this +
              "][ActivityId=" + execution.getCurrentActivityId() +
              "][TaskAssignee=" + task.getAssignee() +
              "][TaskForm=" + task.getFormKey() + "]");

  String initiator = (String)execution.getVariable("initiator");
  logger.info("Initiator of the process has user ID = " + initiator);

  execution.setVariable("greeting2Proc", "Hello World!");
  execution.setVariableLocal("greeting2ProcLocal", "Hello World Local!");
  task.setVariable("greetingTask", "Hello World!");
  task.setVariableLocal("greetingTaskLocal", "Hello World Local!");

  logger.info("--- Process variables:");
  Map<String, Object> procVars = execution.getVariables();
  for (Map.Entry<String, Object> procVar : procVars.entrySet()) {
      logger.info("   [" + procVar.getKey() + " = " + procVar.getValue() + "]");
  }

  logger.info("--- Task variables:");
  Map<String, Object> taskVars = task.getVariables();
  for (Map.Entry<String, Object> taskVar : taskVars.entrySet()) {
      logger.info("   [" + taskVar.getKey() + " = " + taskVar.getValue() + "]");
  }
}

This will print a log looking something like this for the user task assignment event:

09:10:03,006 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - [Process=140005][event=assignment][TaskListener=com.activiti.extension.bean.HelloWorldTaskListener@62afbe29][ActivityId=userTask1][TaskAssignee=1][TaskForm=null]

09:10:03,006 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - Initiator of the process has user ID = 1

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - --- Process variables:

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [greeting1Proc = Hello World!]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [greeting1ProcLocal = Hello World Local!]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [greeting2Proc = Hello World!]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [initiator = 1]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [greetingTask = Hello World!]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [greeting2ProcLocal = Hello World Local!]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  - --- Task variables:

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [greeting1Proc = Hello World!]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [greeting1ProcLocal = Hello World Local!]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [greeting2Proc = Hello World!]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [greetingTaskLocal = Hello World Local!]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [initiator = 1]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [greetingTask = Hello World!]

09:10:03,008 [http-nio-8080-exec-5] INFO  com.activiti.extension.bean.HelloWorldTaskListener  -    [greeting2ProcLocal = Hello World Local!]

Let’s start with process scoped variables, we can see that we got all the variables we set available in the process scope, including variables such as greeting1Proc that has been set by previous execution listeners and variables such as greetingTask that has been set in task scope. However, there is one variable missing, the greetingTaskLocal. This is because the task instance is created in a sub-scope to the process scope, and when you use task.setVariableLocal("greetingTaskLocal", "Hello World Local!"), it will set this variable only in the task scope. A local task variable will not be propagated to the process scope and it will be gone when the task instance is deleted.

Now let’s see what variables we got available in the task scope, the “task variables”. We can see that we got all the process scoped variables (i.e. greeting1Proc, greeting2Proc, greeting1Local, and greeting2Local) as they are automatically propagated through to the task scope when the task instance is created. Besides the greetingTask variable we can also see the local task variable greetingTaskLocal.

Now let’s see what process variables will be available when we get to the script task. Let’s complete the user task and we should then see the following variables when we enter the start event for the script task:

09:30:21,630 [http-nio-8080-exec-1] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - [Process=140005][event=start][ExecutionListener=com.activiti.extension.bean.HelloWorldExecutionListener@5b12a6e][ActivityId=scriptTask]

09:30:21,630 [http-nio-8080-exec-1] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - Initiator of the process has user ID = 1

09:30:21,633 [http-nio-8080-exec-1] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  - - Process variables:

09:30:21,633 [http-nio-8080-exec-1] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  -    [greeting1Proc = Hello World!]

09:30:21,633 [http-nio-8080-exec-1] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  -    [greeting1Local = Hello World Local!]

09:30:21,633 [http-nio-8080-exec-1] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  -    [greeting2Proc = Hello World!]

09:30:21,633 [http-nio-8080-exec-1] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  -    [initiator = 1]

09:30:21,633 [http-nio-8080-exec-1] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  -    [greetingTask = Hello World!]

09:30:21,633 [http-nio-8080-exec-1] INFO  com.activiti.extension.bean.HelloWorldExecutionListener  -    [greeting2ProcLocal = Hello World Local!]

We can see that we got pretty much all variables we have set available, the only one that is not available any more is the greetingTaskLocal as it was set locally in the user task scope. The reason we can see the greetingTask variable here is that when it was set in the task scope with task.setVariable, this method will actually navigate up the scope hierarchy until it reaches a root scope and set it there, or overwrite any local variable with the same name on the way.

Using Field Injection in a Listener

This works in the same way as for service task POJO Java Delegates. See docs.

Making the Listener a Spring Bean

This works in the same way as for service task Spring Bean Java Delegates. See docs.

A “springified” execution listener looks like this:

package com.activiti.extension.bean;

import org.activiti.engine.delegate.DelegateExecution;
import org.activiti.engine.delegate.ExecutionListener;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

import java.util.Map;

@Component("helloWorldExecutionListener")
public class HelloWorldSpringExecutionListener implements ExecutionListener {
  private static Logger logger = LoggerFactory.getLogger(HelloWorldSpringExecutionListener.class);

  @Override
  public void notify(DelegateExecution execution) throws Exception {
      logger.info("[Process=" + execution.getProcessInstanceId() +
                  "][event=" + execution.getEventName() +
                  "][ExecutionListener=" + this +
                  "][ActivityId=" + execution.getCurrentActivityId() + "]");
  }
}

And it is used as in the following example:

And the BPMN 2.0 XML for this will look like:

<sequenceFlow id="transitionStart2UserTask" sourceRef="startEvent" targetRef="userTask1">
  <extensionElements>
      <activiti:executionListener 
         event="take"
         delegateExpression="${helloWorldExecutionListener}"/>
  </extensionElements>
</sequenceFlow>

And in a similar way we can easily turn a task listener into a Spring bean:

package com.activiti.extension.bean;

import org.activiti.engine.delegate.DelegateExecution;
import org.activiti.engine.delegate.DelegateTask;
import org.activiti.engine.delegate.TaskListener;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

import java.util.Map;

@Component("helloWorldTaskListener")
public class HelloWorldSpringTaskListener implements TaskListener {
  private static Logger logger = LoggerFactory.getLogger(HelloWorldSpringTaskListener.class);

  @Override
  public void notify(DelegateTask task) {
      DelegateExecution execution = task.getExecution();

      logger.info("[Process=" + execution.getProcessInstanceId() +
                  "][event=" + task.getEventName() +
                  "][TaskListener=" + this +
                  "][ActivityId=" + execution.getCurrentActivityId() +
                  "][TaskAssignee=" + task.getAssignee() +
                  "][TaskForm=" + task.getFormKey() + "]");
  }
}

Note. as mentioned before, these classes need to be located in the com.activiti.extension.bean package to be picked up by Activiti bean scanning.

And it is used as in the following example, click on the User task and then on the task listeners property:

And the BPMN 2.0 XML for this will look like:

<userTask id="userTask1" name="User Task 1" activiti:assignee="$INITIATOR">
  <extensionElements>
      <activiti:executionListener event="start"
          class="com.activiti.extension.bean.HelloWorldExecutionListener"/>
      <activiti:executionListener event="end"
          class="com.activiti.extension.bean.HelloWorldExecutionListener"/>

      <activiti:taskListener event="create"
          delegateExpression="${helloWorldTaskListener}"/>

      <activiti:taskListener event="assignment"
          class="com.activiti.extension.bean.HelloWorldTaskListener"/>
      <activiti:taskListener event="complete"
          class="com.activiti.extension.bean.HelloWorldTaskListener"/>
      <activiti:taskListener event="delete"
          class="com.activiti.extension.bean.HelloWorldTaskListener"/>
  </extensionElements>
</userTask>