Camunda

Contents

Get started with Camunda

This tutorial guides you through modeling and implementing your first workflow with the Camunda BPM Platform. In this guide, you’ll choose between implementing executable processes in Java or JavaScript (NodeJS) using one of Camunda’s ready-to-go task clients.

Join in: Get the Sources for this guide

In addition to this guide, the source code of the example project is also available on GitHub. You can directly download the whole project or clone it with git:

git clone https://github.com/camunda/camunda-get-started-quickstart.git

To follow this guide, download the initial state or checkout the tag in the git repositiory:

git checkout -f Start

or every step in between:

git checkout -f Step-X

After every section in this guide you will find a box which contains a download link to the current state of the project and git instructions to checkout the current version of the repository.

You will be guided through the following steps:

Download and Installation

Install the Camunda BPM Platform and Camunda Modeler on your machine.

https://camunda.com/download/

Executable Process

Learn the basics of handling the Camunda Modeler, learn how to model and configure a fully executable process and learn how to integrate your own business logic.

Deploy the Process

Deploy the Process to Camunda and start your first process instances.

Involve Humans

Learn the basics of integrating user tasks into a Process and how to build forms with Camunda.

Make It Dynamic

Learn how to make your Process more dynamic by adding Gateways to the Process.

Decision Automation

Learn how to integrate DMN decision tables in the Process.


Plugins/Installation on IntellJ***

  • Download Camunda Modeler at first, and then go to IntellJ IDEA
  • IntelliJ IDEA -> Preferences -> Tools -> External Tools
  • + (Add new)
  • From Tool Settings, show your camunda modeler download path
    • Program: (CamundaModeler download path)
    • Arguments: $FilePath$
    • Working Directory: just show your working space

OK..

Offical manual : https://docs.camunda.org/manual/7.8/


Get started with Camunda

This tutorial guides you through modeling and implementing your first workflow with the Camunda BPM Platform. In this guide, you’ll choose between implementing executable processes in Java or JavaScript (NodeJS) using one of Camunda’s ready-to-go task clients.

Download and Installation.

First, you need to install the Camunda BPM Platform and the Camunda Modeler.

In the following section, we’ll describe how to install the Camunda BPM Platform locally on your machine.

Hint:If you prefer, you can also run the Camunda BPM Platform with Docker:

docker pull camunda/camunda-bpm-platform:latest
docker run -d --name camunda -p 8080:8080 camunda/camunda-bpm-platform:latest

Afterwards, you can install the Camunda Modeler.

Prerequisites

Please make sure you have the following installed:

  • Java Runtime Environment 1.7+

You can verify this by using your terminal, shell, or command line:

java -version

If you need to install Java Runtime Environment, you can find the download from Oracle here.

Camunda BPM Platform

First, download a distribution of the Camunda BPM platform. You can choose from different distributions for various application servers. In this tutorial, we’ll use the Apache Tomcat-based distribution. Download it from the download page.

After downloading the distribution, unpack it inside a directory of your choice.

After you’ve successfully unpacked your distribution of the Camunda BPM platform, execute the script named start-camunda.bat (for Windows users) or start-camunda.sh (for Unix users).

This script will start the application server and open a welcome screen in your web browser. If the page does not open on its own, go to http://localhost:8080/camunda-welcome/index.html.

Camunda Modeler

Download the Camunda Modeler from the download page.

After downloading the Modeler, simply unzip the download in a folder of your choice.

After you have successfully unpacked the zip, run camunda-modeler.exe (for Windows users), camunda-modeler.app (for Mac users), or camunda-modeler.sh (for Linux users).

Once you’ve installed the Camunda Platform and the Camunda Modeler, you can move to the next step to model and execute your first process.

Executing automated steps

In this section, you’ll learn how to create your first BPMN 2.0 process with the Camunda Modeler and how to execute automated steps. Start by opening up Camunda Modeler.

Create a new BPMN Diagram

Create a new BPMN diagram by clicking File > New File > BPMN Diagram.

modeler-new-bpmn-diagram.png

Start with a Simple Process

Start by modeling a simple process.

modeler-step1.png

Double-click on the Start Event. A text box will open. Name the Start Event “Payment Retrieval Requested”.

Hint: When editing Labels, you can add line breaks using Shift + Enter.

