In this blog post, I will walk you through version 0.1.14 of Apex Camunda Explorer. Explorer is a great way to learn about and interact with the Camunda 8 process engine called Zeebe. Explorer is built using low code Apex Designer and is available as a starting point to build your own tailored process automation experience.
Key Components
This diagram shows how the components interact with each other.
Explorer talks to Zeebe using the gRPC api. Zeebe sends a stream of events to Elasticsearch through the Zeebe Elasticsearch Exporter. Explorer reads the events from Elasticsearch, aggregates them for use in the user interface, and stores them in Postgres.
Process Administration
Just like the previous version, Explorer has process administration capabilities including uploading process definitions, creating process instances, managing tasks, managing process variables, and handling incidents.
Query Elasticsearch
It also provides a way to query Elasticsearch to understand what information is available in the event stream.
Task Assignments
The latest version of Explorer adds the ability to assign, claim, and complete user tasks. The first thing you will notice is that there is a link on the Process Definitions page that downloads a sample process. Open the process using the Camunda Modeler.
The process is a simple two step process that submits a vacation request and gets the vacation request reviewed.
Click on the Submit Vacation Request user task and you see that it is assigned to a specific user using an expression “= initiator”.
When Explorer starts a process instance, it sets the initiator process variable to the email address of the person that started the instance. This ensures that the task is assigned to the right person and is not picked up by someone else.
The Review Vacation Request user task has two candidate groups: Supervisors and Managers. These tasks will only be shown to users that have that role.
Explorer is built using Apex Designer and the Camunda 8 Library. The Camunda 8 Library includes all the business objects, properties, relationships and behaviors that interact with the Zeebe engine and Elasticsearch. This includes Process Definitions, Process Instances, Process Variables, Process Incidents and Tasks.
To manage task assignments, the latest version of the library adds a relationship between AppUser and Task as well as a new business object that links Tasks to Roles.
My Tasks Page
The process administration pages and APIs are all restricted to users with the Camunda Administrator role. The new version adds a My Tasks page that is accessible by all users.
The My Tasks page design in Apex Designer is simple and can be a great starting point for your own tailored tasks page.
The template (in the middle) has a breadcrumb with two icon buttons: one refreshes the list of task and the other starts a vacation request process instance. The loading container (which displays a progress bar while data is being loaded) contains a paragraph that is shown if the user does not have any tasks, a table for the tasks, and a Show More button.
The getTasks method calls the new myTasks behavior on the Task business object.
The myTasks behavior (and the others that end users would access) have logic that verifies that the user is assigned to the task or a member of one of the related groups.
Users Page
When the Camunda 8 Library pulls tasks from Elasticsearch, it links the task to the AppUser (if it is a directly assigned task) and/or adds TaskToRole links to link the task to the roles that are candidate users. If the role does not exist, it is created automatically. The Users page has been enhanced to not only show the Administrator (controls access) and Camunda Administrator (can access all process admin capabilities) but also all the other roles. Checking or unchecking a cell will assign or remove the role from that user.
User Task Forms using Camunda Forms
The second big addition to the latest version of Explorer is user task forms. When the user clicks a task on the My Tasks page, they are presented with a form to complete.
This user task has a Camunda Form. Notice that the Start Date field has a date picker. That is triggered by a baseType custom property that is set to DateWithoutTime. The Camunda 8 Library uses that information to determine which type of field to present on the form.
The Description field has a baseType of MultilineString.
Based on that, the Camunda 8 Library uses a textarea field for description that allows more than one line of text.
The Save button has two custom properties: action which tells Explorer that this button should save the process variables and color which sets the button color to the accent color on the app’s palette.
The My Task page design in Apex Designer handles the rendering of the Camunda Form using the Render Task With Camunda Form component from the Camunda 8 library.
User Task Forms using Angular Components
Camunda Forms are great for very simple tasks but most real world applications require more complex user interactions. The Review Vacation Request user task in the sample process uses an Angular component build in Apex Designer. In the modeler, a custom form key is set with the name of the component.
The getTask method on the My Task page retrieves the form key, finds that it starts with “apex-designer:component:” and uses the Render Angular Component to display the custom component.
Here is what the user sees when the click a Review Vacation Request user task.
The page is a mix of information from the process variables (start date, number of days and description) and information from the system(s) of record (name, email, photo, previous vacation requests - none in this case). This ensures that the user has all the information in front of them to make the decision.
The ReviewRequest component is modeled in Apex Designer.
The template contains a paragraph and heading. Then a row splits the screen width between the image and the fields. The fields are inside a Wrap component that switches from two columns of fields for medium and larger screens to one column on small and extra small screens. The other vacation requests are presented in a table followed by the heading, radio buttons and comments fields for the reviewer to fill in. Finally, there are two buttons: Save to save the data entered but not complete the task and Submit which completes the task with the data entered.
The getData method lists the process variables that are required along with information on which fields are required, which ones are disabled, and what base types should be used.
It then uses the Task Service from the Camunda 8 Library to set the current task, get the process variables and create a Form Group (an Angular data construct connected to form fields). Then it sets the where clause on the submitter object and reads it.
This is just one example of what you can do with Angular components for user tasks. Apex Designer makes it easy to create Angular components for user tasks. It provides low code productivity without limiting what you can do. Anything that you can do in Angular (which is pretty much anything) you can do in Apex Designer.
Give it a Try
The container image for Apex Camunda Explorer is published on Docker Hub. You can follow these installation instructions to set up Apex Camunda Explorer (along with Zeebe, Elasticsearch and Postgres) using Docker Compose on your local machine. If you like what you see, you can sign up for a trial of Apex Designer, create a project from the Apex Camunda Explorer template, and customize to your heart's content.
What’s Next for Apex Camunda Explorer?
We are continuously evolving the Camunda 8 Library in Apex Designer as well as Apex Camunda Explorer. If you have questions or would like to see specific features added, you can join the discussion on the Apex Designer Forum. You can also ask questions privately on the Apex Designer site.
