JBoss.orgCommunity Documentation
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.
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.
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 |
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 |
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.
InitialContext
instanceWhen 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.
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 |
connectionFactory | javax.jms.ConnectionFactory |
This is a valid |
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 |
ConnectionFactory
and Queue
instance parametersSome 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 |
connectionFactory | javax.jms.ConnectionFactory |
This is a |
ksessionQueue | javax.jms.Queue |
This is an instance of the |
taskQueue | javax.jms.Queue |
This is an instance of the |
responseQueue | javax.jms.Queue |
This is an instance of the |
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. |
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.
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.
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
|
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
|
pageSize
|
The number of elements per page to return. The default value is 10. |
s
|
Synonym for the above
|
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 |
---|---|
|
Returns a list of
|
|
Returns a list of
|
|
Returns a list of
|
|
Returns a list of
|
|
Returns a list of
|
|
Returns a list of
|
|
Returns a list of
|
|
Returns a list of
|
|
Returns a list of
|
|
Returns a list of
|
|
Returns a list of
|
|
Returns a list of
|
|
Returns a list of
|
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
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:
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 |
---|---|
runtimeProcInstId
|
Value (must match the regex
Will have no effect if the underlying deployment uses the
|
This section lists REST calls that interface with
The deploymentId component of the REST calls below must conform to the following regex:
[a-zA-Z0-9-:\.]+
/runtime/
{deploymentId}
/process/
{processDefId}
/start
Starts a process.
Returns a
JaxbProcessInstanceResponse
instance, that contains basic information about the process instance.
The
prodessDefId
component of the URL must conform to the following regex:
[_a-zA-Z0-9-:\.]+
This operation takes map query parameters (see above), which will be used as parameters for the process instance.
/runtime/
{deploymentId}
/process/instance/
{procInstId}
Does a (read only) retrieval of the process instance. This operation will fail (code 400) if the process instance has been completed.
Returns a
JaxbProcessInstanceResponse
instance.
The
procInstId
component of the URL must conform to the following regex:
[0-9]+
/runtime/
{deploymentId}
/process/instance/
{procInstId+}
/abort
Aborts the process instance.
Returns a
JaxbGenericResponse
indicating whether or not the operation has succeeded.
The
procInstId
component of the URL must conform to the following regex:
[0-9]+
/runtime/
{deploymentId}
/process/instance/
{procInstId}
/signal
Signals the process instance.
Returns a
JaxbGenericResponse
indicating whether or not the operation has succeeded.
The
procInstId
component of the URL must conform to the following regex:
[0-9]+
This operation takes a
signal
and a
event
query parameter.
The
signal
parameter value is used as the name of the signal. This parameter is required.
The
event
parameter value is used as the value of the event. This value may use the
number query parameter
syntax described above.
/runtime/
{deploymentId}
/process/instance/
{procInstId}
/variables
Gets the list of process variables in a process instance.
Returns a
JaxbVariablesResponse
The
procInstId
component of the URL must conform to the following regex:
[0-9]+
/runtime/
{deploymentId}
/signal
Signals the
KieSession
Returns a
JaxbGenericResponse
indicating whether or not the operation has succeeded.
The
procInstId
component of the URL must conform to the following regex:
[0-9]+
This operation takes a
signal
and a
event
query parameter.
The
signal
parameter value is used as the name of the signal. This parameter is required.
The
event
parameter value is used as the value of the event. This value may use the
number query parameter
syntax described above.
/runtime/
{deploymentId}
/workitem/
{workItemId}
Gets a
WorkItem
instance
Returns a
JaxbWorkItem
instance
The
workItemId
component of the URL must conform to the following regex:
[0-9]+
/runtime/
{deploymentId}
/workitem/
{workItemId}
/complete
Completes a
WorkItem
Returns a
JaxbGenericResponse
indicating whether or not the operation has succeeded
The
workItemId
component of the URL must conform to the following regex:
[0-9]+
This operation takes map query parameters , which are used as input to signify the results for completion of the work item.
/runtime/
{deploymentId}
/workitem/{workItemId: [0-9-]+}/abort
Aborts a
WorkItem
Returns a
JaxbGenericResponse
indicating whether or not the operation has succeeded
The
workItemId
component of the URL must conform to the following regex:
[0-9]+
/runtime/
{deploymentId}
/withvars/process/
{processDefId}
/start
Starts a process and retrieves the list of variables associated with the process instance
Returns a
JaxbProcessInstanceWithVariablesResponse
that contains:
Information about the process instance (with the same fields and behaviour as the
JaxbProcessInstanceResponse
A key-value list of the variables available in the process instance.
The
processDefId
component of the URL must conform to the following regex:
[_a-zA-Z0-9-:\.]+
/runtime/
{deploymentId}
/withvars/process/instance/
{procInstId}
Starts a process and retrieves the list of variables associated with the process instance
Returns a
JaxbProcessInstanceWithVariablesResponse
(see the above REST
call)
The
processInstId
component of the URL must conform to the following regex:
[0-9]+
/runtime/
{deploymentId}
/withvars/process/instance/
{procInstId}
/signal
Signals a process instance and retrieves the list of variables associated it
Returns a
JaxbProcessInstanceWithVariablesResponse
(see above)
The
processInstId
component of the URL must conform to the following regex:
[0-9]+
This operation takes a
signal
and a
event
query parameter.
The
signal
parameter value is used as the name of the signal. This parameter is required.
The
event
parameter value is used as the value of the event. This value may use the
number query parameter
syntax described above.
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.
/runtime/
{deploymentId}
/history/clear
Cleans (deletes) all history logs
/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
/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
/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
/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
/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
/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
/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
/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
/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
/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
/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
/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
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
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]+
/task/
{taskId}
/activate
Activates a task
Returns a
JaxbGenericResponse
with the status of the operation
/task/
{taskId}
/claim
Claims a task
Returns a
JaxbGenericResponse
with the status of the operation
/task/
{taskId}
/claimnextavailable
Claims the next available task
Returns a
JaxbGenericResponse
with the status of the operation
Takes an optional
language
query parameter.
/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
/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
/task/
{taskId}
/exit
Exits a task
Returns a
JaxbGenericResponse
with the status of the operation
/task/
{taskId}
/fail
Fails a task
Returns a
JaxbGenericResponse
with the status of the operation
/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
/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
/task/
{taskId}
/release
Releases a task
Returns a
JaxbGenericResponse
with the status of the operation
/task/
{taskId}
/resume
Resumes a task
Returns a
JaxbGenericResponse
with the status of the operation
/task/
{taskId}
/skip
Skips a task
Returns a
JaxbGenericResponse
with the status of the operation
/task/
{taskId}
/start
Starts a task
Returns a
JaxbGenericResponse
with the status of the operation
/task/
{taskId}
/stop
Stops a task
Returns a
JaxbGenericResponse
with the status of the operation
/task/
{taskId}
/suspend
Suspends a task
Returns a
JaxbGenericResponse
with the status of the operation
/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:
businessAdministrator
Specifies that the returned tasks should have the business administrator identified by this parameter
This parameter may be repeated
potentialOwner
Specifies that the returned tasks should have the potential owner identified by this parameter
This parameter may be repeated
processInstanceId
Specifies that the returned tasks should be associated with the process instance identified by this parameter
This parameter may be repeated
status
Specifies that the returned tasks should have the status identified by this parameter
This parameter may be repeated
taskId
Specifies that the returned tasks should have the (task) id identified by this parameter
This parameter may be repeated
taskOwner
Specifies that the returned tasks should have the task owner (initiator) identified by this parameter
This parameter may be repeated
workItemId
Specifies that the returned tasks should be associated with the work item identified by this parameter
This parameter may be repeated
language
Specifies the language that the returned tasks should be associated with
This parameter may be repeated
union
This specifies whether the query should query the union or intersection of the parameters. See below for more info.
This parameter must only be passed once
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.
/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]+
/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]+
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:
[A-Z]
[a-z]
[0-9]
_
.
-
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
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.
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.
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:
An identical job has already been submitted to the queue and has not yet completed.
The amount of (deploy/undeploy) jobs submitted but not yet processed exceeds the deploy/undeploy job queue size.
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. |
/deployment/
Returns a list of all the available deployed instances in a
JaxbDeploymentUnitList
instance
/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.
/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:
This parameter describes the runtime strategy used for the deployment.
This parameter takes the following (case- in sensitive) values:
SINGLETON
PER_REQUEST
PER_PROCESS_INSTANCE
The default runtime strategy used for a deployment is
SINGLETON
.
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
/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.
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.
/task/execute
Executes a
Command
, assumed to be related to tasks.
Returns a
JaxbCommandResponse
implementation with the result of the operation
/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
AbortWorkItemCommand | GetProcessInstancesCommand | GetGlobalCommand |
CompleteWorkItemCommand | SetProcessInstanceVariablesCommand | GetIdCommand |
GetWorkItemCommand | SignalEventCommand | SetGlobalCommand |
AbortProcessInstanceCommand | StartCorrelatedProcessCommand | DeleteCommand |
GetProcessIdsCommand | StartProcessCommand | FireAllRulesCommand |
GetProcessInstanceByCorrelationKeyCommand | GetVariableCommand | InsertObjectCommand |
GetProcessInstanceCommand | GetFactCountCommand | UpdateCommand |
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 |
ClearHistoryLogsCommand | FindProcessInstanceCommand | FindSubProcessInstancesCommand |
FindActiveProcessInstancesCommand | FindProcessInstancesCommand | FindVariableInstancesByNameCommand |
FindNodeInstancesCommand | FindSubProcessInstancesCommand | FindVariableInstancesCommand |
This section describes the setup and use of the JMS API.
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.
While it's 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 following section.. ???
Sometimes, users may wish to pass instances of their own classes as parameters to commands sent in a JMS message. In order to do this, there are a number of requirements.
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 must either implement the Serializable
interface or
otherwise be correctly annotated with JAXB annotations.
The class definition must implement a no-arg constructor.
Any fields in the class must either be object primitives (such as a
Long
or String
) or otherwise satisfy the above 2
requirements.
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.
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 msgBytesMessage 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 responseassert 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 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:
| |
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 | |
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 For example, in the code above, the However, not all methods that can be called on a normal |