User task listeners

Beginner Time estimate: 35 minutes

In Camunda 8, user task listeners allow you to run custom logic in response to changes to a user task, such as when the creating, assigning, or completing event occurs.

User task listeners facilitate the integration of custom logic into your workflows. For more details, refer to the User Task Listeners concept.

This guide walks you through:

• Defining a task listener using Camunda Modeler
• Implementing a task listener as a job worker
• Verifying the result in Operate and Tasklist

Prerequisites

You must have access to a Camunda 8 SaaS account.

Have you signed up for Camunda yet?

Sign Up

Visit signup.camunda.com/accounts to sign up.

Create an account

Fill out the form and click Create account.

When you fill out the form, you'll receive a confirmation email. Click on the link to verify your email address.

Log in to your Camunda 8 account

Log in with the email address and password you used in the previous form, or use the social login buttons. To access the login site directly, navigate to camunda.io.

After login, select the square-shaped Camunda components icon in the upper-left corner, and select Console to view the Console overview page. This is the central place to manage the clusters, diagrams, and forms you want to deploy to Camunda 8.

You must also know how to model a process with a user task.
If you haven't done this before, first follow the steps in our guide to get started with human task orchestration.

Additionally, you need the following:

• Java ≥ 8
• Maven
• IDE (IntelliJ, VSCode, or similar)
• Download and unzip or clone the repository, then navigate to:
  camunda-platform-tutorials/quick-start/task-listeners/task-listener-java

Step 1: Create a process with a user task in Modeler

1. Launch Camunda Modeler.
2. Create a new BPMN file.
3. Add a user task named Review application.

note

In this guide, you can also use the example BPMN from the repo located in camunda-platform-tutorials/quick-start/task-listeners/task-listener-java/src/main/resources/Quick_Start_Task_Listeners.bpmn. In that case, just explore the BPMN using the steps below, but do not adjust the model in steps 2-4.

Step 2: Select the user task

1. Click the user task (e.g., “Assigned by creating task listener”).
2. In the right-hand properties panel, scroll to Task listeners.

Step 3: Define a task listener

We'll now add a new task listener to the user task and define its properties.

1. Click the plus sign in the Task listeners section to add a new task listener.
2. Under Event type, select creating.
3. Under Listener type, enter assign_new_task.

info

You've now defined a creating task listener for this user task. When a process instance arrives at this user task, the creating event is triggered, and a job of type assign_new_task is created. A job worker can then activate this job to execute the external logic and complete it, approving the creation of the user task.

Step 4: Create a cluster

To deploy and run your process, you must create a cluster in Camunda 8.

1. To create a cluster, navigate to Console by clicking the square-shaped icon labeled Camunda components in the top left corner, and click Console.
2. Click the Clusters tab, and click Create new cluster.
3. Name your cluster. For the purpose of this guide, we recommend using the Stable channel and the latest generation. Additionally, select your region. Click Create cluster.
4. Your cluster will take a few moments to create. Check the status on the Clusters page or by clicking into the cluster itself and looking at the Applications section.

Even while the cluster shows a status Creating, you can still proceed to begin modeling.

note

Zeebe must show a status of Healthy to properly deploy your model.

Development clusters

Starter plan users have one development cluster, with free execution for development, included in their plan. Deployment and execution of models (process instances, decision instances, and task users) is provided at no cost. Additional clusters can be purchased through your billing reservations.

Visit the clusters page to learn more about the differences between development clusters and production clusters. Additionally, review the related Camunda Academy course on creating clusters.

Starter plans

The Starter plan is no longer available.

• Existing customers using a Starter plan will need to either upgrade to the Enterprise plan, or move to the Free plan.
• To compare plan features and contact Camunda for advice and an Enterprise plan quote, refer to Camunda 8 pricing.

Step 5: Deploy the process

1. Click Deploy current diagram.
2. Select your Camunda 8 cluster.
3. Click Deploy.

Step 6: Start a process instance to create the user task

1. Start a new process instance by clicking on the blue Run button.
2. In the top left corner of the screen, click the square-shaped Camunda components button.
3. Navigate to Tasklist and notice that there is no task in Tasklist yet.
4. Navigate to Operate to see your process instance with a token waiting at the user task by clicking View process instances.
5. Click the user task and then click the Listeners tab to see that the Creating listener is Active.
6. Take a moment to understand the properties of the listener, for example verify that the listener type is what you defined in the process model. This listener is a job that can be activated and handled by a job worker.

Step 7: Implement the listener

Next, we'll run the listener application to execute our external logic, and complete the listener job to continue the user task's creation.

Create credentials for your Zeebe client

To interact with your Camunda 8 cluster, you'll use the Zeebe client. First, you'll need to create credentials.

1. The main page for Console should be open on another tab. Use Console to navigate to your clusters either through the navigation Clusters or by using the section under View all on the Clusters section of the main dashboard. Click on your existing cluster. This will open the Overview for your cluster, where you can find your region Id and cluster Id (in your client credentials under the API tab within your cluster). You will need this information later when creating a worker in the next section.
   note

   If your account is new, you should have a cluster already available. If no cluster is available, or you’d like to create a new one, click Create New Cluster.

2. Navigate to the API tab. Click Create.
3. Provide a descriptive name for your client like microservice-worker. For this tutorial, the scope can be the default Zeebe scope. Click Create.
4. Your client credentials can be copied or downloaded at this point. You will need your client ID and your client secret when creating a worker in the next section, so keep this window open. Once you close or navigate away from this screen, you will not be able to see them again.

Create a job worker to implement the task listener

Next, we’ll create a worker that listens to the user task's events by associating it with the Listener type we specified on the task listener in the BPMN diagram.

1. Open the downloaded or cloned project (repo, then cd into camunda-platform-tutorials/quick-start/task-listeners/task-listener-java) in your IDE.
2. Add your credentials to application.properties. Your client ID and client secret are available from the previous section in the credential text file you downloaded or copied. Go to the cluster overview page to find your region Id and cluster Id (in your client credentials under the API tab within your cluster).
3. In the Listener.java file, change the type to match what you specified in the BPMN diagram. If you followed the previous steps for this guide and entered “assign_new_task”, no action is required.
4. After making these changes, perform a Maven install, then run the Listener.java main method via your favorite IDE. If you prefer using a terminal, run mvn package exec:java.

Step 8: Verify the result in Operate and Tasklist

Now that the task listener is running, the listener job will have been handled and completed. Let's see what effects this has had.

1. Navigate to Operate and see that the listener that was Active previously, has now been Completed.
2. Navigate to Tasklist and see that the task is available and assigned to the assignee or manager that you provided.

Suggestions for further exploration

To build your understanding of task listeners, you can also:

• Stop the listener application.
• Start a new instance of the process, and notice that the task does not appear in Tasklist.
• Check Operate, and notice that a creating listener is active.
• Restart the listener application and notice that the listener failed, and an incident is raised.
• Set a variable assignee or manager in the process instance, and resolve the incident.
• Check Tasklist, and notice that the task is assigned to the assignee or manager that you provided.

Further, you can try the following:

• Add a separate listener for another event type, and trigger that event.
• Access the user task's data from the activated job.
• Correct the assignee in the listener by adding a job result to the complete job command.
• Deny the assignment from the listener to avoid the task's assignment altogether.

Additional resources and next steps

• Learn more about Camunda 8 and what it can do by reading What is Camunda 8 or watching our Overview video in Camunda Academy.
• Get your local environment ready for development with Camunda 8 by setting up your first development project.