Chapter 17. Remote API

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 AuditLogService 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.

17.1.1. The REST Remote Java RuntimeEngine Factory

In order to interact via REST with the remote runtime, the RemoteRestRuntimeFactory can be used. Through this factory, you can get access to a KieSession and TaskService, which you can then interact with the same way as if they were a local services. The following example illustrates how the remote session can be used.

// Setup the factory class with the necessarry information to communicate with the REST services

RemoteRestRuntimeFactory restSessionFactory 

  = new RemoteRestRuntimeFactory(deploymentId, baseUrl, user, password);


// Create KieSession and TaskService instances and use them

RuntimeEngine engine = restSessionFactory.newRuntimeEngine();

KieSession ksession = engine.getKieSession();

ProcessInstance processInstance = ksession.startProcess("com.burns.reactor.maintenance.cycle");

long procId = processInstance.getId();

  

String taskUserId = user;

TaskService 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 RemoteRestRuntimeFactory has one constructor which takes the arguments described in table below.

Table 17.1. RemoteRestRuntimeFactory constructor arguments

Name	Type	Example value	Description
`deploymentId`	`java.lang.String`	`reactor-maintenance-project`	This is the name (id) of the deployment the `RuntimeEngine` should interact with.
`baseURL`	`java.net.URL`	`http://localhost:8080/jbpm-console/`	This is the base URL of where the workbench application is deployed, containing the remote execution server to connect to.
`user`	`java.lang.String`	`homer`	This is the user needed for authentication for all REST calls.
`password`	`java.lang.String`	`d0nutsd0nutsILUVDONUTS!`	This is the password for the user specified in the `user` parameter.

17.1.2. The JMS Remote Java RuntimeEngine Factory

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

The RemoteJmsRuntimeEngineFactory has multiple constructors: one set of constructors allows the user to specify the JMS ConnectionFactory instance and each JMS Queue instance, while the other set takes an InitialContext instance that is expected to contain references to the ConnectionFactory and Queue instances.

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.

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 maxWaitTimeMillisecs = 5 * 1000;

  RemoteJmsRuntimeEngineFactory remoteJmsFactory

    = new RemoteJmsRuntimeEngineFactory(deploymentId, remoteInitialContext, user, password, maxWaitTimeMillisecs);


  // 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.2. RemoteRestRuntimeFactory constructor arguments

Name	Type	Description
`deploymentId`	`java.lang.String`	This is the name (id) of the deployment the `RuntimeEngine` should interact with.
`connectionFactory`	`javax.jms.ConnectionFactory`	This is a valid `ConectionFactory` instance that will be used to create a connection to the JMS queue used by the JMS API.
`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.
`qosThresholdMillisecs`	`int`	This maximum number of milliseconds to wait when waiting for a response from the server.

The following constructors are also available for users who wish to use the default quality of service threshold value (maximum wait time) for JMS messages, or otherwise configured the JMS queues to accept all connections:

Table 17.3. RemoteJmsRuntimeEngineFactory constructor arguments

Name	Type	Description
`deploymentId`	`java.lang.String`	This is the name (id) of the deployment the `RuntimeEngine` should interact with.

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.4. RemoteJmsRuntimeEngineFactory constructor arguments

Name	Type	Description
`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).
`qosThresholdMillisecs`	`int`	This maximum number of milliseconds to wait when waiting for a response from the server.

17.2. REST

REST API calls to the execution server allow you to 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 complete, including the possible return of a result, once the requested operation has succeeded. 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.

17.2.1. Additional Information

17.2.1.1. Serialization: JAXB or JSON

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.

17.2.1.2. Serialization: classes from the deployment/KJar

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

For all REST calls that start with /runtime/{deploymentId} , no additional information is required in order to pass instances of these classes.

However, REST calls 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.

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

Table 17.5. Deployment id query parameter

Parameter name	Description
`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

17.2.1.3. Pagination

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.6. Pagination query parameter syntax

Parameter name	Description
`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.7. REST operations using pagination

REST call URL	Short 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

17.2.1.4. Map query parameters

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.1.

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

17.2.1.5. Number query parameters

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.8. Number query parameter syntax

