Camunda basics for execution

After learning modeling with Camunda Modeler, you are only few steps away from modeling also for execution. Before you start, please, open the properties panel of Camunda Modeler, either by clicking its handle on the right side of the modeler window or choosing Window -> Toggle Properties Panel from the menu bar.

Let’s now learn the minimum requirements for configuring a BPMN model to be ready for execution.

Process name and ID

Every BPMN model (process definition) for executable processes should have descriptive display Name and unique definition ID set, and Executable option checked. These are available on the properties panel when no element selected.

Service task configuration

At first, use element context modeling palette to turn a plain task into a service task. Once you see service task’s properties panel, the only really required property there is the service task Type on Task definition. This is the identifier you’ll be giving to your automation code executing the task later. The type should be unique on your environment, and it is up to you to guard that.

The Name and ID of the task has no effect on the execution. Choose a Name that describes the task work with verb in the domain language of the process. Having a naming policy for ID would help to identify service tasks from your logs. In addition, the playground has a feature to show Robot Framework logo for service tasks with robot in their ID. (The feature is case insensitive.)

Inputs and outputs

Input and output mappings on the properties panel allow to adapt domain specific process to more generic task implementations. All Camunda BPMN engines implement nested variable scopes by BPMN elements:

  • Element may have local variables not propagated back to process level.

  • Variables introduced in Inputs, are only available within the element.

  • Variables introduced in Inputs, and set as local by task implementation (job worker), are only propagated back to process through Outputs.

  • For Zeebe, variable assignment values on Inputs and Outputs must be valid FEEL expressions.

In our example, at service task, we use Inputs to set local variable completed with value false, expect the service task worker to update it, and then map its final using Outputs as variable workCompleted having the value of executed FEEL expression completed (which evaluates to the value of that local task variable during output mapping).

Gateway paths

How do exclusive gateways know which path should the token be directed to? Well, you have to tell them, how to.

At first, one of the outgoing paths from an exclusive gateway, could be configured as the default path from the element context modeling palette of the path. The rest of the paths should have condition expression defined.

In our example, the exclusive gateway has two ongoing paths. The default path with label No goes back join the main flow just before the service task. The other path with label Yes is followed when FEEL expression workCompleted evaluates to true. That happen when the process variable workCompleted has value true.

Warning

If expression for more than one path on a exclusive gateway results in true, a runtime incident will be raised.

Feel expressions

What are those FEEL expressions required for service task inputs, service task outputs and exclusive gateway conditions?

FEEL stands for Friendly Enough Expression Language. It is a pretty simple functional expression language for manipulating or testing process variables. With Camunda tools we use Camunda FEEL implementation. That said, unofficial FEEL playground is still probably the easiest place to learn how to use FEEL expressions to map or test process variables.

Use the embedded playground above to practice, how to access task variable completed, then add it into Variables as workCompleted and access it again. You have now implemented the expressions used in our example.

Executable process

Before deploying a model, it must be saved and given a filename. This is the model we’ve been building so far:

../_images/work-request.svg

work-request.bpmn

Deploy to Zeebe

The bottom toolbar of the modeler, has a dedicated Rocket button for deploying a model diagram to Zeebe engine. The playground Zeebe matches Camunda Platform 8 Self-Managed with Cluster endpoint http://localhost:26500 and Authentication: None.

Just press Deploy.

Start a new instance

There a are many ways to start a new process instance from deployed definition. A production solution being usually a custom user-interface or by a microservice through an API. While stil llearning, however, it is very convenient start the process directly from Modeler, from Play button on the bottom toolbar.

Just press Start.

Execute with Zeebe Play

Zeebe Play is an open source web application for Zeebe to play with processes while developing them. On the playground, Zeebe Play is opened from the Play desktop shortcut.

Zeebe Play desktop icon

Zeebe Welcome

Next, find your process by choosing deployments from Zeebe Play welcome screen.

Choosing deployment

Whenever you deploy a model diagram with an existing process definition id, it will become a new version of the existing process. Zeebe Play lists every deployment and its version on separate rows. To continue, try to find the latest one of the process you were developing.

Choosing instance

Once you’ve find the deployment, Zeebe Play lists every instance it knows on the chosen deployment, whether active, completed or manually terminated. Choose an active instance or start a new instance directly from Zeebe Play.

Complete task

Zeebe Play show executed paths as green. Whenever there is a token alive on actionable element, it will show action buttons on top of the elements for completing them.

Simply click the blue button with white checkmark on the left corner of the active service task to complete it.

Refresh for results

Currently Zeebe Play may not yet update the instance view automatically, but you need to manually click the highlighted button You may need to reload the page manually to see the changes.

Because the task Work on the example process was completed without payload to update task variables with, the variable completed remained false and process was routed back to the task.

Complete with variables

Just clicking the Zeebe action button on service tasks completes the tasks without payload. Fortunately, the dropdown on Zeebe Play action buttons, also offer to complete with Variables. Select it to complete the task (Complete job for the task) with the following variables (JSON):

{"completed": true}

Process completed

Finally, refresh the Zeebe Play view on process instance for one more time and observe the process being completed.

That’s how Zeebe Play allows us to play with the process and manually confirm that we have modeled its execution properly (without really implementing any of its service tasks yet).

Similarly to completing the service task, Zeebe Play also allows to trigger timer and error events (the later by throwing error from a task):

work-request-with-timer.bpmn
work-request-with-error.bpmn