Start and Step Through a Process with REST (feat. SwaggerUI)

*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.


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. 

Camunda, Swagger, and REST API
Example Process

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.

Process in Camunda Cockpit

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.

Labeled Process in Camunda Cockpit

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: 

Camunda Platform REST API settings

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.

Start Instance in the Process Definition section

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.

Responses with arrows pointing to ID and response code

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.

find user task Camunda REST API

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. 

Responses with arrow pointing to ID

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. 

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. 

Responses with arrow pointing to 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

Labeled Process in Camunda Cockpit

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