Get started with Camunda business process modeling in [#camunda]

Camunda is an important automation tool at LinkORB supporting team member onboarding, authorization requests, incident management response, and much more. This guide will walk team members through understanding and making basic modifications to existing Camunda processes.

Prerequesites

This guide will reference a Team HQ resource of existing Camunda processes. Access to these processes is not available to all team members and can be provided by a senior member of the engineering team.

Download the modeler

Start by downloading the open source desktop modeler, which is a free desktop application for modeling and designing business processes using BPMN (Business Process Model and Notation). Its graphical interface allows users to create, edit, and visualize process models.

As the download is compressed, consider extracting the files to a location other than your downloads folder for long-term retention. For example, in Windows, this might be C:\Program Files\.

Start the modeler

After extracting the files, locate and open Camunda Modeler.exe (Windows), Camunda Modeler.app (Mac) or camunda-modeler (Linux).

When asked to choose the right version for your project, select Camunda Platform 7 > BPMN diagram. This will open a blank business process model and notation file.

By hovering on the items in the left menu, notice how shapes represent process components like start events, gateways (decisions), tasks, and more.

Review an existing process

Instead of starting from scratch, it can be useful to review an existing process model in use at LinkORB. For this guide, let’s take a look at the Camunda process, which has Fonzie remind everyone in Mattermost about the weekly status update process.

All current Camunda processes can be found by selecting Processes from the main top navigation Team HQ.

Next, look for the TeamWeekUpdateProcess entry and select View Details.

Here you’ll see a visual representation of a process that starts at a specific time, performs a task, iterates over a subprocess, waits, performs a final task, and then ends.

Download and inspect the .BPMN file

To get even deeper, select Download as .BPMN. for the TeamWeekUpdateProcess. This will download a file called TeamWeekUpdateProcess.bpmn.

Returning to the Camunda desktop modeler, open the file with File > Open File. Next, select Window > Toggle Properties Panel.

By clicking on the canvas, you can view properties for the entire process. By clicking on individual process elements, properties for a given element are shown.

Understanding task execution

There are three primary tasks in this particular process. They are:

1. Get group members of the “weekupdate” group
2. Heads up Fonzie
3. Send Team Week Update Email

By selecting any of the three above tasks, properties for Implementation and Inputs are exposed in the properties panel.

Understanding implementation and exos

In the properties panel, implementation settings refer to Exo actions. As mentioned in the Exo README, exo’s are stateless, language agnostic functions. These functions-as-a-service (FaaS) are custom digital workers who accept a payload and then do a specific job.

While the link above is to LinkORB’s open-source Exo repository, the specific exo actions in the above tasks are stored in the below repositories:

• Core Exo Actions contains generic actions such as executing a Git clone, making an HTTP request, or executing a SQL query.
• LinkORB Exo Actions contains actions for interacting with LinkORB-specific services such as Omnia, Herald Server, or Userbase.

In both repositories, inside the individual directory for a given exo action are a YAML file and logic file. The YAML file documents and enforces valid inputs and outputs for the action, while the logic file contains the actual steps of the action. Browsing multiple actions will show PHP, Shell scripts, and other types of logic files.

In the case of the Heads up Fonzie task, in the properties panel under Implementation, you’ll see the exo is set to exo. The YAML and logic file for which are found at Core Exo Actions.

Understanding inputs

Inspecting the properties of the Heads up Fonzie task reveals the exo action as well as the task Inputs. In particular, this task has three inputs which are the payload sent to the exo action and provide values for:

Input	Value
channel	@${member.user.username}
text	${member.user.displayName} (${member.user.username}), here’s a quick reminder from your buddy Fonzie…
url	{{MATTERMOST_URL}}

A quick look at the exo.action.yaml in the mattermost-send-message/ directory at Core Exo Actions repo shows those same inputs:

name: mattermost-send-message
description: Send a message to a user or channel
handler: message.php
interpreter: php
input:
  type: object
  required: [ url, channel, text ]
  additionalProperties: false
  properties:
    url:
      type: string
      description: Webhook URL
    channel:
      type: string
      description: Channel URI or @username. May contain multiple as csv
    text:
      type: string
      description: Message text to send

Exo outputs are optional and defined in the same YAML file. The exo action does not include an output.

Understanding variables

Looking at the input values within the Heads up Fonzie task, values such as ${member.user.username} and {{MATTERMOST_URL}} are entered. Without going too deep, these are variables. A variable is like a jar that holds a value, and you can name the jar itself (like cookie jar or marble jar) and change its contents like adding or removing different cookies or marbles.

As the scope of this guide is to understand and make basic modifications to existing processes, we won’t go much further other than to say that ${member.user.username} temporarily stores the identifier of the team member to receive the Fonzie reminder and {{MATTERMOST_URL}} contains the URL for LinkORB’s Mattermost instance.

Modifying and deploying a process

After downloading and understanding the contents of a BPMN (Business Process Model and Notation) file, let’s discuss how to modify and deploy a process.

For this step, let’s return to Team HQ and select Processes from the main top navigation. Now download the process called Learning Camunda and open it in the desktop modeler.

Inspecting the Send myself a Mattermost message task properties, again we see inputs for channel, text, and url. In this task, the input accepts a value of @[username]. To modify the process, change the username to your own, such as @msmith or @jjones.

After adding your own username, save the file and click the rocket icon in the bottom menu to deploy the current diagram.

Running your modified process

Once deployed, return to Team HQ Processes list. Going to the Learning Camunda process, you should see a new version has been recently uploaded.

Select Start and on the next page click Start Process Instance.

If everything has gone correctly, you should get a message in Mattermost from Fonzie within a few seconds!

Thanks for reading. Hopefully, you now feel ready to take the next step with Camunda! If so, bookmark the official Camunda 7 docs.