JBoss.orgCommunity Documentation

Chapter 17. Remote API

17.1. Remote Java API
17.1.1. The REST Remote Java RuntimeEngine Factory
17.1.2. The JMS Remote Java RuntimeEngine Factory
17.1.3. Supported methods
17.2. REST
17.2.1. Runtime calls
17.2.2. History calls
17.2.3. Task calls
17.2.4. Deployment calls
17.2.5. Deployment call details
17.2.6. Execute calls
17.2.7. Additional Information
17.2.8. REST summary
17.3. JMS
17.3.1. JMS Queue setup
17.3.2. Using the remote Java API
17.3.3. Serialization issues
17.3.4. Example JMS usage

The workbench contains an execution server (for executing processes and tasks), which also allows you to invoke various process and task related operations through a remote API. As a result, you can setup your process engine "as a service" and integrate this into your applications easily by doing remote requests and/or sending the necessary triggers to the execution server whenever necessary (without the need to embed or manage this as part of your application).

Both a REST and JMS based service are available (which you can use directly), and a Java remote client allows you to invoke these operations using the existing KieSession and TaskService interfaces (you also use for local interaction), making remote integration as easy as if you were interacting with a local process engine.

17.1. Remote Java API

The Remote Java API provides KieSession, TaskService and AuditService interfaces to the JMS and REST APIs.

The interface implementations provided by the Remote Java API take care of the underlying logic needed to communicate with the JMS or REST APIs. In other words, these implementations will allow you to interact with a remote workbench instance (i.e. KIE workbench or the jBPM Console) via known interfaces such as the KieSession or TaskService interface, without having to deal with the underlying transport and serialization details.

The Remote Java API provides clients, not "instances"

While the KieSession, TaskSerivce and AuditService instances provided by the Remote Java API may "look" and "feel" like local instances of the same interfaces, please make sure to remember that these instances are only wrappers around a REST or jMS client that interacts with a remote REST or JMS API.

This means that if a requested operation fails on the server, the Remote Java API client instance on the client side will throw a RuntimeException indicating that the REST call failed. This is different from the behaviour of a "real" (or local) instance of a KieSession, TaskSerivce and AuditService instance because the exception the local instances will throw will relate to how the operation failed. Also, while local instances require different handling (such as having to dispose of a KieSession), client instances provided by the Remote Java API hold no state and thus do not require any special handling.

Lastly, operations on a Remote Java API client instance that would normally throw other exceptions (such as the TaskService.claim(taskId, userId) operation when called by a user who is not a potential owner), will now throw a RuntimeException instead when the requested operation fails on the server.

The first step in interacting with the remote runtime is to create either the RemoteRestRuntimeFactory or RemoteJmsRuntimeEngineFactory, both of which are instances of the RemoteRuntimeEngineFactory interface.

The configuration for the Remote Java API is done when creating the RemoteRuntimeEngineFactory instance: there are a number of different constructors for both the JMS and REST impelementations that allow the configuration of such things as the base URL of the REST API, JMS queue location or timeout while waiting for responses.

Once the factory instances have been created, there are a couple of methods that can then be used to instantiate the client instance that you want to use:

Remote Java API Methods

RemoteRuntimeEngine RemoteRuntimeEngineFactory.newRuntimeEngine()

This method instantiates a new RemoteRuntimeEngine (client) instance.

RemoteRuntimeEngineFactory.addExtraJaxbClasses(Collection<Class<?>> extraJaxbClasses )

This method adds extra classes to the classpath available to the serialization mechanisms.

When passing instances of user-defined classes in a Remote Java API call, it's important to have added the classes via this method first so that the class instances can be serialized correctly.

KieSession RemoteRuntimeEngine.getKieSession()

This method instantiates a new (client) KieSession instance.

TaskService RemoteRuntimeEngine.getTaskService()

This method instantiates a new (client) TaskService instance.

AuditService RemoteRuntimeEngine.getAuditService()

This method instantiates a new (client) AuditService instance.

Oops!

The RemoteRestRuntimeFactory should indeed have been called the RemoteRestRuntimeEngineFactory! Sometimes it's the easiest mistakes which are the hardest to catch. This will be corrected in future releases.

The RemoteRestRuntimeFactory has 4 constructor methods available. Besides an "everything" constructor method which provides all of the options provided below, there are also the following 3 constructors:

RemoteRestRuntimeFactory constructor method parameters

Simple constructor

Table 17.1. Simple RemoteRestRuntimeFactory constructor parameters

NameTypeDescription

deploymentId

java.lang.String

This is the name (id) of the deployment the RuntimeEngine should interact with.

baseUrl

java.net.URL

This is the URL of the deployed jbpm-console, kie-wb or BPMS instance.

For example: http://127.0.0.1:8080/jbpm-console/

username

java.lang.String

This is the user name needed to access the JMS queues.

password

java.lang.String

This is the password needed to access the JMS queues.


Constructor with timeout parameter

Table 17.2. RemoteRestRuntimeFactory constructor parameters with (response message) timeout parameter

NameTypeDescription

deploymentId

java.lang.String

This is the name (id) of the deployment the RuntimeEngine should interact with.

baseUrl

java.net.URL

This is the URL of the deployed jbpm-console, kie-wb or BPMS instance.

For example: http://127.0.0.1:8080/jbpm-console/

username

java.lang.String

This is the user name needed to access the REST API.

password

java.lang.String

This is the password needed to access the REST API.

timeoutInSeconds

int

This maximum number of seconds to wait when waiting for a response from the server.


Constructor with form-based authorization parameter

Table 17.3. RemoteRestRuntimeFactory constructor parameters with form-based authorization parameter

NameTypeDescription

deploymentId

java.lang.String

This is the name (id) of the deployment the RuntimeEngine should interact with.

baseUrl

java.net.URL

This is the URL of the deployed jbpm-console, kie-wb or BPMS instance.

For example: http://127.0.0.1:8080/jbpm-console/

username

java.lang.String

This is the user name needed to access the REST API.

password

java.lang.String

This is the password needed to access the REST API.

useFormBasedAuth

boolean

Whether or not to use form-based authentication when making a REST call. Form-based authentication will be necessary on tomcat instances.


The following example illustrates how the Remote Java API can be used with the REST API.

