How to deploy a BPMN, start and complete a transaction with Camunda REST
In this blog, we are going to talk about how to start a task from your workflow and complete it using camunda REST. Before I explain the main topic you need to have a REST client like “Postman” or google chrome’s advanced rest client, installed camunda cockpit and, of course, you need to have a basic knowledge of workflows and camunda.
In this blog, you will,
- Deploy a BPMN file
- Start the workflow in your BPMN file
- Complete the task
- Learn how to handle Exclusive gateways in your process
For this blog, I’m going to use a BPM that I created for this blog and down below you can see the image of that diagram. If you want you can create the same diagram and try out while reading the blog. (To create a bpmn diagram you can use the camunda modeler)
Start the camunda server
Before we deploy out BPMN file, you need to start the camunda server. If you have downloaded the camunda server, you can simply start it by running start-camunda.sh file (for ubuntu users) or start-camunda.bat (for windows users). After you successfully start the camunda, your browser will open a new window with “http://localhost:8080/camunda/app/welcome/default/#!/welcome” link and display below message in your terminal.
You can find out more about this in my previous blog.
Deploy your BPMN file
Now that we have started the camunda server, we can deploy out BPMN file to our server. For all the REST calls I use my personal favorite REST client postman. Deployment of your file is done by using below API.
POST /deployment/create
Since this is a POST call, your POST method body should be form-data and inside the form-data, you should have a key name of “upload” that accepts a file as value and for the value, you should provide your BPMN file.
As you can see in the image, you should use below API with above POST data to successfully deploy the BPMN file.
http://localhost:8080/engine-rest/deployment/create
When you send the API call, you should receive a response like below with a status of 200 OK.
If you get that means your deployment was successful. Then log in to your cockpit with “demo” as username and password and navigate to the deployments tab. Your deployment tab should look like below.
And on the top of the deployed list, your deployed BPMN should be there. When you click the deployed BPMN, you can see your deployed file name in the middle tab and once you click that name on the left tab your process should be displayed like below.
Now that we have successfully deployed a BPMN, we can start the workflow using the Camunda REST.
Start the task
When you deploy the bpmn file, in your response under the “deployedProcessDefinitions” json, you will get a key value pair that include your process definition key.
You need that key to start your BPMN.
POST
/process-definition/{id}/startPOST
/process-definition/key/{key}/start(starts the latest version of the process definition which belongs to no tenant)POST
/process-definition/key/{key}/tenant-id/{tenant-id}/start(starts the latest version of the process definition for tenant)
Using the above API you can start your workflow. For this POST method, your content type should be “application/json” and POST body should be empty json (“{}”). We are using the second POST method from the above list to start the workflow.
When you start the workflow successfully, you should get a response like in the above image. It has the started process instance's id as id in the response.
Then you can get the current task of the created instance by below API. (Get method with query processInstanceId as a query parameter).
http://localhost:8080/engine-rest/task?processInstanceId=your-instance-id
When you call this api, your response will look like below.
Here you can see the current task name as “Check weather” and its id and several data are listed in the response. After that if we navigate to camunda cockpit and select our deployment, we can see that there is one instance in front of our BPMN.
When you click the BPMN name again, you can see the current task with a blue label like below in the diagram.
Now you can simply complete the task by calling the complete task API.
Complete task
POST /task/{id}/complete
You need to provide the id you received from above get task response and provide it for the id request parameter. In out case it should look like below API.
http://localhost:8080/engine-rest/task/yout-task-id/complete
But in my BPMN you can see there is an Exclusive gateway after the task. If you dont have an Exclusive gateway after the current task then you can call the POST request for task completion and finish it.
But if you have one, then you have to provide the suitable expression that moves forward the task.
As you can see in my diagram, if my variable isSunnyDay is true, then only the task will complete and move to the next task. If that variable is false, the task will complete and as in the diagram, the workflow will stop.
In the task completion API, you can provide the variable in POST metohod body like below.
The format of the body should not be changed. Otherwise, it gives you an error. When you call the task complete API with relevant POST body, you will get an empty response from camunda server with 204 status code.
That means our task completion was successful and you can check it by navigating to your camunda cockpit.
Cheers! now you know how to deploy a workflow, start a workflow and complete a workflow like a boss. I will list down some userfull link that you may find interesting when you read this blog.
Camunda REST API Docs — https://docs.camunda.org/manual/7.12/reference/rest/
Camunda REST for Deployment — https://docs.camunda.org/manual/7.12/reference/rest/deployment/
Camunda REST for ProcessDefinition — https://docs.camunda.org/manual/7.12/reference/rest/process-definition/
Camunda REST for tasks — https://docs.camunda.org/manual/7.12/reference/rest/task/
