jBPM REST API made simple

This tutorial will discuss how to use jBPM REST API to manage your Process Server with any tool able to execute simple HTTP requests such as curl.

By using jBPM REST API you can perform the following actions:

  • Create, update, or delete Process Server instances
  • Retrieve information about Process instances, and associated KIE containers
  • Start, stop or update KIE containers associated with Process Server instances

REST API Role setting

By default, the REST API requires HTTP Basic authentication or token-based authentication for the following user roles, depending on controller type:

  • rest-all user role if you installed Business Central and you want to use the built-in jBPM controller
  • kie-server user role if you installed the headless jBPM controller separately from Business Central

As an example, we will add (or update) the kieserver user assigning both roles. From the ‘bin’ folder of jBPM run:

$ ./add-user.sh -a --user <USERNAME> --password <PASSWORD> --role kie-server,rest-all

If you prefer, you can also assign the rest-all role to your users from the Business Central.

Login to the Business Central and select Admin | Security:

kie server rest api

Deploy and Test an asset

Now, for the purpose to show how jBPM REST API works, we will deploy at first a KJAR from https://github.com/fmarchioni/mastertheboss/tree/master/jbpm/licensedemo and install it as a container.

Download the example from GitHub, then install in on your local Maven repository:

$ mvn install

Now, you can use the Business Central to deploy the artifact in a Container. You can check this tutorial to learn more about the Business Central: Getting started with jBPM Business Central

From the Business Central choose to Deploy – Administer and Provision Servers.

jbpm rest api tutorial

Click on Add Deployment Unit. In the next UI enter the Maven GAV and the Alias for your Depoyment Unit:

jbpm rest api example

Deployment will begin shortly. In the next part of this tutorial, we will learn how to invoke some actions on this process using the REST API.

Using the Swagger Interface to execute REST Commands

If you want to get started quickly with jBPM REST API, we recommend using the Swagger UI which is available at: http://localhost:8080/kie-server/docs

From there, you can convenientely manage your process instances just filling in the required parameters. We will start by querying the list of Process Definitions which have been deployed on the KieServer:

Query Process Definitions

jbpm rest api tutorial

This command does not require any parameter and will result in the following output:

curl -X GET "http://localhost:8080/kie-server/services/rest/server/queries/processes/definitions?page=0&pageSize=10&sortOrder=true" -H  "accept: application/json"

  "processes": [
      "associatedEntities": null,
      "serviceTasks": null,
      "processVariables": null,
      "reusableSubProcesses": null,
      "nodes": null,
      "timers": null,
      "process-id": "com.mastertheboss.LicenseDemo",
      "process-name": "LicenseDemo",
      "process-version": "",
      "package": "defaultPackage",
      "container-id": "jbpmdemo",
      "dynamic": false

So we will run the “process-id”: “com.mastertheboss.LicenseDemo” which is into the “container-id”: “jbpmdemo“. You can think of the container-id of a deployment unit which can contain one or more processes in it.

Create a new Process

We will now start the process whose container is “jbpmdemo” and process id is “com.mastertheboss.bpmn.hello”:

jbpm rest api tutorial

curl -X POST "http://localhost:8080/kie-server/services/rest/server/containers/jbpmdemo/processes/com.mastertheboss.LicenseDemo/instances" -H  "accept: application/json" -H  "content-type: application/json" -d "{}"


The response will be the process id. In our case, the Task Element will display the following information on the console:

14:35:11,436 INFO  [stdout] (default task-41) Welcome to license check
14:35:11,438 INFO  [stdout] (default task-41) Enter you age

Returning a list of process instances in a specified KIE container.

To query the list of process instances running the the container you can use the following REST API:

jbpm rest api tutorial

In our example, this will be:

curl -X GET "http://localhost:8080/kie-server/services/rest/server/jobs/processes/instances/1?page=0&pageSize=10" -H  "accept: application/json"

  "request-info-instance": [
      "request-instance-id": 1,
      "request-status": "DONE",
      "request-business-key": "job1",
      "request-message": "Ready to execute",
      "request-retries": 2,
      "request-executions": 1,
      "request-command": "org.jbpm.executor.commands.LogCleanupCommand",
      "request-scheduled-date": {
        "java.util.Date": 1540299058209
      "request-data": null,
      "response-data": null,
      "request-errors": null,
      "request-container-id": null
      "request-instance-id": 2,
      "request-status": "DONE",
      "request-business-key": "job2",
      "request-message": "Ready to execute",
      "request-retries": 0,
      "request-executions": 0,
      "request-command": "java.lang.String",
      "request-scheduled-date": {
        "java.util.Date": 1540328449419
      "request-data": null,
      "response-data": null,
      "request-errors": null,
      "request-container-id": null

Listing work items for a specified process instance.

In order to list the work items (f.e. Human Tasks) which are active for a specified process, you can use the following API:

jbpm rest api tutorial

Here is the input and output of the REST Command:

curl -X GET "http://localhost:8080/kie-server/services/rest/server/containers/jbpmdemo/processes/instances/1/workitems" -H  "accept: application/json"
  "work-item-instance": [
      "work-item-id": 1,
      "work-item-name": "Human Task",
      "work-item-state": 0,
      "work-item-params": {
        "Locale": "en-UK",
        "TaskName": "Task Name",
        "NodeName": "CheckLicense",
        "Priority": "1",
        "Skippable": "true",
        "ActorId": "john"
      "process-instance-id": 1,
      "container-id": "jbpmdemo",
      "node-instance-id": 2,
      "node-id": 2

As you can see there’s a Human Task whose id is “2”. In the next command, we will complete the Task providing the information required.

Completing a Process

To complete our process, we will call the following REST API:

jbpm rest api tutorial

This time as parameter we will also include the “age” parameter which is Task I/O Data copied in the process variable with the same name. The XOR gateway in this process will choose the next Script Task based on the simple condition

age >= 18 Accepted
age < 18  Rejected

By setting “age” to 25 we will have:

curl -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/jbpmdemo/processes/instances/1/workitems/1/completed" -H  "accept: application/json" -H  "content-type: application/json" -d "{    \"age\": 25}"

On the console of jBPM you should be able to see:

14:39:28,228 INFO  [stdout] (default task-41) Thanks
14:39:28,230 INFO  [stdout] (default task-41) Admitted

On the other hand, by setting a different “age”:

curl -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/jbpmdemo/processes/instances/1/workitems/1/completed" -H  "accept: application/json" -H  "content-type: application/json" -d "{    \"age\": 5}"

Then your process will end in the “Rejected” Script Task:

14:44:08,509 INFO  [stdout] (default task-41) Thanks
14:44:08,511 INFO  [stdout] (default task-41) Rejected

In this tutorial we have covered how to manage a jBPM Process using its REST API. We have covered how to list process definitions, how to start a process, how to list running process and work items and finally how to complete a process, submitting the information required in its human task.