public void startProcessAndHandleTaskViaRestRemoteJavaAPI(URL instanceUrl, String deploymentId, String user, String password) {
  // the serverRestUrl should contain a URL similar to "http://localhost:8080/jbpm-console/"
  
  // Setup the factory class with the necessarry information to communicate with the REST services
  RemoteRuntimeEngineFactory restSessionFactory 
    = new RemoteRestRuntimeFactory(deploymentId, instanceUrl, user, password);

  // Create KieSession and TaskService instances and use them
  RemoteRuntimeEngine engine = restSessionFactory.newRuntimeEngine();
  KieSession ksession = engine.getKieSession();
  TaskService taskService = engine.getTaskService();

  // Each opertion on a KieSession, TaskService or AuditService (client) instance 
  // sends a request for the operation to the server side and waits for the response
  // If something goes wrong on the server side, the client will throw an exception. 
  ProcessInstance processInstance 
    = ksession.startProcess("com.burns.reactor.maintenance.cycle");
  long procId = processInstance.getId();

  String taskUserId = user;
  taskService = engine.getTaskService();
  List<TaskSummary> tasks = taskService.getTasksAssignedAsPotentialOwner(user, "en-UK");

  long taskId = -1;
  for (TaskSummary task : tasks) {
    if (task.getProcessInstanceId() == procId) {
      taskId = task.getId();
    }
  }

  if (taskId == -1) {
    throw new IllegalStateException("Unable to find task for " + user + " in process instance " + procId);
  }

  taskService.start(taskId, taskUserId);
}

The Remote JMS Java RuntimeEngine works precisely the same as the REST variant, except that it has different constructors.

The RemoteJmsRuntimeEngineFactory constructors can be grouped into 3 types. The list below specifies the main arguments to each group type.

  1. The URL of the execution server instance is given

  2. The JMS remote access objects (such as the ConnectionFactory and Queue) are given.

  3. A remote InitialContext instance (created using JNDI) from the server is given.

Configuration using the server URL. Configuration using only the URL of the server where the jBPM Console or KIE Workbench instance is running, is the most straightforward. However, this is only possible when the jBPM console or KIE Workbench instance is running on Wildfly or JBoss AS, or JBoss EAP.

The following table describes the parameters used when using an InitialContext to configure a RemoteJmsRuntimeEngineFactory instance:

Table 17.4. RemoteJmsRuntimeFactory constructor arguments

NameTypeDescription

deploymentId

java.lang.String

This is the name (id) of the deployment the RuntimeEngine should interact with.

serverURL

java.net.URL

This is the URL of the (JBoss) server instance..

username

java.lang.String

This is the user name needed to access the JMS queues and JNDI InitialContext instance.

password

java.lang.String

This is the password needed to access the JMS queues and JNDI InitialContext instance.


Configuration using an InitialContext instance. When configuring the RemoteJmsRuntimeEngineFactory with an InitialContext instance as a parameter, it's necessary to retrieve the (remote) InitialContext instance first from the remote server. The following code illustrates how to do this.

Important

The code below illustrates how this can be done with a JBoss AS 7 or EAP 6 server instance. Similar code is used in the constructor above.

However, regardless of which application server you use, it is necessary to include in your classpath the class specified as the INITIAL_CONTEXT_FACTORY (see below). For JBoss AS 7 and EAP 6, the artifact (jar) containing this class is the org.jboss:jboss-remote-naming artifact (jar), version 1.0.5.Final or higher. Depending on the version of AS 7 or EAP 6 that you use, this version may vary.

If you are using a different application server, please see your specific application server documentation for the parameters and artifacts necessary to create an InitialContextFactory instance or otherwise get a remote InitialContext instance (via JNDI) from the application server instance.

public void startProcessAndTaskViaJmsRemoteJavaAPI(String serverHostName, String deploymentId, String user, String password) {
  // Setup remote JMS runtime engine factory
  InitialContext remoteInitialContext 
    = getRemoteInitialContext(serverHostName, user, password);
  int maxTimeoutSecs = 5;
  RemoteJmsRuntimeEngineFactory remoteJmsFactory 
    = new RemoteJmsRuntimeEngineFactory(deploymentId, remoteInitialContext, user, password, maxTimeoutSecs);

  // Interface with JMS api
  RuntimeEngine engine = remoteJmsFactory.newRuntimeEngine();
  KieSession ksession = engine.getKieSession();
  ProcessInstance processInstance = ksession.startProcess("com.burns.reactor.maintenance.cycle");
  long procId = processInstance.getId();
  TaskService taskService = engine.getTaskService();
  List<Long> tasks = taskService.getTasksByProcessInstanceId(procId);
  taskService.start(tasks.get(0), user);
}