Regex syntax	Type
`\d+`	`Long`
`\d+i`	`Integer`
`\d+l`	`Long`

17.2.1.6. Runtime strategies

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.9. Per-Process-Instance runtime query parameter

Parameter name Description

Parameter name	Description
`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

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

17.2.3. History calls

Important

The information that is available via the History REST calls is not limited to the deployment specfied by the deploymentId part of the URL used. This is because the AuditLogService used by the REST calls is only dependent on the persistence framework used by the deployment, but not on anything else.

[POST] /runtime/ {deploymentId} /history/clear

Cleans (deletes) all history logs

[GET] /runtime/ {deploymentId} /history/instances

Gets a list of ProcessInstanceLog instances
Returns a JaxbHistoryLogList instance that contains a list of JaxbProcessInstanceLog instances
This operation responds to pagination parameters

[GET] /runtime/ {deploymentId} /history/instance/ {procInstId}

Gets the ProcessInstanceLog instance associated with the specified process instance
Returns a JaxbHistoryLogList instance that contains a JaxbProcessInstanceLog instance
The processInstId component of the URL must conform to the following regex: [0-9]+
This operation responds to pagination parameters

[GET] /runtime/ {deploymentId} /history/instance/ {procInstId} /child

Gets a list of ProcessInstanceLog instances associated with any child/sub-processes associated with the specified process instance
Returns a JaxbHistoryLogList instance that contains a list of JaxbProcessInstanceLog instances
The processInstId component of the URL must conform to the following regex: [0-9]+
This operation responds to pagination parameters

[GET] /runtime/ {deploymentId} /history/instance/ {procInstId} /node

Gets a list of NodeInstanceLog instances associated with the specified process instance
Returns a JaxbHistoryLogList instance that contains a list of JaxbNodeInstanceLog instances
The processInstId component of the URL must conform to the following regex: [0-9]+
This operation responds to pagination parameters

[GET] /runtime/ {deploymentId} /history/instance/ {procInstId} /variable

Gets a list of VariableInstanceLog instances associated with the specified process instance
Returns a JaxbHistoryLogList instance that contains a list of JaxbVariableInstanceLog instances
The processInstId component of the URL must conform to the following regex: [0-9]+
This operation responds to pagination parameters

[GET] /runtime/ {deploymentId} /history/instance/ {procInstId} /node/ {nodeId}

Gets a list of NodeInstanceLog instances associated with the specified process instance that have the given (node) id
Returns a JaxbHistoryLogList instance that contains a list of JaxbNodeInstanceLog instances
The processInstId component of the URL must conform to the following regex: [0-9]+
The nodeId component of the URL must conform to the following regex: [a-zA-Z0-9-:\.]+
This operation responds to pagination parameters

[GET] /runtime/ {deploymentId} /history/instance/ {procInstId} /variable/ {varId}

Gets a list of VariableInstanceLog instances associated with the specified process instance that have the given (variable) id
Returns a JaxbHistoryLogList instance that contains a list of JaxbVariableInstanceLog instances
The processInstId component of the URL must conform to the following regex: [0-9]+
The varId component of the URL must conform to the following regex: [a-zA-Z0-9-:\.]+
This operation responds to pagination parameters

[GET] /runtime/ {deploymentId} /history/process/ {processDefId}

Gets a list of ProcessInstanceLog instances associated with the specified process definition
Returns a JaxbHistoryLogList instance that contains a list of JaxbProcessInstanceLog instances
The processDefId component of the URL must conform to the following regex: [_a-zA-Z0-9-:\.]+
This operation responds to pagination parameters

17.2.3.1. History calls that search by variable

[GET] /runtime/ {deploymentId} /history/variable/ {varId}

Gets a list of VariableInstanceLog instances associated with the specified variable id
Returns a JaxbHistoryLogList instance that contains a list of JaxbVariableInstanceLog instances
The varId component of the URL must conform to the following regex: [a-zA-Z0-9-:\.]+
This operation responds to pagination parameters

[GET] /runtime/ {deploymentId} /history/variable/ {varId} /value/ {value}

Gets a list of VariableInstanceLog instances associated with the specified variable id that contain the value specified
Returns a JaxbHistoryLogList instance that contains a list of JaxbVariableInstanceLog instances
Both the varId and value components of the URL must conform to the following regex: [a-zA-Z0-9-:\.]+
This operation responds to pagination parameters

[GET] /runtime/ {deploymentId} /history/variable/{varId}/instances

Gets a list of ProcessInstance instances that contain the variable specified by the given variable id.
Returns a JaxbProcessInstanceListResponse instance that contains a list of JaxbProcessInstanceResponse instances
The varId component of the URL must conform to the following regex: [a-zA-Z0-9-:\.]+
This operation responds to pagination parameters

[GET] /runtime/ {deploymentId} /history/variable/{varId}/value/{value}/instances

Gets a list of ProcessInstance instances that contain the variable specified by the given variable id which contains the (variable) value specified
Returns a JaxbProcessInstanceListResponse instance that contains a list of JaxbProcessInstanceResponse instances
Both the varId and value components of the URL must conform to the following regex: [a-zA-Z0-9-:\.]+
This operation responds to pagination parameters

17.2.4. Task calls

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

Task REST operations that mirror the TaskService interface, allowing the user to interact with the remote TaskService instance
The Task query REST operation, that allows users to query for Task instances
Other assorted Task REST operations

17.2.4.1. Task operation calls

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:

[0-9]+

[POST] /task/ {taskId} /activate

Activates a task
Returns a JaxbGenericResponse with the status of the operation

[POST] /task/ {taskId} /claim

Claims a task
Returns a JaxbGenericResponse with the status of the operation

[POST] /task/ {taskId} /claimnextavailable

Claims the next available task
Returns a JaxbGenericResponse with the status of the operation
Takes an optional language query parameter.

[POST] /task/ {taskId} /complete

Completes a task
Returns a JaxbGenericResponse with the status of the operation
Takes map query parameters, which are the "results" input for the complete operation

[POST] /task/ {taskId} /delegate

Delegates a task
Returns a JaxbGenericResponse with the status of the operation
Requires a targetId query parameter, which identifies the user or group to which the task is delegated

[POST] /task/ {taskId} /exit

Exits a task
Returns a JaxbGenericResponse with the status of the operation

[POST] /task/ {taskId} /fail

Fails a task
Returns a JaxbGenericResponse with the status of the operation

[POST] /task/ {taskId} /forward

Delegates a task
Returns a JaxbGenericResponse with the status of the operation
Requires a targetId query parameter, which identifies the user or group to which the task is forwarded

[POST] /task/ {taskId} /nominate

Nominates a task
Returns a JaxbGenericResponse with the status of the operation
Requires at least one of either the user or group query parameter, which identify the user(s) or group(s) that are nominated for the task

[POST] /task/ {taskId} /release

Releases a task
Returns a JaxbGenericResponse with the status of the operation

[POST] /task/ {taskId} /resume

Resumes a task
Returns a JaxbGenericResponse with the status of the operation

[POST] /task/ {taskId} /skip

Skips a task
Returns a JaxbGenericResponse with the status of the operation

[POST] /task/ {taskId} /start

Starts a task
Returns a JaxbGenericResponse with the status of the operation

[POST] /task/ {taskId} /stop

Stops a task
Returns a JaxbGenericResponse with the status of the operation

[POST] /task/ {taskId} /suspend

Suspends a task
Returns a JaxbGenericResponse with the status of the operation

17.2.4.2. Task query call

[GET] /task/query

The /task/query operation..

Queries the available (non-archived) tasks
Returns a JaxbTaskSummaryListResponse with a list of TaskSummaryImpl instances.
Takes the following (case- in sensitive) query parameters listed below:

Except for the union parameter, if any of the other parameters are passed multiple times, this operation will query tasks based on the union of all values specific parameter. This is always true, regardless of the value of the union parameter.

For example, if multiple taskOwner parameters are passed, this operation will return all tasks that have a task owner matching at least one of the passed values.

However, behaviour with regards to multiple (types of) parameters is governed by the union parameter: if the union parameter is passed as false , then the operation will query based on the intersection of the two sets of values.

For example, if both a taskOwner and taskId parameter are passed as well as a union parameter with a value of false , then the operation will query for tasks that have both the specified task owner and task id.

However, if the union parameter in the above example is true , then the operation will query for tasks that have either the specified task owner or the specified task id.

17.2.4.3. Other Task calls

[GET] /task/ {taskId} /content

Gets the task content from a task identified by the given task id
Returns a JaxbContent with the content of the task
The taskId component of the URL must conform to the following regex: [0-9]+

[GET] /task/content/ {contentId}

Gets the task content from a task identified by the given content id
Returns a JaxbContent with the content of the task
The contentId component of the URL must conform to the following regex: [0-9]+

17.2.5. Deployment calls

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 deploymentId component of the REST calls below must conform to the following regex:

[\w\.-]+(:[\w\.-]+){2,2}(:[\w\.-]*){0,2}

The above regular expression is explained below:

The [\w\.-] element, which occurs 3 times in the above regex, refers to a character set that can contain the following character sets:
The deploymentId string must contain at least 3 groups of characters that satisfy [\w\.-]+ separated by a : character. For example:
- com.wonka:choco-maker:67.190
Lastly, the deploymentId may then also contain up to two more groups of characters that satisfy [\w\.-]* separated by a : character (note that * means 0 or more characters where + means 1 or more). For example:
- com.wonka:choco-maker:67.190:oompaBase
- com.wonka:choco-maker:67.190:oompaLoompaBase:gloopSession

The general idea behind the deploymentId is that it describes it contains the following elements, separated from eachother by a : character:

The group id
The artifact id
The version
The (optional) kbase id
The (optional) ksession id

17.2.5.1. Asynchrous deployment calls

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

/deployments/{deploymentId}/deploy
/deployments/{deploymentId}/undeploydeploy

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:

While the request may have been accepted "successfully", the operation itself (deploying or undeploying the deployment unit) may actually fail.
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.

17.2.5.2. Additional deployment call details

In addition to the asynchronous nature of the POST deploy and undeploy calls described above, the following information is also important to know:

The deploy and undeploy operations can fail if one of the following is true:
1. An identical job has already been submitted to the queue and has not yet completed.
2. The amount of (deploy/undeploy) jobs submitted but not yet processed exceeds the deploy/undeploy job queue size.

17.2.5.2.1. The deploy/undeploy job queue

Requests for the deployment or undeployment of deployment units are added as they are received to a single queue and processed in a serial fashion.

The reason for this is that the increased complexity necessary to manage and safeguard concurrent deploy and undeploy operation requests possibly involving the same deployment unit is far more costly than the benefit of having these requests complete safely in a concurrent environment, especially given that deploy and undeploy requests will be far less utilized than parts of the remote API involving actions on the deployment units themselves.

The size of this queue can be determined at startup by the parameter described below. Otherwise, the deployment job queue size defaults to 100.

The following system properties can be specified in order to change the size of the deploy/undeploy job queue:

Table 17.10. System properties that influence REST deployment call behavior

Parameter name	Description
`org.kie.remote.rest.deployment.job.queue.size`	Specifies the size of the deploy/undeploy job queue. Must be numerical.

17.2.5.3. Deployment call details

[GET] /deployment/

Returns a list of all the available deployed instances in a JaxbDeploymentUnitList instance

[GET] /deployment/ {deploymentId}

Returns a JaxbDeploymentUnit instance containing th e information (including the configuration) of the deployment unit.
- This operation will fail when the URL uses a deployementId that refers to a deployment unit that does not exist or for which the deployment has not yet been completed.
- This operation may succeed for deployment units for which an undeploy operation request has not yet completed.

[POST] /deployment/ {deploymentId} /deploy

Deploys the deployment unit referenced by the deploymentId
Returns a JaxbDeploymentJobResult instance with the status of the request
Takes a strategy query parameter:
The deploy operation is an asynchronous operation. The status of the deployment can be retrieved using the GET calls described above.
The request can fail for the reasons described

[POST] /deployment/ {deploymentId} /undeploy

Undeploys the deployment unit referenced by the deploymentId
Returns a JaxbDeploymentJobResult instance with the status of the request
The undeploy operation is an asynchronous operation. The status of the deployment can be retrieved using the GET calls described above.

17.2.6. Execute calls

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 command that needs this information ( deploymentId , for example) and don't fill it in, this will fail.

17.2.6.1. Execution call details

[POST] /task/execute

Executes a Command , assumed to be related to tasks.
Returns a JaxbCommandResponse implementation with the result of the operation

[POST] /runtime/ {deploymentId} /execute

Executes a Command , assumed to be related to business processes or the knowledge session.
Returns a JaxbCommandResponse implementation with the result of the operation

17.2.6.2. Commands accepted

Runtime commands

AbortWorkItemCommand	GetProcessInstancesCommand	GetGlobalCommand
CompleteWorkItemCommand	SetProcessInstanceVariablesCommand	GetIdCommand
GetWorkItemCommand	SignalEventCommand	SetGlobalCommand
AbortProcessInstanceCommand	StartCorrelatedProcessCommand	DeleteCommand
GetProcessIdsCommand	StartProcessCommand	FireAllRulesCommand
GetProcessInstanceByCorrelationKeyCommand	GetVariableCommand	InsertObjectCommand
GetProcessInstanceCommand	GetFactCountCommand	UpdateCommand

Task commands

ActivateTaskCommand	FailTaskCommand	GetTasksOwnedCommand
AddTaskCommand	ForwardTaskCommand	NominateTaskCommand
CancelDeadlineCommand	GetAttachmentCommand	ProcessSubTaskCommand
ClaimNextAvailableTaskCommand	GetContentCommand	ReleaseTaskCommand
ClaimTaskCommand	GetTaskAssignedAsBusinessAdminCommand	ResumeTaskCommand
CompleteTaskCommand	GetTaskAssignedAsPotentialOwnerCommand	SkipTaskCommand
CompositeCommand	GetTaskByWorkItemIdCommand	StartTaskCommand
DelegateTaskCommand	GetTaskCommand	StopTaskCommand
ExecuteTaskRulesCommand	GetTasksByProcessInstanceIdCommand	SuspendTaskCommand
ExitTaskCommand	GetTasksByStatusByProcessInstanceIdCommand

Task commands

ClearHistoryLogsCommand	FindProcessInstanceCommand	FindSubProcessInstancesCommand
FindActiveProcessInstancesCommand	FindProcessInstancesCommand	FindVariableInstancesByNameCommand
FindNodeInstancesCommand	FindSubProcessInstancesCommand	FindVariableInstancesCommand

17.3. JMS

This section describes the setup and use of the JMS API.

17.3.1. JMS Queue setup

When the Workbench is deployed, it automatically creates 3 queues:

jms/queue/KIE.SESSION
jms/queue/KIE.TASK
jms/queue/KIE.RESPONSE

The KIE.SESSION and KIE.TASK queues should be used to send command request messages to the JMS API. Command response messages will be then placed on the KIE.RESPONSE. 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.

The following requirements are taken care of by the Remote Java API. However, if your application is communicating with the JMS API by creating JMS messages itself, then it must satisfy the following requirements when sending a message that includes a user-defined class instance:

The user-defined class satisfy the following in order to be property serialized and deserialized by the JMS API:
The class definition must be included in the deployment jar of the deployment that the JMS message content is meant for.
Lastly, 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.

17.3.5. Example JMS usage

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.

import static org.kie.services.client.serialization.SerializationConstants.*;


import java.util.List;

import java.util.UUID;


import javax.jms.*;

import javax.naming.*;

import javax.xml.bind.JAXBException;


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.serialization.jaxb.JaxbSerializationProvider;

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.impl.JaxbExceptionResponse;


// ...


  String USER = "charlie";

  String PASSWORD = "ch0c0licious";


  String DEPLOYMENT_ID = "test-project";

  String PROCESS_ID_1 = "oompa-processing";

  

  // Create command

  Command<?> cmd = new StartProcessCommand(PROCESS_ID_1);

  int oompaProcessingResultIndex = 0;

  JaxbCommandsRequest req = new JaxbCommandsRequest(DEPLOYMENT_ID, cmd);

  req.getCommands().add(new GetTaskAssignedAsPotentialOwnerCommand(USER, "en-UK"));

  int loompaMonitoringResultIndex = 1;


  // Setup queues

  

  InitialContext context;

  Queue sendQueue, responseQueue;

  try { 

      context = new InitialContext();

      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); 

  }


  Connection connection = null;

  Session session = null;

  JaxbCommandsResponse cmdResponse = null;


  String corrId = UUID.randomUUID().toString();

  String selector = "JMSCorrelationID = '" + corrId + "'";

  try {


      // Create JMS connection and session

      MessageProducer producer;

      MessageConsumer consumer;

      try {

          ConnectionFactory connectionFactory = (ConnectionFactory) context.lookup("jms/RemoteConnectionFactory");

          connection = connectionFactory.createConnection(USER, PASSWORD);

          session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);


          producer = session.createProducer(sendQueue);

          consumer = session.createConsumer(responseQueue, selector);


          connection.start();

      } catch (JMSException jmse) {

          throw new RuntimeException("Unable to setup a JMS connection.", jmse);

      } catch (NamingException ne) {

          throw new RuntimeException("Unable to lookup JMS connection factory.", ne);

      }


      // Create msg

      BytesMessage msg;

      try {

          msg = session.createBytesMessage();

          msg.setJMSCorrelationID(corrId);

          msg.setIntProperty("serialization", JaxbSerializationProvider.JMS_SERIALIZATION_TYPE);

          msg.setStringProperty(DEPLOYMENT_ID_PROPERTY_NAME, config.getDeploymentId());

          String xmlStr = JaxbSerializationProvider.convertJaxbObjectToString(req);

          msg.writeUTF(xmlStr);

      } catch (JMSException jmse) {

          throw new RuntimeException("Unable to create and fill a JMS message.", jmse);

      } catch (JAXBException jaxbe) {

          throw new RuntimeException("Unable to deserialze JMS message.", jaxbe);

      }


      // Send msg

      try {

          producer.send(msg);

      } catch (JMSException jmse) {

          throw new RuntimeException("Unable to send a JMS message.", jmse);

      }


      // receive

      Message response;

      try {

          long qualityOfServiceThresholdMilliSeconds = 5 * 1000;

          response = consumer.receive(qualityOfServiceThresholdMilliSeconds);

      } catch (JMSException jmse) {

          throw new RuntimeException("Unable to receive or retrieve the JMS response.", jmse);

      }


      // extract response

      assert response != null : "Response is empty.";

      try {

          String xmlStr = ((BytesMessage) response).readUTF();

          cmdResponse = (JaxbCommandsResponse) JaxbSerializationProvider.convertStringToJaxbObject(xmlStr);

      } catch (JMSException jmse) {

          throw new RuntimeException("Unable to extract " + JaxbCommandsResponse.class.getSimpleName()

                  + " instance from JMS response.", jmse);

      } catch (JAXBException jaxbe) {

          throw new RuntimeException("Unable to extract " + JaxbCommandsResponse.class.getSimpleName()

                  + " instance from JMS response.", jaxbe);

      }

      assert cmdResponse != null : "Jaxb Cmd Response was null!";

  } finally {

      if (connection != null) {

          try {

              connection.close();

              session.close();

          } catch (JMSException jmse) {

              System.out.println("Unable to close connection or session!");

              jmse.printStackTrace();

          }

      }

  }


  ProcessInstance oompaProcInst = null;

  List<TaskSummary> charliesTasks = null;

  for (JaxbCommandResponse<?> response : cmdResponse.getResponses()) {

      if (response instanceof JaxbExceptionResponse) {

          JaxbExceptionResponse exceptionResponse = (JaxbExceptionResponse) response;

          throw new RuntimeException(exceptionResponse.getMessage());

      }

      if (response.getIndex() == oompaProcessingResultIndex) {

          oompaProcInst = (ProcessInstance) response.getResult();

      } else if (response.getIndex() == loompaMonitoringResultIndex) {

          charliesTasks = (List<TaskSummary>) response.getResult();

      }

  }

	These classes can all be found in the (org.kie.remote:)kie-services-client JAR.
	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.
	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
	The same serialization mechanism used to serialize the request message will be used to serialize the response message.
	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.
	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`.