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:
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.
Click on Add Deployment Unit. In the next UI enter the Maven GAV and the Alias for your Depoyment Unit:
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
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”:
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 "{}"
1
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:
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:
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:
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.
