Wondering how you can use the Camunda 8 REST API to start a process? Check out this detailed example and learn how to start a process via the Camunda REST API using the latest Connectors.
Starting a process
To start a deployed process in Camunda Platform 8 you can click some buttons in the user interface on either the Camunda Web Modeler or from Tasklist, or you can do it programmatically using Zeebe’s gRPC API. These options have been around for a while however, and with the recent addition of webhooks to Camunda Platform 8, you’ll now be able to generate an endpoint that, when called, will start a process for you.
Inbound Connectors: Webhooks
Camunda 8 has had Connectors for about a year now. They do things like make REST calls, produce messages for Kafka, send emails through SendGrid and lots more, all without requiring you to code anything. What all of these Connectors have in common is that they’re all outbound. Meaning it’s always the process that is instructing another system to go do some stuff. The latest version of Camunda 8 has added the first inbound Connectors, giving external applications a way of telling the process to do stuff for a change and thus making for a more wholesome relationship between the process engine and external services.
The inbound Connector that’ll help us out in this situation is the Webhook Connector and it’s really easy to get started with it. Once a webhook is set up, it generates a unique URL that an external application or service can use. This URL can be called like you would a REST call in order to start a new process instance.
Creating a Webhook
For this example I decided to lean into the hook element of webhook and create a process to help us find a place to do a spot of fishing.
As you can see I want to be able to give the process the name of a fish I’m interested in catching using a REST call, then through the awesome power of DMN, I’ll get a suggested place where I could find that fish.
Once you’ve opened up the Web Modeler, start with a start event that seems appropriate. Once you have that start event you can morph it into a webhook from the context menu.
Now it’s selected, the properties panel will need some info from you, starting with the webhook properties.
As you can see I’ve given it an ID and thrown caution to the wind by disabling authentication. If you’d like to see how the authentication works, feel free to check out this page of the docs. I will not be implementing this here, I don’t feel this example really needs all that much security.
Next we have an activation condition. This isn’t required, but I feel I’d like to ensure that only a certified “Fish Person” uses this process, and so once the request comes in it must have a variable called “status” and the value must be “Fish Person”. It’s a watertight way of ensuring we offer this service to true fish people.
Next up we want to get some data from the incoming request. Specifically we’d like to get the name of the fish that the requester would like to find. We do this by parsing the request with FEEL and putting the result into a variable called fish.
You can then build the remainder of the process (or copy it from the GitHub repo) and deploy it to your Camunda 8 cluster. After a successful deployment you can get your hands on the webhook URL by clicking on the tab and copying the link there.
Before starting the process, you can check it out in Operate.
Just as with other examples making REST calls, we use Postman. To actually start it, you can use Postman to create the following call:
POST https://bru-2.connectors.camunda.io/<your-id>/inbound/FishingSpotWith a body that looks like this:
{"id": 1,
"status": "Fish Person",
"fish" : "Bass"}If you send the call you should get back a response like this:
{
"unauthorizedConnectors": [],
"unactivatedConnectors": [],
"executedConnectors": {
"FishingSpot-FishingExample-4": {
"type": "START_EVENT",
"id": "2251799814964011",
"responseData": {
"processDefinitionKey": 2251799814964011,
"bpmnProcessId": "FishingExample",
"version": 4,
"processInstanceKey": 2251799814965139
}
}
},
"errors": []
}More importantly you should then be able to see a token appear in Operate as well the data produced by the DMN table to help you find the fish you want:
In my case I’ve been informed that I can find a Bass either in a river or a supermarket, good to know!
fishingLocations : ["River","Supermarket"]What’s in the works
This is of course the first iteration, and there are two aspects of this example that are worth keeping an eye on: 1) outbound Connectors and 2) new REST API calls.
More from Outbound Connectors
For the inbound Connectors you can expect to be able to start a process using messages produced by RabbitMQ or Kafka, which is a great addition to the existing ability to send messages to both of those systems using outbound Connectors.
More from Camunda 8 REST APIs
There’s a great community project headed up by our very own Nico Korthout that aims to make available a more extensive REST API for Camunda 8. It’s still in early public beta, but it’s really worth taking a look and getting involved. You’ll find that project here. Why not give your feedback on what APIs you’d most like to see implemented.
