Managing Camunda Cloud in a (Nut)shell

*Camunda Platform 8, our cloud-native solution for process orchestration, launched in April 2022. Images and supporting documentation in this post may reflect an earlier version of our cloud and software solutions.

As a Linux user, the first thing you likely do when you start up your computer is check in on your shell. Using Linux without the command line is like a morning without coffee—impossible (at least for me).

Camunda Platform 8 provides a Command Line Interface (CLI) client, called zbctl, to make the interaction between your terminal and Camunda Platform 8 possible. Clearly, this isn’t just handy for terminal lovers but also for system administrators. The CLI allows you to troubleshoot and get information from your Camunda Platform 8 cluster quickly, deploy processes, and even run job workers. 

Zbctl: The CLI Client for Camunda Platform 8

The zbctl client is available through the npm package manager or by downloading the binaries from your operating system. Now, you can also install the CLI client on Linux via Snap.

Falko Menge, Camunda’s principal consultant and open standards ambassador, created and released the Snap package to the Snap Store. The Snap package makes it even easier for Linux users to interact with Camunda Platform 8. By running snap install zbctl, you’ll get the CLI client on your Linux machine, and it’ll automatically update through the software updater of your distro. You now no longer have to deal with the binaries or install code and npm yourself just to get the zbctl client. On a side note, the client is also available via homebrew formulae (this might be an option if you’re using macOS.) 

As a Camunda power user, I had the zbctl client already installed via npm. Now, switching to the Snap package means I have to be aware of which Path is executed by the bash. In the end, the functionality of both clients are the same, so there’s no need to install multiple clients. 

Connecting zbctl to your cluster

Once you have the client installed for a smoother user experience, it’s advisable to define environment variables for Camunda Platform 8 connection settings. Once you create your client Cloud credentials, you can download a text file that contains the necessary information: 

export ZEEBE_ADDRESS='[Zeebe API]'
export ZEEBE_CLIENT_ID='[Client ID]'
export ZEEBE_CLIENT_SECRET='[Client Secret]'
export ZEEBE_AUTHORIZATION_SERVER_URL='[OAuth API]'

You can then directly set your environment variables from the file in your terminal:

source CamundaCloudMgmtAPI-Client-zbctl-client.sh

With the connection variables set, you’re ready to use the CLI client to communicate and interact with your cluster. By the way, you can also use the client if you have Zeebe installed locally. By setting the -–insecure flag you can use the client for an unsecured connection. The command zbctl –help gives a good overview of the existing commands for the client. To test your Camunda Platform 8 connection and view information about your cluster, run zbctl status.

Using the zbctl client for job workers

It’s recommended to build a job worker using an API client that can be deployed and executed in a coding language of your choice. By using an API client, it’s also easier to code your service logic in one file and set the necessary job worker configurations. Nevertheless, the CLI client provides functionalities to run job workers, too. This can be useful for troubleshooting as well as testing workers and process logic. With the create command, you can create a job worker and provide the job worker’s logic with the  — handler flag: 

zbctl create worker <Type> -- handler

The handler is just executable. If you have a more complex bash command, it’s best to put them in a shell script, make the script executable, and then let the handler call the shellscript:

#!/bin/bash

# My random activity worker

activity=$(curl -s  https://www.boredapi.com/api/activity | jq '.activity' -r);
echo {\"activity\":\""$activity"\"}

The shell script above will make a REST call to an API that returns a random activity. The jq command is only used to access the information about the activity from the response JSON. The variable activity is then used in the echo command to provide an output that is formatted in a way that can be used by the zbtcl handler to complete a job with variables. After saving the shell script, make sure it is executable with the chmod command. After that, the handler can call the shell script.

zbctl create worker randomActivity --handler "./randomActivityWorker.txt"

The CLI client provides more functionality to manage jobs in your cluster. Once an instance reaches a service task, the job can be activated:

zbctl activate jobs Type

The command returns information about your current activated jobs. With the key, you can then use the client to either complete, fail, or throw a BPMN error. If you already have activated jobs, you can also access the information in Operate. From an administrator’s perspective, that can be useful if your job workers aren’t available or you need to cancel them.

For Current Camunda Platform 7 Users:
Before a job worker can start working on a task, it has to activate it first. This is, in some ways, similar to locking an external task in Camunda Platform 7. The difference is that, in Camunda Platform 7, the external task ID already exists when a process instance reaches the service task with the external task implementation. In Camunda Platform 8, the Job ID is created with the activation of the job. Once a client in Camunda Platform 8 activates jobs, it iterates through all known participations for the jobs and takes as many as the Job Worker specified with the MaxJobsToActivate Parameter. The activated jobs are returned to the client with the Job ID. 

Manage process instances with the zbctl client

Process instances are another resource the CLI client can manage. An instance can be created and canceled. Again, this can be handy from an administrator’s point of view. You can start a process instance by handing over variables too:

zbctl create instance Process_chooseActivity --variables "{\"toDo\":\"random activity\", \"weekday\":\"Monday\"}"

With the response you get the ID from the started instance:

{
  "processDefinitionKey": "2251799813755043",
  "bpmnProcessId": "Process_chooseActivity",
  "version": 3,
  "processInstanceKey": "2251799813755110"
}

In case of one or two variables, it’s okay to attach them directly to the bash command, like in the example above. If you want to handover more variables, they can be stored in a JSON file, and the file can be attached to the command:

zbctl create instance Process_chooseActivity --variables "$(<variables.json)"

Other useful commands

Further, the CLI client provides a command to send a message. This way, message events in your BPMN process can be triggered.

zbctl publish message <Message name>

From the standpoint of the software delivery process, it’s useful that the CLI client provides a command to deploy process models to your clusters. Once a process is tested, it can be deployed directly via the command line client to the cluster, which eases the software delivery process.

zbctl deploy <process Path>

Try it Out

I hope these examples have shown that it’s quite handy to manage and communicate with your Camunda Platform 8 cluster using the zbctl client. You can find the example process and shell script in this GitHub repo to try it out yourself.

The CLI client is now available via Snap. The Snap infrastructure allows you to build CLI Cloud clients for CPUs that aren’t supported yet. Suppose you have fancy hardware and you want to connect to Camunda Platform 8 via zbctl. In that case, the Snap configuration needs to be adjusted, so it takes the sources from zbtcl instead of the binaries, and runs the Go build. In addition, pull requests are welcome as well. 

Thank you to Falko for making this possible and the interaction for Linux users easier!