private static InitialContext getRemoteInitialContext(String jbossServerHostName, String user, String password) { 
  // Configure the (JBoss AS 7/EAP 6) InitialContextFactory
  Properties initialProps = new Properties();
  initialProps.setProperty(InitialContext.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
  initialProps.setProperty(InitialContext.PROVIDER_URL, "remote://"+ jbossServerHostName + ":4447");
  initialProps.setProperty(InitialContext.SECURITY_PRINCIPAL, user);
  initialProps.setProperty(InitialContext.SECURITY_CREDENTIALS, password);

  for (Object keyObj : initialProps.keySet()) {
    String key = (String) keyObj;
    System.setProperty(key, (String) initialProps.get(key));
  }
  
  // Create the remote InitialContext instance
  try {
    return new InitialContext(initialProps);
  } catch (NamingException e) {
    throw new RuntimeException("Unable to create " + InitialContext.class.getSimpleName(), e);
  }
}

The following table describes the parameters used when using an InitialContext to configure a RemoteJmsRuntimeEngineFactory instance:

Table 17.5. RemoteJmsRuntimeFactory constructor arguments

NameTypeDescription

deploymentId

java.lang.String

This is the name (id) of the deployment the RuntimeEngine should interact with.

initialContext

javax.naming.InitialContext

This is a remote InitialContext instance from which the (javax.jms) ConnectionFactory and Queue instances can be retrieved.

username

java.lang.String

This is the user name needed to access the JMS queues.

password

java.lang.String

This is the password needed to access the JMS queues.

timeoutSeconds

int

This maximum number of seconds to wait when waiting for a response from the server.


Configuration using ConnectionFactory and Queue instance parameters. Some users may have direct access to a ConnectionFactory and the Queue instances needed to interact with the JMS API. In this case, they can use the RemoteJmsRuntimeEngineFactory constructor that uses the following arguments:

Table 17.6. RemoteJmsRuntimeEngineFactory constructor arguments

NameTypeDescription

deploymentId

java.lang.String

This is the name (id) of the deployment the RuntimeEngine should interact with.

connectionFactory

javax.jms.ConnectionFactory

This is a ConnectionFactory instance used to connect to the ksessionQueue or taskQueue.

ksessionQueue

javax.jms.Queue

This is an instance of the Queue for requests relating to the process instance.

taskQueue

javax.jms.Queue

This is an instance of the Queue for requests relating to task service usage.

responseQueue

javax.jms.Queue

This is an instance of the Queue used to receive responses.

username

java.lang.String

This is the user name needed to access the JMS queues (in your application server configuration).

password

java.lang.String

This is the password needed to access the JMS queues (in your application server configuration).

timeoutSeconds

int

This maximum number of seconds to wait when waiting for a response from the server.


As mentioned above, the Remote Java API provides client-like instances of the RuntimeEngine, KieSession, TaskService and AuditService interfaces.

This means that while many of the methods in those interfaces are available, some are not. The following tables lists the methods which are available. Methods not listed in the below, will throw an UnsupportedOperationException explaining that the called method is not available.

Table 17.7. Available process-related KieSession methods

ReturnsMethod signatureDescription

void

abortProcessInstance(long processInstanceId)

Abort the process instance

ProcessInstance

getProcessInstance(long processInstanceId)

Return the process instance

ProcessInstance

getProcessInstance(long processInstanceId,
  boolean readOnly)

Return the process instance

List<ProcessInstance>

getProcessInstances()

Return all (active) process instances

void

signalEvent(String signal, Object event)

Signal all (active) process instances

void

signalEvent(String signal, Object event,
  long processInstanceId)

Signal the process instance

ProcessInstance

startProcess(String processId,
  CorrelationKey correlationKey,
  Map<String, Object> parameters)

Start a new process and return the process instance (if the process instance has not immediately completed)

ProcessInstance

startProcess(String processId,
  Map<String, Object> parameters);

Start a new process and return the process instance (if the process instance has not immediately completed)


Table 17.8. Available rules-related KieSession methods

ReturnsMethod signatureDescription

Long

getFactCount()

Return the total fact count

Object

getGlobal(String identifier)

Return a global fact

Integer

getId()

Return the id of the KieSession

void

setGlobal(String identifier, Object value)

Set a global fact

void

fireAllRules()

Fire all rules


Table 17.9. Available WorkItemManager methods

ReturnsMethod signatureDescription

void

abortWorkItem(long workItemId)

Abort the work item

void

completeWorkItem(long workItemId, Map<String, Object> results)

Complete the work item

WorkItem

getWorkItem(long workItemId)

Return the work item


Table 17.10. Available task operation TaskService methods

Returns Method signatureDescription

Long

addTask(Task task, Map<String, Object> params)

Add a new task

void

activate(long taskId, String userId)

Activate a task

void

claim(long taskId, String userId)

Claim a task

void

claim(long taskId, String userId, List<String> groupIds)

Claim a task

void

claimNextAvailable(String userId, String language)

Claim the next available task for a user

void

claimNextAvailable(String userId, List<String> groupIds,
  String language)

Claim the next available task for a user

void

complete(long taskId, String userId,
  Map<String, Object> data)

Complete a task

void

delegate(long taskId, String userId, String targetUserId)

Delegate a task

void

exit(long taskId, String userId)

Exit a task

void

fail(long taskId, String userId, Map<String,
  Object> faultData)

Fail a task

void

forward(long taskId, String userId, String targetEntityId)

Forward a task

void

nominate(long taskId, String userId,
  List<OrganizationalEntity> potentialOwners)

Nominate a task

void

release(long taskId, String userId)

Release a task

void

remove(long taskId, String userId)

Remove a task

void

resume(long taskId, String userId)

Resume a task

void

skip(long taskId, String userId)

Skip a task

void

start(long taskId, String userId)

Start a task

void

stop(long taskId, String userId)

Stop a task

void

suspend(long taskId, String userId)

Suspend a task


Table 17.11. Available task retrieval and query TaskService methods

Returns Method signature

Task

getTaskByWorkItemId(long workItemId)

Task

getTaskById(long taskId)

List<TaskSummary>

getTasksAssignedAsBusinessAdministrator(String userId,
  String language)

List<TaskSummary>

getTasksAssignedAsPotentialOwner(String userId, String language)

List<TaskSummary>

getTasksAssignedAsPotentialOwnerByStatus(String userId,
  List<Status>gt; status, String language)

List<TaskSummary>

getTasksOwned(String userId, String language)

List<TaskSummary>

getTasksOwnedByStatus(String userId, List<Status> status,
  String language)

List<TaskSummary>

getTasksByStatusByProcessInstanceId(long processInstanceId,
  List<Status> status, String language)

List<TaskSummary>

getTasksByProcessInstanceId(long processInstanceId)

List<TaskSummary>

getTasksByVariousFields(List<Long> workItemIds, List<Long> taskIds,
  List<Long> procInstIds, List<String> busAdmins, 
  List<String> potOwners, List<String> taskOwners, List<Status> status, 
  boolean union)

List<TaskSummary>

getTasksByVariousFields(Map <String, List<?>> parameters, boolean union)

Content

getContentById(long contentId)

Attachment

getAttachmentById(long attachId)


Table 17.12. Available AuditService methods

Returns Method signature

List<ProcessInstanceLog>

findProcessInstances()

List<ProcessInstanceLog>

findProcessInstances(String processId)

List<ProcessInstanceLog>

findActiveProcessInstances(String processId)

ProcessInstanceLog

findProcessInstance(long processInstanceId)

List<ProcessInstanceLog>

findSubProcessInstances(long processInstanceId)

List<NodeInstanceLog>

findNodeInstances(long processInstanceId)

List<NodeInstanceLog>

findNodeInstances(long processInstanceId, String nodeId)

List<VariableInstanceLog>

findVariableInstances(long processInstanceId)

List<VariableInstanceLog>

findVariableInstances(long processInstanceId,
  String variableId)

List<VariableInstanceLog>

findVariableInstancesByName(String variableId,
  boolean onlyActiveProcesses)

List<VariableInstanceLog>

findVariableInstancesByNameAndValue(String variableId,
  String value, boolean onlyActiveProcesses)

void

clear()


17.2. REST

REST API calls to the execution server allow you to remotely manage processes and tasks and retrieve various dynamic information from the execution server. The majority of the calls are synchronous, which means that the call will only finish once the requested operation has completed on the server. The exceptions to this are the deployment POST calls, which will return the status of the request while the actual operation requested will asynchronously execute.

When using Java code to interface with the REST API, the classes used in POST operations or otherwise returned by various operations can be found in the (org.kie.remote:)kie-services-client JAR.

This section lists REST calls that interface with

The deploymentId component of the REST calls below must conform to the following regular expression:

For information, see the Deployment calls section.

[POST] /runtime/{deploymentId}/process/{processDefId}/start
[POST] /runtime/{deploymentId}/process/{processDefId}/startform
[GET] /runtime/{deploymentId}/process/instance/{procInstId}
[POST] /runtime/{deploymentId}/process/instance/{procInstId+}/abort
[POST] /runtime/{deploymentId}/process/instance/{procInstId}/signal
[GET] /runtime/{deploymentId}/process/instance/{procInstId}/variables
[POST] /runtime/{deploymentId}/signal
[GET] /runtime/{deploymentId}/workitem/{workItemId}
[POST] /runtime/{deploymentId}/workitem/{workItemId}/complete
[POST] /runtime/{deploymentId}/workitem/{workItemId: [0-9-]+}/abort
[POST] /runtime/{deploymentId}/withvars/process/{processDefId}/start
[POST] /runtime/{deploymentId}/withvars/process/instance/{procInstId}
[POST] /runtime/{deploymentId}/withvars/process/instance/{procInstId}/signal

Note

Between the 6.0.0.Final and 6.0.1.Final releases, the History REST calls were udpated and fixed in order to make them both more robust and accessible. While the REST calls that were provided with 6.0.0.Final are still available in 6.0.1.Final, they will be removed in a future release.

[POST] /history/clear
[GET] /history/instances
[GET] /history/instance/{procInstId}
[GET] /history/instance/{procInstId}/child
[GET] /history/instance/{procInstId}/node
[GET]/history/instance/{procInstId}/variable
[GET] /history/instance/{procInstId}/node/{nodeId}
[GET] /history/instance/{procInstId}/variable/{varId}
[GET] /history/process/{processDefId}
[GET] /history/variable/{varId}
[GET] /history/variable/{varId}/value/{value}
[GET] /history/variable/{varId}/instances
[GET] /history/variable/{varId}/value/{value}/instances

Rest calls that contain "rest/runtime/{deploymentId}/history" have been deprecated: the same functionality provided by these calls can be found in the history REST calls described in the previous sections.

Important

If you're using the 6.0.0.Final release, the following applies to the History REST calls:

The history calls in 6.0.0.Final are dependent on a deployment being available to call them. This is because the History REST calls in 6.0.0.Final needed the persistence framework of a deployment in order to be executed. This means that history REST calls listed below may sometimes fail when used with a deployment unit that uses a PER_REQUEST or PER_PROCESS_INSTANCE strategy (i.e. when the deployment is no longer available).

[POST] /runtime/{deploymentId}/history/clear
[GET] /runtime/{deploymentId}/history/instances
[GET] /runtime/{deploymentId}/history/instance/{procInstId}
[GET] /runtime/{deploymentId}/history/instance/{procInstId}/child
[GET] /runtime/{deploymentId}/history/instance/{procInstId}/node
[GET] /runtime/{deploymentId}/history/instance/{procInstId}/variable
[GET] /runtime/{deploymentId}/history/instance/{procInstId}/node/{nodeId}
[GET] /runtime/{deploymentId}/history/instance/{procInstId}/variable/{varId}
[GET] /runtime/{deploymentId}/history/process/{processDefId}
[GET] /runtime/{deploymentId}/history/variable/{varId}
[GET] /runtime/{deploymentId}/history/variable/{varId}/value/{value}
[GET] /runtime/{deploymentId}/history/variable/{varId}/instances
[GET] /runtime/{deploymentId}/history/variable/{varId}/value/{value}/instances

The following section describes the three different types of task calls:

Task operation authorizations. Task REST operations use the user information (used to authorize and authenticate the HTTP call) to check whether or not the requested operations can happen. This also applies to REST calls that retrieve information, such as the task query operation. REST calls that request information will only return information about tasks that the user is allowed to see.

With regards to retrieving information, only users associated with a task may retrieve information about the task. However, the authorizations of progress and other modifications of task information are more complex. See the Task Permissions section in the Task Service documentation for more infomration.

Note

Given that many users have expressed the wish for a "super-task-user" that can execute task REST operations on all tasks, regardless of the users associated with the task, there are now plans to implement that feature. However, for the 6.0.x releases, this feature is not available.

All of the task operation calls described in this section use the user (id) used in the REST basic authorization as input for the user parameter in the specific call.

Some of the operations take an optional lanaguage query parameter. If this parameter is not given as a element of the URL itself, the default value of "en-UK" is used.

The taskId component of the REST calls below must conform to the following regex:

[POST] /task/{taskId}/activate
[POST] /task/{taskId}/claim
[POST] /task/{taskId}/claimnextavailable
[POST] /task/{taskId}/complete
[POST] /task/{taskId}/delegate
[POST] /task/{taskId}/exit
[POST] /task/{taskId}/fail
[POST] /task/{taskId}/forward
[POST] /task/{taskId}/nominate
[POST] /task/{taskId}/release
[POST] /task/{taskId}/resume
[POST] /task/{taskId}/skip
[POST] /task/{taskId}/start
[POST] /task/{taskId}/stop
[POST] /task/{taskId}/suspend
[GET] /task/{taskId}/showTaskForm
[GET] /task/query

The /task/query operation queries all non-archived tasks based on the parameters given.

Example 17.1. Query usage

This call retrieves the task summaries of all tasks that have a work item id of 3, 4, or 5. If you specify the same parameter multiple times, the query will select tasks that match any of that parameter.

  • http://server:port/rest/task/query?workItemId=3&workItemId=4&workItemId=5

The next call will retrieve any task summaries for which the task id is 27 and for which the work item id is 11. Specifying different parameters will result in a set of tasks that match both (all) parameters.

  • http://server:port/rest/task/query?workItemId=11&taskId=27

The next call will retrieve any task summaries for which the task id is 27 or the work item id is 11. While these are different parameters, the union parameter is being used here so that the union of the two queries (the work item id query and the task id query) is returned.

  • http://server:port/rest/task/query?workItemId=11&taskId=27&union=true

The next call will retrieve any task summaries for which the status is `Created` and the potential owner of the task is `Bob`. Note that the letter case for the status parameter value is case-insensitve.

  • http://server:port/rest/task/query?status=creAted&potentialOwner=Bob

The next call will return any task summaries for which the status is `Created` and the potential owner of the task is `bob`. Note that the potential owner parameter is case-sensitive. `bob` is not the same user id as `Bob`!

  • http://server:port/rest/task/query?status=created&potentialOwner=bob

The next call will return the intersection of the set of task summaries for which the process instance is 201, the potential owner is `bob` and for which the status is `Created` or `Ready`.

  • http://server:port/rest/task/query?status=created&status=ready&potentialOwner=bob&processInstanceId=201

That means that the task summaries that have the following characteristics would be included:

  • process instance id 201, potential owner `bob`, status `Ready`

  • process instance id 201, potential owner `bob`, status `Created`

And that following task summaries will not be included:

  • process instance id 183, potential owner `bob`, status `Created`

  • process instance id 201, potential owner `mary`, status `Ready`

  • process instance id 201, potential owner `bob`, status `Complete`


[GET] /task/{taskId}/content
[GET] /task/content/{contentId}

The calls described in this section allow users to manage deployments. Deployments are in fact KieModule JARs which can be deployed or undeployed, either via the UI or via the REST calls described below. Configuration options, such as the runtime strategy, should be specified when deploying the deployment: the configuration of a deployment can not be changed after it has already been deployed.

The above deploymentId regular expression describes an expression that contains the following elements, separated from eachother by a : character:

  1. The group id

  2. The artifact id

  3. The version

  4. The (optional) kbase id

  5. The (optional) ksession id

In a more formal sense, the deploymentId component of the REST calls below must conform to the following regex:

This regular expression is explained as follows:

There are 2 operations that can be used to modify the status of a deployment:

These POST deployment calls are both asynchronous, which means that the information returned by the POST request does not reflect the eventual final status of the operation itself.

Important

As noted above, both the /deploy and /undeploy operations are asynchronous REST operations. Successfull requests to these URLs will return the status 202 upon the request completion. RFC 2616 defines the 202 status as meaning that “the request has been accepted for processing, but the processing has not been completed.”

This means the following:

  1. While the request may have been accepted "successfully", the operation itself (deploying or undeploying the deployment unit) may actually fail.

  2. Furthermore, information about deployments, such as that retrieved by calling the GET operations described below, are snapshots and the information (including the status of the deployment unit) may have changed by the time the user client receives the answer to the GET request.

[GET] /deployment/
[GET] /deployment/ {deploymentId}
[POST] /deployment/ {deploymentId} /deploy
[POST] /deployment/ {deploymentId} /undeploy

While there is a /runtime/{id}/execute and a task/execute method, both will take all types of commands. This is possible because execute takes a JaxbCommandsRequest object, which contains a list of (org.kie.api.command.)Command objects. The JaxbCommandsRequest has fields to store the proper deploymentId and processInstanceId information.

Of course, if you send a request with a command that needs this information (deploymentId, for example) and don't fill the deploymentId in, the request will fail.

[POST] /task/execute
[POST] /runtime/ {deploymentId} /execute

Runtime commands. 

AbortWorkItemCommandGetProcessInstancesCommandGetGlobalCommand
CompleteWorkItemCommandSetProcessInstanceVariablesCommandGetIdCommand
GetWorkItemCommandSignalEventCommandSetGlobalCommand
AbortProcessInstanceCommandStartCorrelatedProcessCommandDeleteCommand
GetProcessIdsCommandStartProcessCommandFireAllRulesCommand
GetProcessInstanceByCorrelationKeyCommandGetVariableCommandInsertObjectCommand
GetProcessInstanceCommandGetFactCountCommandUpdateCommand

Task commands. 

ActivateTaskCommandFailTaskCommandGetTasksOwnedCommand
AddTaskCommandForwardTaskCommandNominateTaskCommand
CancelDeadlineCommandGetAttachmentCommandProcessSubTaskCommand
ClaimNextAvailableTaskCommandGetContentCommandReleaseTaskCommand
ClaimTaskCommandGetTaskAssignedAsBusinessAdminCommandResumeTaskCommand
CompleteTaskCommandGetTaskAssignedAsPotentialOwnerCommandSkipTaskCommand
CompositeCommandGetTaskByWorkItemIdCommandStartTaskCommand
DelegateTaskCommandGetTaskCommandStopTaskCommand
ExecuteTaskRulesCommandGetTasksByProcessInstanceIdCommandSuspendTaskCommand
ExitTaskCommandGetTasksByStatusByProcessInstanceIdCommand 

Task commands. 

ClearHistoryLogsCommandFindProcessInstanceCommandFindSubProcessInstancesCommand
FindActiveProcessInstancesCommandFindProcessInstancesCommandFindVariableInstancesByNameCommand
FindNodeInstancesCommandFindSubProcessInstancesCommandFindVariableInstancesCommand

Except for the Execute calls, all other REST calls described below can use either JAXB or JSON.

All REST calls, unless otherwise specified, will use JAXB serialization.

When using JSON, make sure to add the JSON media type ("application/json") to the ACCEPT header of your REST call.

Sometimes, users may wish to pass instances of their own classes as parameters to commands sent in a REST request or JMS message. In order to do this, there are a number of requirements.

  1. The user-defined class satisfy the following in order to be property serialized and deserialized by the JMS API:

  2. The class definition must be included in the deployment jar of the deployment that the JMS message content is meant for.

  3. The sender must set a “deploymentId” string property on the JMS bytes message to the name of the deploymentId. This property is necessary in order to be able to load the proper classes from the deployment itself before deserializing the message on the server side.

Retrieving process variables

While submitting an instance of a user-defined class is possible via both the JMS and REST API's, retrieving an instance of the process variable is only possible via the REST API.

When interacting with the Remote API, users may want to pass instances of their own classes as parameters to certain operations. As mThis will only be possible if the KJar for a deployment includes these classes.

REST calls that involve the TaskService (e.g. that start with /task..), often do not contain any information about the associated deployment. In that case, an extra query parameter will have to be added to the REST call so that the server can find the appropriate deployment with the class (definition) and correctly deserialize the information passed with the call.

For these REST calls which do not contain the deployment id, you'll need to add the following parameter:

Table 17.13. Deployment id query parameter

Parameter nameDescription
deploymentId

Value (must match the regex [a-zA-Z0-9-:\.]+) specifies the deployment which contains the user-defined class(es) needed to correctly deserialze information passed in the call


Some of the REST calls below return lists of information. The results of these operations can be paginated , which means that the lists can be split up and returned according to the parameters sent by the user.

For example, if the REST call parameters indicate that page 2 with page size 10 should be returned for the results, then results 10 to (and including) 19 will be returned.

The first page is always page 1 (as opposed to page "0").

Table 17.14. Pagination query parameter syntax

Parameter nameDescription
page

The page number requested. The default value is 1.

p

Synonym for the above page parameter.

pageSize

The number of elements per page to return. The default value is 10.

s

Synonym for the above pageSize parameter.


If both a "long" pagination parameter and its synonym are used, then only the value from the "long" variant is used. For example, if the page is given with a value of 11 and the p parameter is given with a value of 37, then the value of the page parameter, 11 , will be used and the p parameter will be ignored.

For the following operations, pagination is always used. See above for the default values used.

Table 17.15. REST operations using pagination

REST call URLShort Description

/runtime/{deploymentId}/history/instance

Returns a list of ProcessInstanceLog instances

runtime/{deploymentId}/history/instance/{procInstid}

Returns a list of ProcessInstanceLog instances

/runtime/{deploymentId}/history/instance/{procInstId}/child

Returns a list of ProcessInstanceLog instances

/runtime/{deploymentId}/history/instance/{procInstId}/node

Returns a list of NodeInstanceLog instances

/runtime/{deploymentId}/history/instance/{procInstId}/node/{nodeId}

Returns a list of NodeInstanceLog instances

/runtime/{deploymentId}/history/instance/{procInstId}/variable

Returns a list of VariableInstanceLog instances

/runtime/{deploymentId}/history/instance/{procInstId}/variable/{varId}

Returns a list of VariableInstanceLog instances

/runtime/{deploymentId}/history/variable/{variableId}

Returns a list of VariableInstanceLog instances

/runtime/{deploymentId}/history/variable/{variableId}/instances

Returns a list of ProcessInstance instances

/runtime/{deploymentId}/history/variable/{variableId}/value/{value}

Returns a list of VariableInstanceLog instances

/runtime/{deploymentId}/history/variable/{variableId}/value/{value}/instances

Returns a list of ProcessInstance instances

/runtime/{deploymentId}/history/process/{procDefId}

Returns a list of ProcessInstanceLog instances

/task/query

Returns a list of TaskSummaryImpl instances


If you're triggering an operation with a REST API call that would normally (e.g. when interacting the same operation on a local KieSession or TaskService instance) take an instance of a java.util.Map as one of its parameters, you can submit key-value pairs to the operation to simulate this behaviour by passing a query parameter whose name starts with map_ .

Example 17.3. 

If you pass the query parameter map_kEy=vAlue in a REST call, then the Map that's passed to the actual underlying KieSession or TaskService operation will contain this ( String, String ) key value pair: "kEy" => "vAlue" .You could pass this parameter like so:

http://localhost:8080/kie-wb/rest/runtime/myproject/process/wonka.factory.loompa.hire/start?map_kEy=vAlue

Map query parameters also use the object query parameter syntax described below, so the following query parameter, map_total=5000 will be translated into a key-value pair in a map where the key is the String "total" and the value is a Long with the value of 5000. For example:

http://localhost:8080/kie-wb/rest/runtime/myproject/process/wonka.factory.oompa.chocolate/start?map_total=5000


The following operations take query map parameters:

  • /runtime/{deploymentId}/process/{processDefId}/start

  • /runtime/{deploymentId}/workitem/{processItemId}/complete

  • /runtime/{deploymentId}/withvars/process/{processDefId}/start

  • /task/{taskId}/complete

  • /task/{taskId}/fail

While REST calls obviously only take strings as query parameters, using the following notation for query parameters will mean that the string is translated into a different type of object when the value of the string is used in the actual operation:

Table 17.16. Number query parameter syntax

Regex syntaxType
\d+ Long
\d+i Integer
\d+l Long


The REST calls allow access to the underlying deployments, regardless of whether these deployments use the Singleton , Per-Process-Instance or Per-Request strategies.

While there's enough information in the URL in order to access deployments that use the Singleton , or Per-Request strategies, that's not always the case with the Per-Process-Instance runtimes because the REST operation will obviously need the process instance id in order to identify the deployment.

Therefore, for REST calls for which the URL does not contain the process instance id, you'll need to add the following parameter:

Table 17.17. Per-Process-Instance runtime query parameter

Parameter nameDescription
runtimeProcInstId

Value (must match the regex [0-9]+ ) specifies the process instance id that identifies the underlying Per-Process-Instance deployment

Will have no effect if the underlying deployment uses the Singleton or Per-Request strategy


The URL templates in the table below are relative the following URL:

Table 17.18. runtime REST calls

URL TemplateTypeDescription
/runtime/{deploymentId}/process/{procDefID}/startPOSTstart a process instance based on the Process definition (accepts query map parameters)
/runtime/{deploymentId}/process/{procDefID}/startformPOSTreturns a valid URL to the start process form to be shown on a client aplication.
/runtime/{deploymentId}/process/instance/{procInstanceID}GETreturn a process instance details
/runtime/{deploymentId}/process/instance/{procInstanceID}/abortPOSTabort the process instance
/runtime/{deploymentId}/process/instance/{procInstanceID}/signalPOSTsend a signal event to process instance (accepts query map parameters)
/runtime/{deploymentId}/process/instance/{procInstanceID}/variable/{varId}GETreturn a variable from a process instance
/runtime/{deploymentId}/signal/{signalCode}POSTsend a signal event to deployment
/runtime/{deploymentId}/workitem/{workItemID}/completePOSTcomplete a work item (accepts query map parameters)
/runtime/{deploymentId}/workitem/{workItemID}/abortPOSTabort a work item
/runtime/{deploymentId}/withvars/process/{procDefinitionID}/startPOST

start a process instance and return the process instance with its variables

Note that even if a passed variable is not defined in the underlying process definition, it is created and initialized with the passed value.

/runtime/{deploymentId}/withvars/process/instance/{procInstanceID}/GET

return a process instance with its variables

/runtime/{deploymentId}/withvars/process/instance/{procInstanceID}/signalPOST

send a signal event to the process instance (accepts query map parameters)

The following query parameters are accepted:

  • The signal parameter specifies the name of the signal to be sent

  • The event parameter specifies the (optional) value of the signal to be sent


Table 17.19. task REST calls

URL TemplateTypeDescription
/task/queryGET

return a TaskSummary list

/task/content/{contentID}GET

returns the content of a task

/task/{taskID}GET

return the task

/task/{taskID}/activatePOST

activate the task

/task/{taskID}/claimPOST

claim the task

/task/{taskID}/claimnextavailablePOST

claim the next available task

/task/{taskID}/completePOST

complete the task (accepts query map paramaters)

/task/{taskID}/delegatePOST

delegate the task

/task/{taskID}/exitPOST

exit the task

/task/{taskID}/failPOST

fail the task

/task/{taskID}/forwardPOST

forward the task

/task/{taskID}/nominatePOST

nominate the task

/task/{taskID}/releasePOST

release the task

/task/{taskID}/resumePOST

resume the task (after suspending)

/task/{taskID}/skipPOST

skip the task

/task/{taskID}/startPOST

start the task

/task/{taskID}/stopPOST

stop the task

/task/{taskID}/suspendPOST

suspend the task

/task/{taskID}/contentGET

returns the content of a task

/task/{taskID}/showTaskFormGET

returns a valid URL to the task form to be shown on a client aplication.


Table 17.20. history REST calls

URL TemplateTypeDescription
/history/clear/POSTdelete all process, node and history records
/history/instancesGETreturn the list of all process instance history records
/history/instance/{procInstId}GETreturn a list of process instance history records for a process instance
/history/instance/{procInstId}/childGETreturn a list of process instance history records for the subprocesses of the process instance
/history/instance/{procInstId}/nodeGETreturn a list of node history records for a process instance
/history/instance/{procInstId}/node/{nodeId}GETreturn a list of node history records for a node in a process instance
/history/instance/{procInstId}/variableGETreturn a list of variable history records for a process instance
/history/instance/{procInstId}/variable/{variableId}GETreturn a list of variable history records for a variable in a process instance
/history/process/{procDefId}GETreturn a list of process instance history records for process instances using a given process definition
/history/variable/{varId}GETreturn a list of variable history records for a variable
/history/variable/{varId}/instancesGETreturn a list of process instance history records for process instances that contain a variable with the given variable id
/history/variable/{varId}/value/{value}GETreturn a list of variable history records for variable(s) with the given variable id and given value
/history/variable/{varId}/value/{value}/instancesGETreturn a list of process instance history records for process instances with the specified variable that contains the specified variable value

Table 17.21. deployment REST calls

URL TemplateTypeDescription
/deploymentsGETreturn a list of (deployed) deployments
/deployment/{deploymentId}GETreturn the status and information about the deployment
/deployment/{deploymentId}/deployPOST

submit a request to deploy a deployment

/deployment/{deploymentId}/undeployPOST

submit a request to undeploy a deployment


The Java Message Service (JMS) is an API that allows Java Enterprise components to communicate with each other asynchronously and reliably.

Operations on the runtime engine and tasks can be done via the JMS API exposed by the jBPM console and KIE workbench. However, it's not possible to manage deployments or the knowledge base via this JMS API.

Unlike the REST API, it is possible to send a batch of commands to the JMS API that will all be processed in one request after which the responses to the commands will be collected and return in one response message.

When the Workbench is deployed on the JBoss AS or EAP server, it automatically creates 3 queues:

The KIE.SESSION and KIE.TASK queues should be used to send request messages to the JMS API. Command response messages will be then placed on the KIE.RESPONSE queues. Command request messages that involve starting and managing business processes should be sent to the KIE.SESSION and command request messages that involve managing human tasks, should be sent to the KIE.TASK queue.

Although there are 2 different input queues, KIE.SESSION and KIE.TASK, this is only in order to provide multiple input queues so as to optimize processing: command request messages will be processed in the same manner regardless of which queue they're sent to. However, in some cases, users may send many more requests involving human tasks than requests involving business processes, but then not want the processing of business process-related request messages to be delayed by the human task messages. By sending the appropriate command request messages to the appropriate queues, this problem can be avoided.

The term "command request message" used above refers to a JMS byte message that contains a serialized JaxbCommandsRequest object. At the moment, only XML serialization (as opposed to, JSON or protobuf, for example) is supported.

While it is possible to interact with a BPMS or KIE workbench server instance by sending and processing JMS messages that you create yourself, it will always be easier to use the remote Java API that's supplied by the kie-services-client jar.

For more information about how to use the remote Java API to interact with the JMS API of a server instance, see the Remote Java API section.

The JMS API accepts ByteMessage instances that contain serialized JaxbCommandsRequest objects. These JaxbCommandsRequest instances can be filled with multiple command objects. In this way, it's possible to send a batch of commands for processing to the JMS API.

When users wish to include their own classes with requests, there a number of requirements that must be met for the user-defined classes. For more information about these requirements, see the Sending and receiving user class instances section in the REST API documentation.

The following is a rather long example that shows how to use the JMS API. The numbers ("callouts") along the side of the example refer to notes below that explain particular parts of the example. It's supplied for those advanced users that do not wish to use the jBPM Remote Java API.

The jBPM Remote Java API, described here, will otherwise take care of all of the logic shown below.

// normal java imports skipped

import org.drools.core.command.runtime.process.StartProcessCommand;
import org.jbpm.services.task.commands.GetTaskAssignedAsPotentialOwnerCommand;
import org.kie.api.command.Command;
import org.kie.api.runtime.process.ProcessInstance;
import org.kie.api.task.model.TaskSummary;
import org.kie.services.client.api.command.exception.Remote(1)CommunicationException;
import org.kie.services.client.serialization.JaxbSerializationProvider;
import org.kie.services.client.serialization.SerializationConstants;
import org.kie.services.client.serialization.SerializationException;
import org.kie.services.client.serialization.jaxb.impl.JaxbCommandResponse;
import org.kie.services.client.serialization.jaxb.impl.JaxbCommandsRequest;
import org.kie.services.client.serialization.jaxb.impl.JaxbCommandsResponse;
import org.kie.services.client.serialization.jaxb.rest.JaxbExceptionResponse;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class DocumentationJmsExamples {

  protected static final Logger logger = LoggerFactory.getLogger(DocumentationJmsExamples.class);

  public void sendAndReceiveJmsMessage() {

    String USER = "charlie";
    String PASSWORD = "ch0c0licious";

    String DEPLOYMENT_ID = "test-project";
    String PROCESS_ID_1 = "oompa-processing";
    URL serverUrl;
    try {
      serverUrl = new URL("http://localhost:8080/jbpm-console/");
    } catch (MalformedURLException murle) {
      logger.error("Malformed URL for the server instance!", murle); 
      return;
    }

    // Create JaxbCommandsRequest instance and add commands
    Command<?> cmd = new StartProcessCommand(PROCESS_ID_1);
    int oompaProcessingResultIndex = 0;                    (5)
    JaxbCommandsRequest req = new JaxbCommandsRequest(DEPLO(2)YMENT_ID, cmd);
    req.getCommands().add(new GetTaskAssignedAsPotentialOwnerCommand(USER, "en-UK"));
    int loompaMonitoringResultIndex = 1;                   (5)

    // Get JNDI context from server
    InitialContext context = getRemoteJbossInitialContext(serverUrl, USER, PASSWORD);
      
    // Create JMS connection 
    ConnectionFactory connectionFactory;
    try {
      connectionFactory = (ConnectionFactory) context.lookup("jms/RemoteConnectionFactory");
    } catch (NamingException ne) {
      throw new RuntimeException("Unable to lookup JMS connection factory.", ne);
    }

    // Setup queues
    Queue sendQueue, responseQueue;
    try {
      sendQueue = (Queue) context.lookup("jms/queue/KIE.SESSION");
      responseQueue = (Queue) context.lookup("jms/queue/KIE.RESPONSE");
    } catch (NamingException ne) {
      throw new RuntimeException("Unable to lookup send or response queue", ne);
    }

    // Send command request
    Long processInstanceId = null; // needed if you're doing an operation on a PER_PROCESS_INSTANCE deployment
    String humanTaskUser = USER;
    JaxbCommandsResponse cmdResponse = sendJmsCommands(
        DEPLOYMENT_ID, processInstanceId, humanTaskUser, req, 
        connectionFactory, sendQueue, responseQueue, 
        USER, PASSWORD, 5);

    // Retrieve results
    ProcessInstance oompaProcInst = null;
    List<TaskSummary> charliesTasks = null;
    for (JaxbCommandResponse<?> response : cmdResponse.getR(6)esponses()) {
      if (response instanceof JaxbExceptionResponse) {
        // something went wrong on the server side
        JaxbExceptionResponse exceptionResponse = (JaxbExceptionResponse) response;
        throw new RuntimeException(exceptionResponse.getMessage());
      }

      if (response.getIndex() == oompaProcessingResultIndex(5)) {
        oompaProcInst = (ProcessInstance) response.getResul(6)t();
      } else if (response.getIndex() == loompaMonitoringRes(5)ultIndex) {
        charliesTasks = (List<TaskSummary>) response.getRes(6)ult();
      }
    }
  }

  private JaxbCommandsResponse sendJmsCommands(String deploymentId, Long processInstanceId, String user, JaxbCommandsRequest req,
      ConnectionFactory factory, Queue sendQueue, Queue responseQueue, String jmsUser, String jmsPassword, int timeout) {
    req.setProcessInstanceId(processInstanceId);
    req.setUser(user);

    Connection connection = null;
    Session session = null;
    String corrId = UUID.randomUUID().toString();
    String selector = "JMSCorrelationID = '" + corrId + "'";
    JaxbCommandsResponse cmdResponses = null;
    try {

      // setup
      MessageProducer producer;
      MessageConsumer consumer;
      try {
        if (jmsPassword != null) {
          connection = factory.createConnection(jmsUser, jmsPassword);
        } else {
          connection = factory.createConnection();
        }
        session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);

        producer = session.createProducer(sendQueue);
        consumer = session.createConsumer(responseQueue, selector);

        connection.start();
      } catch (JMSException jmse) {
        throw new RemoteCommunicationException("Unable to setup a JMS connection.", jmse);
      }

      JaxbSerializationProvider serializationProvider = new JaxbSerializationProvider();
      // if necessary, add user-created classes here:
      // xmlSerializer.addJaxbClasses(MyType.class, AnotherJaxbAnnotatedType.class);

      // Create msg
      BytesMessage msg;
      try {
        msg = session.createBytesMessage();                (3)

        // set properties
        msg.setJMSCorrelationID(corrId);                   (3)
        msg.setIntProperty(SerializationConstants.SERIALIZA(3)TION_TYPE_PROPERTY_NAME, JaxbSerializationProvider.JMS_SERIALIZATION_TYPE);
        Collection<Class<?>> extraJaxbClasses = serializationProvider.getExtraJaxbClasses();
        if (!extraJaxbClasses.isEmpty()) {
          String extraJaxbClassesPropertyValue = JaxbSerializationProvider
              .classSetToCommaSeperatedString(extraJaxbClasses);
          msg.setStringProperty(SerializationConstants.EXTRA_JAXB_CLASSES_PROPERTY_NAME, extraJaxbClassesPropertyValue);
          msg.setStringProperty(SerializationConstants.DEPLOYMENT_ID_PROPERTY_NAME, deploymentId);
        }

        // serialize request
        String xmlStr = serializationProvider.serialize(req(3));
        msg.writeUTF(xmlStr);
      } catch (JMSException jmse) {
        throw new RemoteCommunicationException("Unable to create and fill a JMS message.", jmse);
      } catch (SerializationException se) {
        throw new RemoteCommunicationException("Unable to deserialze JMS message.", se.getCause());
      }

      // send
      try {
        producer.send(msg);
      } catch (JMSException jmse) {
        throw new RemoteCommunicationException("Unable to send a JMS message.", jmse);
      }

      // receive
      Message response;
      try {
        response = consumer.receive(timeout);
      } catch (JMSException jmse) {
        throw new RemoteCommunicationException("Unable to receive or retrieve the JMS response.", jmse);
      }

      if (response == null) {
        logger.warn("Response is empty, leaving");
        return null;
      }
      // extract response
      assert response != null : "Response is empty.";
      try {
        String xmlStr = ((BytesMessage) response).readUTF();
        cmdResponses = (JaxbCommandsResponse) serialization(4)Provider.deserialize(xmlStr);
      } catch (JMSException jmse) {
        throw new RemoteCommunicationException("Unable to extract " + JaxbCommandsResponse.class.getSimpleName()
            + " instance from JMS response.", jmse);
      } catch (SerializationException se) {
        throw new RemoteCommunicationException("Unable to extract " + JaxbCommandsResponse.class.getSimpleName()
            + " instance from JMS response.", se.getCause());
      }
      assert cmdResponses != null : "Jaxb Cmd Response was null!";
    } finally {
      if (connection != null) {
        try {
          connection.close();
          session.close();
        } catch (JMSException jmse) {
          logger.warn("Unable to close connection or session!", jmse);
        }
      }
    }
    return cmdResponses;
  }

  private InitialContext getRemoteJbossInitialContext(URL url, String user, String password) { 
    Properties initialProps = new Properties();
    initialProps.setProperty(InitialContext.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
    String jbossServerHostName = url.getHost();
    initialProps.setProperty(InitialContext.PROVIDER_URL, "remote://"+ jbossServerHostName + ":4447");
    initialProps.setProperty(InitialContext.SECURITY_PRINCIPAL, user);
    initialProps.setProperty(InitialContext.SECURITY_CREDENTIALS, password);

    for (Object keyObj : initialProps.keySet()) {
      String key = (String) keyObj;
      System.setProperty(key, (String) initialProps.get(key));
    }
    try {
      return new InitialContext(initialProps);
    } catch (NamingException e) {
      throw new RemoteCommunicationException("Unable to create " + InitialContext.class.getSimpleName(), e);
    }
  }
}

1

These classes can all be found in the kie-services-client and the kie-services-jaxb JAR.

2

The JaxbCommandsRequest instance is the "holder" object in which you can place all of the commands you want to execute in a particular request. By using the JaxbCommandsRequest.getCommands() method, you can retrieve the list of commands in order to add more commands to the request.

A deployment id is required for command request messages that deal with business processes. Command request messages that only contain human task-related commands do not require a deployment id.

3

Note that the JMS message sent to the remote JMS API must be constructed as follows:

  • It must be a JMS byte message.

  • It must have a filled JMS Correlation ID property.

  • It must have an int property with the name of "serialization" set to an acceptable value (only 0 at the moment).

  • It must contain a serialized instance of a JaxbCommandsRequest, added to the message as a UTF string

4

The same serialization mechanism used to serialize the request message will be used to serialize the response message.

5

In order to match the response to a command, to the initial command, use the index field of the returned JaxbCommandResponse instances. This index field will match the index of the initial command. Because not all commands will return a result, it's possible to send 3 commands with a command request message, and then receive a command response message that only includes one JaxbCommandResponse message with an index value of 1. That 1 then identifies it as the response to the second command.

6

Since many of the results returned by various commands are not serializable, the jBPM JMS Remote API converts these results into JAXB equivalents, all of which implement the JaxbCommandResponse interface. The JaxbCommandResponse.getResult() method then returns the JAXB equivalent to the actual result, which will conform to the interface of the result.

For example, in the code above, the StartProcessCommand returns a ProcessInstance. In order to return this object to the requester, the ProcessInstance is converted to a JaxbProcessInstanceResponse and then added as a JaxbCommandResponse to the command response message. The same applies to the List<TaskSummary> that's returned by the GetTaskAssignedAsPotentialOwnerCommand.

However, not all methods that can be called on a normal ProcessInstance can be called on the JaxbProcessInstanceResponse because the JaxbProcessInstanceResponse is simply a representation of a ProcessInstance object. This applies to various other command response as well. In particular, methods which require an active (backing) KieSession, such as ProcessInstance.getProess() or ProcessInstance.signalEvent(String type, Object event) will throw an UnsupportedOperationException.