Restful Web Services with JBPM GWT console

This tutorial has been written for an old version of jBPM which is now deprecated.

If you want to get started quickly with jBPM, we recommend the following quickstarts:

JBPM 3.3.1 GA brings a few interesting news: one of this is the GWT console which allows for rapid publishing of Process information as REST resources and has out of the box support for “application/json” and “text/xml” marshalling.

In the web services world, REST is a key design idiom that embraces a stateless client-server architecture in which the web services are viewed as resources and can be identified by their URLs.

In short, the difference with traditional web services is that traditional Web Services are enginereed with a more complex protocol (SOAP) which has been built over HTTP. The web services request and response are in fact SOAP messages. REST web services on the other hand can be invoked as simple HTTP requests, adding the methods and parameters on the URL.

Step 1: download and install JBPM 3.3.1

JBPM can be downloaded from JBoss site at

You’ll notice that it is not a .zip file as the previous release. It’s actually an installer.

java -jar jbpm-installer-3.3.1.GA.jar

A wizard will guide you through the installation. Select th database you want to use (in this tutorial we’ll use MySQL)


Then you have to opportunity to select your JBoss server so JBPM gets actually deployed on your server with all the required libraries (this was really an annoying task to do manually!)

Step 2: configure the Database

Once the wizard has completed, move to the “deploy” folder of your JBoss distribution. You’ll notice a jbpm folder which contains the libraries, the applications and the configuration.

If you have selected MySQL as database you’ll find an “jbpm-mysql-ds.xml“. JBPM installer has created it for you. Not only, it has also copied the jdbc drivers for MySQL. Wonderful isn’t it ???

You need only to specify the Database settings, in our datasource file :

<?xml version="1.0" encoding="UTF-8"?>


    <xa-datasource-property name="URL">jdbc:mysql://localhost/jbpm</xa-datasource-property>
    <no-tx-separate-pools />
    <track-connection-by-tx />


In our sample we have created an empty schema named “jbpm” on our local machine.

Ok, now populate the Database running the scripts found under the JBPM_HOME/database folder
(I suggest you reading this tip for information about the jbpm database users:

Step 3: launch the console

The GWT console server can be reached at http://localhost:8080/gwt-console-server/
This is an hard copy if it:

GWT Console Server

Published REST Url’s

Method Context Description Mime Types

Process Management

GET /rs/process/definitions A list of process definitions application/json
POST /rs/process/definitions/{processId}/remove Removes a particular process definition application/json
GET /rs/process/definitions/{id}/instances A list of process instances for a given process definition application/json
POST /rs/process/instances/{id}/state/{next} Change instance state (RUNNING, SUSPENDED, ENDED) */*
POST /rs/process/definitions/{processId}/instances/new Create a new process instance application/json

User Management

GET /rs/user/roles?roleCheck=a,b,c A list of assigned roles matching the query parameter (Comma seperated list) application/json

Task Management

GET /rs/tasks/actor/{actorId} A list of available tasks (OPEN and IN_PROGRESS) for an actor application/json
GET /rs/tasks/{taskId}/assignment/{actorId} Assign a task to an actor actor. If you leave out the actorId it will release (IN_PROGRESS->OPEN) the task application/json
POST /rs/tasks/{taskId}/close/transition?signal={signalName} Complete a task with signal application/json
POST /rs/tasks/{taskId}/close/transition/default Complete a task with default transition application/json

jBPM3 proprietary extensions

GET /rs/jbpm3/definitions/{processId}/image Retrieve a process definition image (GPD), if deployed image/jpeg
GET /rs/jbpm3/definitions/{processId}/diagramInfo Retrieve a process definition coordinates (GPD) application/json
GET /rs/jbpm3/instances/{instanceId}/activeNodeInfo Retrieve a process definition coordinates (GPD) of the active node application/json
POST /rs/jbpm3/definitions/new Upload a new process definition Accept:multipart/form-data
POST /rs/jbpm3/tokens/{tokenId}/transition?signal={signalName} Signal a token by specifiy a transition  
POST /rs/jbpm3/tokens/{tokenId}/transition/default Signal a token to take the default transition  

As you can see, every process management action can be done simply with an HTTP request!
The output of the RestFul Web services is JSON.

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is another protocol to exchange data between web applications. is easy for humans to read and write. It is easy for machines to parse and generate.

JSON is built on two structures:

  • A collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.
  • An ordered list of values. In most languages, this is realized as an array, vector, list, or sequence.

In order to consume these web services you have several options, here we have used a simple shell command “curl” which is available on most Linux platforms and can be downloaded here for other OS:

Here’s a sample output from curl under windows:

curl http://localhost:8080/gwt-console-server/rs/process/definitions -u admin:admin


curl has many options, here we are only passing the URL of the Web service and the -u option which sets username and password needed.