Process automation with Camunda using dotnet6
This article explains how to use Camunda for process or workflow automation using a simple BPMN process with a sample .net application(code repo).
What is Camunda?
Camunda is a Java-based framework for business workflow and process automation. It’s core is a native BPMN 2.0 process engine that runs inside the JVM. It can be embedded inside any Java application or any Runtime Container.
A lot of jargons in above mentioned paragraph. Let’s break it down one by one. The very first is workflow. As per Wikipedia:
A workflow consists of an orchestrated and repeatable pattern of activity, enabled by the systematic organization of resources into processes that transform materials, provide services, or process information.
In simple terms, If you have a set of activities which follow a certain predefined flow and are repeatable, you can define it as a workflow.
Process refers to a business process. It is a series of actions or operations with the purpose of achieving an organizational goal. As per definitions both sounds similar.
But the difference lies in their purpose, Workflow focuses on completing a particular task. Process focuses on achieving a business goal. For example when a customer visits a restaurant and orders tea, serving the customer is a business process and preparing tea, generating bill, receiving payment can be workflows of it.
BPMN(Business Process Model and Notation) is a graphical representation for specifying business processes and workflows. BPMN simplify defining and creating complex business processes and workflows in a very much understandable pictorial view. Please check a simple BPMN diagram in below picture.
Prerequisites
- Camunda(Open Source Community Edition): There are many ways you can install and use Camunda platform. You can find the detailed explanation here. The sample app use in this article uses the docker way. To run it as docker instance check the script ‘start-camunda.ps1’ mentioned here. After running it you can access the Camunda web app at ‘http://localhost:6060/camunda/app/welcome/default’. Use ‘demo/demo’ to login. Click on Cockpit and you will see the dashboard(with 2 pre-deployed processes).
Simple Demo App : Prepare Tea Process
To demonstrate the Camunda’s capabilities, I have created a very simple sample app. I have defined here a process of preparing tea which consists of 3 simple steps of boiling the water, adding tea leaves and finally strain and serve. You can find the BPMN diagram(Prepare Tea.bpmn) here.
- To start with the very first step is to draw the BPMN diagram. You can open the Camunda Modeler and create a new file(name it properly- *.bpmn). You can follow the diagram provided in sample code repo. Find the detailed instructions to create BPMN diagram here.
- The important part to note in the diagram are shown below: Process Id(defined here as Process_Prepare_Tea) is key which will be used to start the process. Process Name(defined here as Prepare Tea Process) will be shown in Camunda web app. Executable check mark is very important. It marks the process as executable and hence the process engine will execute it when requested.
- You can see 3 rectangular boxes, one for each task. These are service tasks. If you select any one of them, in right pane you will find few important details. Name is what is shown in diagram for understanding. Next is Implementation which is a dropdown with many options like Java, Expression, External etc. For sample app, I have used External because I am using a dotnet based worker to cater to these tasks. And hence it has asked for another input Topic(defined as Boil_Water). This topic helps external worker(in our case dotnet app) to identify which task has been called/executed. You can check the image below:
- Similar definitions are there for other 2 tasks also. You can change the type of service tasks also abut then these values will also be changed. For this demo, we will stick to service task only.
- Now once the diagram is ready, you need to deploy it to Camunda engine. You can use rest api to deploy. To make things simpler, Modeler too have an option to deploy. Click on upload button on the left bottom of Modeler. It will pop up the deployment widget. Provide a proper deployment name and rest endpoint and click deploy. Check the image below.
- Now if you go to Camunda web app and select the ‘Processes’ from the tabs(present at top), you will find an entry for ‘Prepare Tea Process’. Click on the process and you will see the entry similar to below image:
Dotnet app [Worker & Rest implementation]
In this demo app, I have showcased 2 use cases:
- Worker: These are worker handlers which performs the task’s operations when Camunda engine calls it based on defined BPMN process. For this app, I have used the NuGet package ‘Camunda.Worker’.
- Rest Implementation: Camunda is Java based but it has a rest-engine which can be used by any language. All the operations of Camunda like starting the process, deploying etc can be performed using rest call. For this app, I have used the NuGet package ‘Camunda.Api.Client’ which provides Camunda REST API Client for .NET platform. In the demo app, we will start the process using this library.
- I have created a .net 6 based web api in which I have added a folder ‘Camunda.Worker.Handlers’ which consists of all the handler implementations.
If you watch closely, you will find out that it has a handler for each of the tasks defined in our earlier mentioned BPMN diagram. I will discuss about one of the handler and you will find the similar implementation in other handlers too.
- To define any worker handler, implement IExternalTaskHandler to the defined class. This interface has one method called HandleAsync where you can provide the implementation. Then there are two important attributes. First one is HandlerTopics; which matches the topic defined in BPMN and denotes which task from BPMN process will be catered by this worker handler. Second one is HandlerVariables which makes process variables(defined while starting/executing the process) available to handler. You can find the code here. See the image below:
- Once you have created the handlers, you need to notify Camunda that these are the handlers who will listen to the defined topics and perform the specific tasks. For that purpose you need to do some configuration at startup. Please check the code below which needs to be added in Programm.cs.
//Camunda worker startUp
builder.Services.AddExternalTaskClient()
.ConfigureHttpClient((provider, client) =>
{
client.BaseAddress = new Uri("http://127.0.0.1:6060/engine-rest");
});builder.Services.AddCamundaWorker("PrepareTeaCamundaWorker", 1)
.AddHandler<BoilWaterHandler>()
.AddHandler<AddTeaLeavesHandler>()
.AddHandler<StrainAndServeHandler>();
//
- Now to start the process, I have exposed one api endpoint. Using Camunda client, this starts the process(specified by id: Process_Prepare_Tea) and returns the processId. You can find the code here. See the image below:
- Make sure that the Camunda is running and process file is deployed correctly.
- Then run your dotnet application. On swagger page you will find a get endpoint startProcess. You can use postman also to call this endpoint.
- You will find the output similar to shown in below image. You can see there is a a small icon is there on ‘Add Tea Leaves’ process. This was when AddTeaLeavesHandler was called, but by the time I took the screenshot the next handler also got executed. That says the process got executed successfully. If I would have taken a screenshot after that, there would be no icon on the BPMN process diagram inside Camunda webapp.
This was a sample use case showing how to start working with Camunda. Hope this article has helped you understand the basics of Camunda. To know further about Camunda please check the second part here.
For further reading you can check out Camunda docs or this link.
Please do checkout other articles by me and share your feedback(s) if any. Thank you.