Click on the start event. From its context menu, select the activity shape (rectangle). It will be placed automatically on the canvas, and you can drag it to your preferred position. Name it Charge Credit Card. Change the activity type to Service Task by clicking on the activity shape and using the wrench button.

modeler-step2.png

Add an End Event named Payment Received.

modeler-step3.png

Configure the Service Task

There are different ways to execute service tasks using Camunda BPM. In this guide, we’ll use the external task pattern. Open the Properties Panel within the Camunda Modeler and click on the Service Task you just created. Change the Implementation to External and use charge-card as the Topic.

modeler-step4.png

Configure Properties for Execution

modeler-step5.png

Because we’re modeling an executable process, we should give it an ID and set the isExecutable property to true. On the right-hand side of the canvas, you find the properties panel. When you click on empty space on the modeling canvas, the properties panel will display the properties of the process itself.

First, configure an ID for the process. Type payment-retrieval in the property field Id. The property ID is used by the process engine as an identifier for the executable process, and it’s best practice to set it to a human-readable name.

Second, configure the Name of the process. Type Payment Retrieval in the property field Name.

Finally, check the box next to the Executable property. If you don’t check this box, the process definition is ignored by the process engine.

Save the BPMN Diagram

modeler-save-diagram.png

When you’re done, save your changes by clicking File > Save File As.. or by using the Save Button. In the dialogue that appears, navigate to a folder of your choice and save the diagram as something like payment.bpmn.

Catch up: Get the Sources of Step-1.

https://github.com/camunda/camunda-get-started-quickstart


Implement an external task worker

After modeling the process, we want to execute some business logic.

Camunda BPM is built so that your business logic can be implemented in different languages. You have the choice which language suits your project best.

In this quick start, we’ll show you how to use Camunda’s ready-to-go task clients in:

  • Java
  • JavaScript (NodeJS)

If you’ve never worked with Java before, we recommend using the JavaScript (NodeJS) task client in this tutorial.

Hint : If you prefer a different programming language, you can also use Camunda’s REST API to access API operations via HTTP.

a) Using Java

In this section, you’ll learn how to implement an external task worker in Java.

Prerequisites

Make sure you have the following tools installed:

  • JDK 1.8
  • An IDE for Java projects (e.g. Eclipse)
Create a new Maven project

Start by creating a new Maven project in your IDE. If you’re using Eclipse, you can follow these steps:

In Eclipse, go to File / New / Other …. This opens the New Project Wizard. In the New Project Wizard, select Maven / Maven Project. Click Next.

On the first page of the New Maven Project Wizard, select Create a simple project (you can skip archetype selection). Click Next.

On the second page (see screenshot), configure the Maven coordinates for the project. Since we are setting up a JAR Project, make sure to select Packaging: jar.

eclipse-new-project.png

When you’re done, click Finish. Eclipse will set up a new Maven project. The project appears in the Project Explorer View.

Add Camunda External Task Client Dependency

The next step consists of setting up the Maven dependency to the external task client for your new process application. Your pom.xml file of your project should look like this:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>org.camunda.bpm.getstarted</groupId>
	<artifactId>charge-card-worker</artifactId>
	<version>0.0.1-SNAPSHOT</version>

	<dependencies>
		<dependency>
			<groupId>org.camunda.bpm</groupId>
			<artifactId>camunda-external-task-client</artifactId>
			<version>1.0.0</version>
		</dependency>
	</dependencies>
</project>
Add the Java class

Next, we will create a new ExternalTaskClient which subscribes to the charge-card topic.

When the process engine encounters a service task that is configured to be externally handled, it creates an external task instance on which our handler will react. We are using Long Polling in the ExternalTaskClient to make the communication more efficient.

Next, you need to create a package, e.g., org.camunda.bpm.getstarted.chargecard and add a Java class, e.g. ChargeCardWorker, to it.

package org.camunda.bpm.getstarted.chargecard;

import java.util.logging.Logger;

import org.camunda.bpm.client.ExternalTaskClient;

public class ChargeCardWorker {
  private final static Logger LOGGER = Logger.getLogger(ChargeCardWorker.class.getName());

