Getting started with JBPM Remote Client API

In this article we will show how to create a standalone application that access jBPM to start a process and handle its tasks.

We already talked about jBPM 6 and a Web Application using it: Developing a jBPM 7 Web application example

We will now learn how to manage processes and tasks remotely using the REST API. Thanks to the jBPM 6 REST API it is possible to manage tasks, process, create process instances, and other actions using a simple API which merely requires the use of a simple HTTP client library. When you start jbpm 6, you can access a summary of all available REST API functionalities by accessing the url http://localhost:8080/business-central/rest-api.jsp:

jbpm6 remote

A Java API for the REST interface

If you don’t like to manually create HTTP requests to access jBPM remotely, no worries! There’s a Java API that is aimed to wrap the HTTP requests for you. The entry point of this API is the class RuntimeEngine, and you can access get an instance of it by using the class RemoteRuntimeEngineFactory as follows:

// Setup the factory class with the necessarry information to communicate with the REST services
RuntimeEngine engine = RemoteRuntimeEngineFactory.newRestBuilder()
// if you're sending custom class parameters, make sure that
// the remote client instance knows about them!

Now you have access to KieSession, TaskService and AuditService remote interfaces and you are able to perform remote calls using pure Java code without having to care about XML/JSON parsing and how to manage HTTP connections with the remote jbpm server. To use the remote API you must have the maven dependency kie-remote for jBPM 6.3:


Our Sample process

To show the API in action we will create and deploy a project in Kie Workbench as it was explained in the article Introduction to jBPM 6. The process we are going to use is the rewards-basic with a few more nodes, see:

jbp6 tutorial This process basically accepts a String variable that contains the name of an employee that should receive a reward. If approved by the PM of the project and for the HR, the employee will receive the reward. Of course, this is a simple process to help us to show the remote API functionalities. We could increase it for example by adding a task to send email instead printing it in the console, or make a Web Service call, etc. We could also use complex types instead String or more detailed approval process, but for the sake of simplicity, we keep it using primitive types.

The process basically has two variables of type String for the employeeName and result. The employeeName it is set when starting the process (passed as a parameter) and the result value will depends on the approval flow. It also has two boolean variables: pmApproval and hrApproval. These variables will be set as a parameter resulting from the human tasks completion, which means that we will pass the boolean value when we complete the task.

Having a Kie Workbench project that has this process, build and deploy it. Now we can focus on the client app, because the process will be available for remote usage.

Using the Remote Java API

Our client application will use the Remote API to start process instances, get the value of process variables and access user tasks for PM and HR. We created a simple class to do some actions with the server. The full source code of this example is available at:

Here’s how our RuntimeEngine is created:

private RuntimeEngine engine;
private KieSession ksession;
private TaskService taskService;
private AuditService auditService;

private RewardService() throws MalformedURLException {
engine = RemoteRuntimeEngineFactory.newRestBuilder()
        .addPassword(PASSWORD).addUrl(new URL(SERVER_URL)).build();
taskService = engine.getTaskService();
ksession = engine.getKieSession();
auditService = engine.getAuditService();

Now we can do a few actions with the server calling methods from ksession, taskService or auditService. Start a process passing a map as parameter:

public void startRewardProcess(String employeeName) {
    Map<String, Object> params = new HashMap<>();
    params.put(P_EMPLOYEE, employeeName);
    ksession.startProcess(PROCESS_ID, params);

Doing actions with tasks:

public void doTask(long taskId, boolean approve) {
    Map<String, Object> params =  new HashMap<>();
    params.put(T_APPROVAL_VAR, approve);
    taskService.claim(taskId, USERNAME);
    taskService.start(taskId, USERNAME);
    taskService.complete(taskId, USERNAME, params);

Clear the history of the running server (DANGEREOUS METHOD!):

public void clearHistory() {

Retrieve a variable value using a process instance ID:

private String getVariableValue(long piid, String varName) {
    String value = null;
    List<? extends VariableInstanceLog> variables = auditService
            .findVariableInstances(piid, varName);
    if (variables.size() > 0)
        value = variables.get(0).getValue();
    return value;

There are, of course, a lot of other possibilities. These are just some possible remote operations to demonstrate the use of the Remote API.

AuthorWilliam Antônio Siqueira has about 6 years of Java programming experience. He started with JavaFX since its first release and since then he follows all the JavaFX updates. He regularly blogs about JavaFX, JBoss and Java application on He also founded a JUG on his region which has about 100 members. Currently he works for Red Hat supporting and helping on JBoss products maintenance. His main areas of interest are Java EE, REST Web Services, jBPM and JavaFX.