Note: Images and supporting documentation in this post may reflect an earlier version of our cloud and software solutions. If you’re using Camunda Platform 8, our cloud-native solution for process orchestration, this post will be more helpful.
If you’re going to be communicating with the Camunda engine from any kind of third-party system, you’re going to need to know a little bit about what Camunda’s REST API can do out of the box. The REST API itself is built on top of the engine’s own Java API – this is important to know because it means that almost anything you can do when speaking to the engine via Java, you can also do through the REST API.
The Setup
As a fun introduction, I’m simply going to discuss how you might go about using the most common REST calls in order to start and step through a process. To make things even easier, I’m going to be doing this using nothing more than our Open Source Community Edition that you can find on our download page.
Once you’ve downloaded this, and started Camunda Platform 7, you will be able to find the web apps at http://localhost:8080/ and login with demo/demo. From here, you can log into Cockpit and you’ll find we’ve supplied you with a demo process called Invoice Receipt. This is the process we’re going to be stepping through.
This process will be pretty straightforward. We’ll start a process instance, query for the waiting user task and then complete that task. Resulting in a token waiting at the Prepare Bank Transfer task.
Starting the Process
The download that you’ve got up and running also happens to have a great way to make REST calls! As part of Camunda Run distribution you can access SwaggerUI. This (if you haven’t heard about it) is a way of making REST calls to a service if provided a description of their REST API. Click here to access it on: http://localhost:8080/swaggerui
What you should see is this:
NOTE: If you don’t see it, chances are you’re using the wrong distribution or an older version of Camunda Run. Follow this link to get the right version.
From here, you can peruse the REST calls that are available to you. We’re looking to start a process instance, so head to the Process Definition section and find the start process instance post call.
The POST call we’re making to kick off the process is: /process-definition/key/{key}/start, which requires a process definition key – that’s “invoice” in this case. It also requires some variables which can be added as a JSON payload.
{
"variables": {
"amount": {
"value": 30,
"type": "Double"
},
"creditor": {
"value": "Niall",
"type": "String"
},
"invoiceCategory": {
"value": "Travel Expenses",
"type": "String"
},
"invoiceNumber": {
"value": "BER-00001",
"type": "String"
}
},
"businessKey": "Doom1",
"withVariablesInReturn": true
}Once you’ve added the requirement you can click Execute. If you’ve done everything correctly, you should get a response code of 200, which is being cleverly pointed at by the green arrow below.
The red arrow is pointing at a very important variable for us, which is the ID of the process that we’ve created. We’ll need that to continue stepping through the process. So copy it and keep it safe.
Finding a User Task
We can use the process instance ID from the previous step to find out what is going on with the process we’ve just started. Specifically finding out which user task the process is currently waiting at.
This is once again done through the SwaggerUI. Find the Task section and select the GET call /task as indicated by the friendly red arrow below.
Then, enter the process instance ID where the green arrow is indicating and click on Execute. If the call was made successfully, you’ll have a code of 200 and the response body will contain a JSON object describing the user task.
We’ve also got another very important ID as part of the response, the ID of the user task itself. Helpfully indicated above with that trusty green arrow again.
Completing a User Task
We now have the ID of the task that the process is currently waiting at, so the only thing left to do is to complete the task and have the process move on. This means scrolling down to the task/{id}/complete POST call and entering the task ID as a parameter.
But this task needs a little more than just the ID, it also needs a variable so that process knows how to progress past the gateway. So if you try to send this call without those variables, you’ll end up getting an error and the task will not complete. The variable we need to add is a boolean variable “approved” which we’ll set to true.
{
"variables": {
"approved": {
"value": true
}
},
"withVariablesInReturn": true
}After clicking Execute, you should be greeted with a response and a very happy 200 response code.
Now, you can feel free to go into Camunda Cockpit and take a look at how far your little process has come. With just three little REST calls.
In Summary
It took three different calls to step through this process, which goes as follows in the screenshot above.
Start the process:
http://localhost:8080/engine-rest/process-definition/key/{processDefinitionKey}/start
{
"variables": {
"amount": {
"value": 30,
"type": "Double"
},
"creditor": {
"value": "Niall",
"type": "String"
},
"invoiceCategory": {
"value": "Travel Expenses",
"type": "String"
},
"invoiceNumber": {
"value": "BER-00001",
"type": "String"
}
},
"businessKey": "Doom1",
"withVariablesInReturn": true
}Query for the Task:
http://localhost:8080/engine-rest/task?processInstanceId={processInstanceId}/
{}Complete the Task:
http://localhost:8080/engine-rest/task/{taskId}/complete
{
"variables": {
"approved": {
"value": true
}
},
"withVariablesInReturn": true
}So, with this powerful new understanding committed to memory, you’re likely thinking, “How can I use this knowledge in a more practical way?” If so, I suggest you check out this video tutorial on how to build a distributed system using Camunda Run. It’ll certainly supplement your understanding of how to communicate with third-party systems in a more hands-on way.
Getting Started
Getting started on Camunda is easy thanks to our robust documentation and tutorials