  public static void main(String[] args) {
    ExternalTaskClient client = ExternalTaskClient.create()
        .baseUrl("http://localhost:8080/engine-rest")
        .build();

    // subscribe to an external task topic as specified in the process
    client.subscribe("charge-card")
        .lockDuration(1000) // the default lock duration is 20 seconds, but you can override this
        .handler((externalTask, externalTaskService) -> {
          // Put your business logic here

          // Get a process variable
          String item = (String) externalTask.getVariable("item");
          Long amount = (Long) externalTask.getVariable("amount");
          LOGGER.info("Charging credit card with an amount of '" + amount + "'€ for the item '" + item + "'...");

          // Complete the task
          externalTaskService.complete(externalTask);
        })
        .open();
  }
}
Run the worker

You can run the Java application by right clicking on the class ChargeCardWorker and choosing Run as Java.

Note that the worker should remain running throughout the entirety of this quick start guide.

source : https://github.com/camunda/camunda-get-started-quickstart

b) Using JavaScript (NodeJS)

In this section, you’ll learn how to implement an external task worker in NodeJS.

Prerequisites

Make sure you have the following tools installed:

  • NodeJS >= v8.9.4 (Download available here)
  • Editor for JavaScript files (e.g. Atom)
Create a new NodeJS project
mkdir charge-card-worker
cd ./charge-card-worker
npm init charge-card-worker -y
Add Camunda External Task Client JS library
npm install -s camunda-external-task-client-js
Implement the NodeJS script

Next, we’ll create a new ExternalTaskClient that subscribes to the charge-card topic.

When the process engine encounters a service task that’s configured to be externally handled, it creates an external task instance on which our handler will react. We use Long Polling in the ExternalTaskClient to make the communication more efficient.

Next, you need to create a new JavaScript file, e.g. worker.js, that looks like the following:

const { Client, logger } = require('camunda-external-task-client-js');

// configuration for the Client:
//  - 'baseUrl': url to the Process Engine
//  - 'logger': utility to automatically log important events
const config = { baseUrl: 'http://localhost:8080/engine-rest', use: logger };

// create a Client instance with custom configuration
const client = new Client(config);

// susbscribe to the topic: 'charge-card'
client.subscribe('charge-card', async function({ task, taskService }) {
  // Put your business logic here

  // Get a process variable
  const amount = task.variables.get('amount');
  const item = task.variables.get('item');

  console.log(`Charging credit card with an amount of ${amount}€ for the item '${item}'...`);

  // Complete the task
  await taskService.complete(task);
});
Run the NodeJS script

You can run the NodeJS script with:

node ./worker.js

Note that the worker should remain running throughout the entirety of this quick start guide.

source : https://github.com/camunda/camunda-get-started-quickstart


Deploy the Process

In the next step, you’ll deploy the Process and start a new instance so you can see that your simple process is working correctly.

Use the Camunda Modeler to Deploy the Process

In order to deploy the Process, click on the deploy button in the Camunda Modeler, then give it the Deployment Name “Payment Retrieval” and click the Deploy button.

modeler-deploy1.png

modeler-deploy2.png

You should see a success message in the Camunda Modeler:

modeler-deploy3.png

Verify the Deployment with Cockpit

Next, use Cockpit to see if the process was successfully deployed. Go to http://localhost:8080/camunda/app/cockpit and log in with the credentials demo / demo. Your process Payment Retrieval should be visible on the dashboard.

cockpit-payment-retrieval.png

Start a Process Instance

In Camunda, there are different ways to start a new process instance. You can leverage the Camunda REST API to start a new process instance by sending a POST Request.

a) curl

curl -H "Content-Type: application/json" -X POST -d '{"variables": {"amount": {"value":555,"type":"long"}, "item": {"value":"item-xyz"} } }' http://localhost:8080/engine-rest/process-definition/key/payment-retrieval/start


In your worker, you should now see the output in your console. This means you have successfully started and executed your first simple process.

b) REST Client

If you don’t feel comfortable using curl for the REST request, you can instead make use of any REST client.

Make a POST request to the following endpoint: http://localhost:8080/engine-rest/process-definition/key/payment-retrieval/start

The JSON Body should look like this:

{
	"variables": {
		"amount": {
			"value":555,
			"type":"long"
		},
		"item": {
			"value": "item-xyz"
		}
	}
}

Hint: Make sure you are setting the headers correctly to Content-Type: application/json

Here’s what the request might look like in Postman:

