Join our largest event of the year | CamundaCon 2022 October 5-6

Icon Close
Register

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

  • Increase your resilience with new regions in...

    We’re excited to announce new regions for Camunda Platform 8 SaaS that further strengthen the resilience, performance, and data requirements for our SaaS customers. Enterprise customers can now choose to create their clusters in a number of regions including Europe West, US Central, US East, and the most recent addition, Australia South East. This provides multiple benefits, such as increasing availability, allowing to set up fail-safes, adhering to regulatory requirements for regional data storage, and reduced latency due to closer physical proximity. Resilience and redundancy in technology are important for all modern organizations and are top of mind for many. Across industries, organizations need a solution that scales effectively and is resilient to provide a good base for process orchestration....

    Read more
  • Black title slide that reads, "The CAM project in JIRA is moving to GitHub"

    The CAM project in JIRA is moving...

    For almost 10 years, JIRA has been our development issue tracker for the core components of Camunda Platform 7. About 15,000 tickets later, Camunda’s engineering has grown from one team to a team of teams. Many new projects have used GitHub exclusively as a code repository and an issue tracker from the start. In October, we will move the CAM project to GitHub issues. With this change we are reducing the gap: our community can participate in our development processes with a single account. We achieve a unified approach for managing development issues, making it easier for everyone to participate. We thank everyone who has contributed to our CAM issue tracker and hope that the collaboration continues in our new...

    Read more
  • Title slide that reads "Camunda Automation Platform 7.18.0-alpha5 Released"

    Camunda Automation Platform 7.18.0-alpha5 Released

    We are pleased to announce the next alpha release of Camunda Platform Runtime 7.18. This release features the following improvements: Logging: Engine name parameter in mapped diagnostic context Exception Error Codes now available in the External Task Clients IBM WebSphere Application Server Liberty support New Supported Environments 7 Bug Fixes You can download Camunda for free or run it with Docker. For a complete list of all improvements, take a look at the release notes. Please also see the list of known issues. If you want to dig in deeper, you can find the source code on GitHub. Logging: Engine Name Parameter in Mapped Diagnostic Context As an addition to the already present list of parameters for the logging context,...

    Read more

Ready to get started?

Still have questions?