jBPM 6 REST API tutorial

User Rating: 5 / 5

Star ActiveStar ActiveStar ActiveStar ActiveStar Active
 

jBPM 6 supports REST API to remotely manage processes and tasks and retrieve various dynamic information from the execution server. In this tutorial we will learn how to execute REST calls to manage the simple process that we have created here: Create your first process with jBPM 6 Web designer

In order to use the REST API you need at first to grant a Role to the user that will execute REST calls. So for example, if you are using the bpmsAdmin user for accessing the BPM, then in your configuration/application-roles.properties include the following role mapping:

bpmsAdmin=admin,rest-all

Now, in order to manage the Process we have created, we need to know the deployment-id. This information is visible from the Authoring | Project Explorer view:

jbpm 6 rest tutorial

In our case, the deployment-id is: com.mastertheboss:demobpm:1.0

The other information is the processDefId which is in our case demobpm.simpleprocess

As first step, let's check the list of deployment units available through the following GET request:

http://localhost:8080/business-central/rest/runtime/com.mastertheboss:demobpm:1.0

We will use SOAPUI to execute our request:

jbpm 6 rest tutorial

Please notice that Authorization is mandatory: we need to include a Basic Authentication form with the username and Password in order to access REST Services.

Starting the Process

Next step will be starting the process. In this case, we will use the following runtime POST call, which executes a start of the "demobpm.simpleprocess"

/business-central/rest/runtime/com.mastertheboss:demobpm:1.0/process/demobpm.simpleprocess/start

jbpm 6 rest tutorial

Passing Variables to the Process

Note that the start process accepts a Map of parameters that can be used to inject process variables at startup. For example, if you were to inject the "param1" and "param2" process variables into the process (with values "1" and "2"), then the following Query Parameters need to be added: start?map_param1=1&map_param2=2

Ok, done with process startup, we can query for the status of a Process instance and variables with the following GET Request:

/business-central/rest/runtime/com.mastertheboss:demobpm:1.0/withvars/process/instance/1

As a result, the following XML will be returned:

<process-instance-with-vars-response>
   <status>SUCCESS</status>
   <url>/business-central/rest/runtime/com.mastertheboss:demobpm:1.0/withvars/process/instance/1</url>
   <variables>
      <entry>
         <key>initiator</key>
         <value>bpmsAdmin</value>
      </entry>
   </variables>
   <processInstance>
      <process-id>demobpm.simpleprocess</process-id>
      <id>1</id>
      <state>1</state>
      <parentProcessInstanceId>0</parentProcessInstanceId>
   </processInstance>
</process-instance-with-vars-response>

As our Process is in a wait state now, we can check the Task list to see Tasks which are in charge to bpmsAdmin with the following GET: /business-central/rest/task/query

And the result:

<task-summary-list-response>
   <task-summary>
      <id>1</id>
      <name>SimpleTask</name>
      <subject/>
      <description/>
      <status>Reserved</status>
      <priority>0</priority>
      <skipable>true</skipable>
      <actual-owner>bpmsAdmin</actual-owner>
      <created-by>bpmsAdmin</created-by>
      <created-on>2016-05-16T16:14:39.518+02:00</created-on>
      <activation-time>2016-05-16T16:14:39.518+02:00</activation-time>
      <process-instance-id>1</process-instance-id>
      <process-id>demobpm.simpleprocess</process-id>
      <process-session-id>2</process-session-id>
      <deployment-id>com.mastertheboss:demobpm:1.0</deployment-id>
      <quick-task-summary>false</quick-task-summary>
      <parent-id>-1</parent-id>
   </task-summary>
</task-summary-list-response>

If the Task is assigned to a Group, we would need to claim it at first:

/business-­central/rest/task/1/claim

In our case the Task has been already assigned to the bpmsAdmin, so we just need to start it:

/business-­central/rest/task/1/start

Here is the response:

<response>
   <status>SUCCESS</status>
   <url>/business-central/rest/task/1/start</url>
</response>

Now the Task has been started and you can check it also from the Web console:

jbpm 6 rest tutorial

Last step will be completing the Task. Just as for the Start Process, we can pass a Map of attributes to the complete action:

/business­-central/rest/task/1/complete?map_approved_out=true

<response>
   <status>SUCCESS</status>
   <url>/business-central/rest/task/1/complete</url>
</response>

Great, now the Process is now completed. From now on, you can still query for information about your processes through the "history" REST calls. For example, to return the list of all process instances history records here is the GET you need:

/history/instances

If you need the process history records for a particular instance then you can issue the following GET:

/history/instance/{procInstId}

Follow us on Twitter