postman-start-instance.png

In your worker console (which we started in the previous section), you should now see an output. This means you have successfully started and executed your first simple process.

Hint : If you are running on Camunda Enterprise Edition, you can also check out your completed process instance in the Camunda Cockpit.


Add a User Task to the Process

In this section, you’ll learn how to involve humans in your process by using BPMN 2.0 User Tasks.

Add a User Task

We want to modify our process so that we can involve humans.

To do so, open the process in the Camunda Modeler.

Next, from the Modeler’s left-hand menu, select the activity shape (rectangle) and drag it into position between the Start Event and the “Charge Credit Card” Service Task. Name it Approve Payment.

modeler-usertask1.png

Change the activity type to User Task by clicking on it and using the wrench button menu.

modeler-usertask2.png

Configure a User Task

Next, open the properties view. If the properties view is not already visible, click on the “Properties Panel” label on the right-hand side of the Modeler canvas.

Select the User Task on the canvas. This will update the selection in the properties view. Scroll to the property named Assignee. Type demo.

modeler-usertask3.png


Configure a basic form in the User Task

This step will also take place in the properties panel. If the panel is not already visible, click on the “Properties Panel” label on the right-hand side of the Modeler canvas.

Select the User Task on the canvas. This will update the selection in the properties view.

Click on the Tab Forms in the properties panel.

Add three form fields by clicking on the plus button:

modeler-usertask-add.png

Field 1:

  • ID: amount
  • Type: long
  • Label: Amount

modeler-usertask4.png

Field 2:

  • ID: item
  • Type: string
  • Label: Item

modeler-usertask5.png

Field 3:

  • ID: approved
  • Type: boolean
  • Label: Approved?

modeler-usertask6.png

Deploy the Process

Use the Deploy Button in the Camunda Modeler to deploy the updated process to Camunda.

Work on the Task

