Working with Task Listeners

The Activiti API provides extension points to create custom implementations that you can trigger where necessary. Task Listener is one such extension point, which you can use to trigger a custom implementation upon the occurrence of a particular task. For more information, go to Task Listener in the Activiti User Guide. Also, for information on other event listeners that allow you to handle various events in business processes, go to Event handlers in the Activiti User Guide.

The sections below demonstrate how to use Task Listeners to extend BPMN capabilities to handle events via business processes.

Creating the Task Listener implementation

In the BPMN Explorer, the default description of a Task, which is created by a Process is displayed as "Description not available".

In this guide, you create a custom Task Listener to change the description whenever a Task is created by the process you deploy. Follow the steps below to create the Task Listener implemention as a Maven Project.

Creating the Maven Project

Follow the steps below to create the Maven Project to create the Task Listener implementation.

1. Create a new Maven Project with the below details. For instructions, see Creating a Maven Project.
   
   • Group Id: org.wso2.bpmn
   • Artifact Id :  TaskListenerMaven
   • Java Package Name: org.wso2.tasklistener
   • Java Class Name:  TaskListenerV1
   • Interface of the Java Class: org.activiti.engine.delegate.TaskListener

2. Replace the default content with the below to implement the business logic of the Task Listener in the  TaskListenerV1.java file as shown below.

   package org.wso2.tasklistener;
   
   import org.activiti.engine.delegate.DelegateTask;
   import org.activiti.engine.delegate.TaskListener;
   
   public class TaskListenerV1 implements TaskListener {
   
   	 public void notify(DelegateTask delegateTask) {
   	     delegateTask.setDescription("First Task Listener");
   	 
   	    }
   
   }

   

3. Add the following dependency to the  pom.xml  file of the Service Task as shown below.

   <dependency>
       <groupId>org.activiti</groupId>
       <artifactId>activiti-engine</artifactId>
       <version>5.17.0</version>
   </dependency>

   
   

4. Build the Maven Project and add the built JAR file to the <EI_HOME>/lib directory to deploy it. For instructions, see  Deploying artifacts of the Maven Project.

Creating the BPMN Project

Follow the steps below to create a BPMN Project with a User Task to implmenet the Task Listener.

1. Create a new BPMN project named TaskListener. For instructions, see Creating a BPMN Project.
2. Create a BPMN Diagram named TaskListener .bpmn. For instructions, see Creating the BPMN Diagram.
3. Click anywhere on the canvas, go to the  Properties  tab, and fill in the following details:
   Id                :  helloworld
   Name          :  Hello World Process
   Namespace : http://wso2.org/bpmn/helloworld
   
4. To implement the order approval process, drag and drop a StartEvent, a UserTask, and an End Event to the canvas. 
   
5. Click on the  User Task  and set the Name as Change Task Description in the  General  section of the  Properties  tab.
   
   
6. Click on the User Task and set the Assignee as admin in the Main config section of the Properties tab.
   
   
7. Click on the User Task and click New in the Listeners section of the Properties tab.
   
8. Enter the below details and click OK.
   
   • Event: create
   • Type: Java class
   • Class: Click Select Class, type  select org.wso2.tasklistener.TaskListenerV1 in the search bar and select it.

   
   
   
   This adds the Task Lister to the User Task as shown in the below configuration.

   <userTask id="myTask" name="My Task" >
     <extensionElements>
       <activiti:taskListener event="create" class="org.wso2.testbpmn.FirstTaskListener"/>
     </extensionElements>
   </userTask>

    Use the event parameter of the User Task to define the event that should trigger the Task Listener class.

Deploying artifacts of the BPMN Project

1. For instructions on creating the deployable artifacts, see Creating the deployable archive.
2. For instructions on deploying them, see Deploying BPMN artifacts.

Testing the output

Follow the steps below to test the output.

1. Log in to the BPMN-explorer at https://localhost:9445/bpmn-explorer using admin for both the username and password.
2. Click PROCESSES in the top menu, and click the Start option of the task Listener process.
   
   
3. Click Close in the message, which pops up.
   
4. Click TASKS in the top menu, and click My Tasks.
   
5.  Click on the new Change Task Description Task. You view the description changed to "First Task Listener" as shown below.