Go to Tasklist (http://localhost:8080/camunda/app/tasklist) and log in with the credentials “demo / demo”. Click on the button to start a process instance. This opens a dialog where you can select Payment Retrieval from the list. Now you can set variables for the process instance using a generic form.

start-form-generic.png

The generic form can be used whenever you have not added a dedicated form for a User Task or a Start Event. Click on the Add a variable button to create a new row. Fill in the form as shown in the screenshot. When you’re done, click Start.

You should now see the Approve Payment task in your Tasklist. Select the task and click on the Diagram tab. This displays the process diagram highlighting the User Task that’s waiting to be worked on.

diagram.png

To work on the task, select the Form tab. Because we defined the variables in the Form Tab in the Camunda Modeler, the Tasklist has automatically generated form fields for us.

task-form-generated.png

source : https://github.com/camunda/camunda-get-started-quickstart

Add Gateways to the Process

In this section, you’ll learn how to make your process more dynamic by using BPMN 2.0 Exclusive Gateways.

Add Two Gateways

We want to modify our process so that it’s more dynamic.

To do so, open the process in the Camunda Modeler.

Next, from the Modeler’s left-hand menu, select the gateway shape (diamond) and drag it into position between between the Start Event and the Service Task. Move the User Task down and add another Gateway after it. Lastly, adjust the Sequence Flows so that the model looks like this:

modeler-gateway1.png

Now also name the new elements accordingly:

modeler-gateway2.png

Configure the Gateways

Next, open the properties panel and select the <1000 € Sequence Flow after the Gateway on the canvas. This will update the selection in the properties panel. Scroll to the property named Condition Type and change it to Expression. Then input ${amount<1000} as the Expression. We are using the Java Unified Expression Language to evaluate the Gateway.

modeler-gateway3.png

Next, change the Expressions for the other Sequence Flows, too.

For the >=1000 € Sequence Flow, use the Expression ${amount>=1000}:

modeler-gateway4.png

For the Yes Sequence Flow, use the Expression ${approved}:

modeler-gateway5.png

For the No Sequence Flow, use the Expression ${!approved}:

modeler-gateway6.png

Deploy the Process

Use the Deploy Button in the Camunda Modeler to deploy the updated process to Camunda.

Work on the Task

Go to Tasklist (http://localhost:8080/camunda/app/tasklist) and log in with the credentials “demo / demo”. Click on the button to start a process instance for the Payment Retrieval Process. Next, set variables for the process instance using the generic form as we learned in the User Tasks section.

start-form-generic.png

Fill in the form as shown in the screenshot and make sure you use an amount that is larger or equal to 1000 in order to see the User Task Approve Payment. When you are done, click Start.

You should see the Approve Payment task when you click on All Tasks. In this quick start, we’re logged into Tasklist as an admin user, and so we can see all tasks associated with our processes. However, it’s possible to create filters in Tasklist to determine which users can see which tasks based on user authorization as well as other criteria.

To work on the task, select the Form tab and check the approved checkbox so that our payment retrieval gets approved. We should see that our worker prints something to the console.

Next, repeat the same steps, and this time, reject the payment. You should also create one instance with an amount less than 1000 to confirm that the first gateway works correctly.

Source: https://github.com/camunda/camunda-get-started-quickstart


Leverage business rules

In this section, you’ll learn how to add decision automation to your process by using BPMN 2.0 Business Rule Tasks and DMN 1.1 Decision Tables.

Add a Business Rule Task to the Process

Use the Camunda Modeler to open the Payment Retrieval process then click on the Approve Payment Task. Change the activity type to Business Rule Task in the wrench button menu.

modeler-businessrule-task1.png

Next, link the Business Rule Task to a DMN table by changing Implementation to DMN and Decision Ref to approve-payment in the properties panel. In order to retrieve the result of the evaluation and save it automatically as a process instance variable in our process, we also need to change the Result Variable to approved and use singleEntry as the Map Decision Result in the properties panel.

modeler-businessrule-task2.png

Save your changes and deploy the updated process using the Deploy Button in the Camunda Modeler.

Create a DMN table using the Camunda Modeler

Create a new DMN table by clicking File > New File > DMN Table.

modeler-new-dmn-table.png

Specify the DMN table

First, give the DMN table the name Approve Payment and the ID approve-payment. The DMN table ID must match the Decision Ref in your BPMN process.

modeler-dmn1.png

Next, specify the input expressions for the DMN table. In this example, we’ll decide whether a payment is approved based on the item name. Your rules can also make use of the FEEL Expression Language, JUEL or Script. If you like, you can read more about Expressions in the DMN Engine.

For the input column, use item as the Input Expression and Item as the Input Label:

modeler-dmn2.png

Next, set up the output column. Use approved as the Output Name and Approved as the Output Label for the output column “Approved”:

modeler-dmn3.png

Let’s create some rules by clicking on the plus icon on the left side of the DMN table. We should also change the Output Column to the Data Type boolean:

modeler-dmn4.png

After setup, your DMN table should look like this:

modeler-dmn5.png

Deploy the DMN table

To deploy the Decision Table, click on the Deploy button in the Camunda Modeler, give it Deployment Name “Payment Retrieval Decision”, then hit the Deploy button.

modeler-dmn6.png

Verify the Deployment with Cockpit

Now, use Cockpit to see if the decision table was successfully deployed. Go to http://localhost:8080/camunda/app/cockpit. Log in with the credentials demo / demo. Navigate to the “Decisions” section. Your decision table Approve Payment should be listed as deployed decision definition.


cockpit-approve-payment.png

Inspect using Cockpit and Tasklist

Next, use Tasklist to start two new Process Instances and verify that depending on your input, the Process Instance will be routed differently. To do so, go to http://localhost:8080/camunda/app/tasklist. Log in with demo / demo.

Click on the button to start a process instance and choose the Payment process. Use the generic form to add the variables as follows:

tasklist-dmn1.png

Hit the Start Instance button.

Next, click again on the Start process button to start another process instance and choose the Payment process. Use the generic form to add the variables as follows:

tasklist-dmn2.png


You’ll see that depending on the input, the worker will either charge or not charge the credit card. You can also verify that the DMN tables were evaluated by using Camunda Cockpit. Go to http://localhost:8080/camunda/app/cockpit. Log in with the credentials demo / demo. Navigate to the “Decisions” section and click on Approve Payment. Check the different Decision Instances that were evaluated by clicking on the ID in the table.

A single DMN table that was executed could look like this in Camunda Cockpit:

cockpit-dmn-table.png


Success!

Congratulations! You’ve successfully completed the Camunda BPM Quick Start. Ready to continue? We recommend the Camunda BPM documentation.