-
Notifications
You must be signed in to change notification settings - Fork 575
Rest API
- URL layout
- Additional documentation
- Runtime operations
- Task operations
- [Operation details]
The following schema lays out the current REST API available via kie-remote:
http://server.address:port/{application-id}/rest/
runtime
{id: [a-zA-Z0-9-:\\.]+} // {deploymentId}
execute * execute the given command [POST]
process
{id: [a-zA-Z0-9-:\\.]+} // {process definition id}
start * start process [POST]
- accepts query map parameters
instance
{id: [0-9]+} * process instance details (// {process instance id}) [GET]
signal * signal event [POST]
- accepts query map parameters
abort * abort process instance [POST]
variables * get variables from process instance [GET]
signal * signal event [POST]
- accepts query map parameters
workitem
{id: [0-9]+} * work item details (// {work item id}) [GET]
complete * complete work item [POST]
- accepts query map parameters
abort * abort work item [POST]
history
clear * clear/delete all (process/variable/node) instance logs [POST]
instances * get all process instance logs [GET]
{id: [0-9]+} * get process instance log (// {process instance id}) [GET]
child * get all child process instance logs [GET]
node * get all node instance logs [GET]
{id: [a-zA-Z0-9-:\\.]+} // {node id}
* get node instance log [GET]
variable * get all variable instances [GET]
{id: [a-zA-Z0-9-:\\.]+} // {variable id}
* get variable instance log [GET]
process
{id: [a-zA-Z0-9-:\\.]+} * get process instance logs (// {process id}) [GET]
variable
{id: [a-zA-Z0-9-:\\.]+} * get variable instance log with this name (// {variable id}) [GET]
instances * get process instance(s) in which variable is used [GET]
value
{id: [a-zA-Z0-9-:\\.]+} * get variable instance log with this name and value (// {variable value}) [GET]
instances * get process instance(s) for which variable has this name and value [GET]
withvars // The following operations return process instance
// as well as process variable information
process
{id: [a-zA-Z0-9-:\\.]+} // {process definition id}
start * start process [POST]
- accepts query map parameters
instance
{id: [0-9]+} * process instance details (// {process instance id}) [GET]
signal * signal event [POST]
- accepts query map parameters
task
execute * execute the given (task) command [POST]
content
{id: [0-9]+} * return the (JAXB) content [GET]
query * query tasks (list of JAXB TaskSummary instances returned) [GET]
{id: [0-9]+} * return (JAXB representation of the) task // {task id} [GET]
activate * activate task (taskId as query param.. ) [POST]
claim * claim task [POST]
claimnextavailable * claim next available task [POST]
complete * complete task [POST]
- accepts query map parameters
delegate * delegate task [POST]
- takes a "targetEntityId" query parameter
exit * exit task [POST]
fail * fail task [POST]
forward * forward task [POST]
- takes a "targetEntityId" query parameter
release * release task [POST]
resume * resume task [POST]
skip * skip task [POST]
start * start task [POST]
stop * stop task [POST]
suspend * suspend task [POST]
nominate * nominate task [POST]
- takes "user" and "group" parameters
content * return (a JAXB representation of the) task content [GET]
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.
While REST obviously only takes Strings as input parameters, using the following notation for query parameters will mean that the string is translated into a different type of object:
-
\d+: Long -
\d+i: Integer -
\d+l: Long
If you're interacting with a REST API call that would normally (when interacting the same operation on a local KieSession instance) take a Map<String, Object> instance, you can submit key-value pairs to the operation by passing a query param whose name starts with "`map_.".
For example, if you pass the query parameter "map_kEy=vAlue", then a Map<String, Object> will be
created that contains the key value pair { "kEy" => "vAlue" }. "query map parameters" also use the
"object parameter" syntax, so the following:
map_age=5000
will be translated into the key-value pair
{ "age" => Long.parseLong("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
When working with the KIE Workbench, Red Hat JBoss BPM Suite, or jBPM Console, there are 3 different types of deployments possible:
- Singleton
- Per Process Instance
- Per Request
These refer to how the KieSession (in which a jBPM process may be run) is handled.
If you've setup your deployment to be a Singleton or Per Request deployment, then you won't need additional parameters to interact with your deployment via the REST API.
However, if you've setup your deployment to be a Per Process Instance deployment, the REST API will need to know the process instance id in order to retrieve the KieSession instance. For some operations, the process instance is already part of the URL, such as this GET operation:
/runtime/{deploymentId}/process/instnce/{processInstanceId}
However, for those operations for which the processInstanceId is not part of the URL, you will need
to add a runtimeProcInstId query parameter to the URL in order to successfully complete the REST
operation. For example:
/runtime/{deploymentId}/workitem/12/abort?runtimeProcInstId=5
In the above case, the REST operation aborts work item 12 associated with process instance 5.
The following operations require the runtimeProcInstId parameter when using a Per Process Instance
strategy with a deployment:
/runtime/{deploymentId}/process/signal
/runtime/{deploymentId}/process/workitem/{workItemId}
/runtime/{deploymentId}/process/workitem/{workItemId}/complete
/runtime/{deploymentId}/process/workitem/{workItemId}/abort
/runtime/{deploymentId}/history/variable/{variableId}/instances
/runtime/{deploymentId}/history/variable/{variableId}/value/{value}/instances
All operations which return a list of items can be provided with parameters in order to "paginate" the results. Pagination means that the results can be divided into a number of pages, each of which contains the same number of items. If user needs results 10 to (and including) 19, then the user can request the operation be paginated with page 2 and page size 10.
The first page is page 1, not page 0!
The following methods will take query parameters in order to paginate the results of the operation:
/task/query
/runtime/{deploymentId}/history/instance
/runtime/{deploymentId}/history/instance/{procInstid}
/runtime/{deploymentId}/history/instance/{procInstId}/child
/runtime/{deploymentId}/history/instance/{procInstId}/node
/runtime/{deploymentId}/history/instance/{procInstId}/node/{nodeId}
/runtime/{deploymentId}/history/variable/{variableId}
/runtime/{deploymentId}/history/variable/{variableId}/instances
/runtime/{deploymentId}/history/variable/{variableId}/value/{value}
/runtime/{deploymentId}/history/variable/{variableId}/value/{value}/instances
/runtime/{deploymentId}/history/process/{id: [a-zA-Z0-9-:\\.]+}
Pagination parameters can be given using the following parameters:
page This the page number requested. The default value is 1.
p This is a synonym for the above "page" parameter.
pageSize This is the number of elements per page to return. The default value is 10.
s This is a synonym for the above "pageSize" parameter.
If both a parameter and it's synonym are included in an URL, the longer version of the parameter will be used instead of the shorter version.
For example, if you include "page=3&p=8" in your url, then page number 3 will be returned.
When no pagination parameters (see above) are included, the results will be paginated as folows:
- "Pages" will contain 10 items per page.
- The first page (e.g. the first 10 items), will be shown.
There are 4 operations available to query history and process instances based on variable information:
/runtime/{deploymentId}/history/variable/{variableId}
/runtime/{deploymentId}/history/variable/{variableId}/instances
/runtime/{deploymentId}/history/variable/{variableId}/value/{value}
/runtime/{deploymentId}/history/variable/{variableId}/value/{value}/instances
All 4 of these operations also take an additional query parameter: activeProcesses. If
activeProcesses is set to true, then the operation will only return results based on active
process instances. If activeProcesses is not set, or set to anything else, the results will be
based on all processes instances, active or not.
// MARCO: needs update (2013-10-21): rewrite to match new GetTasksByVariousFieldsCommand
// MARCO: update jbpm-human-task documentation
-
The
task/queryGET rest call takes the following query parameters:workItemIdtaskIdbusinessAdministratorpotentialOwnerstatustaskOwner-
processInstanceIdand union
-
At the moment, the name of the parameters is interpreted regardless of case, please make sure use the appropriate case for the values of the parameters.
-
If the following parameters are entered multiple times, a union of the results (see combinations listed above) will be returned:
workItemIdtaskIdbusinessAdministratorpotentialOwnertaskOwnerprocessInstanceId
-
The
statusparameter can also be entered multiple times, but is used slightly differently:-
The available values for the
statusquery are the following (case sensitive, at the moment):Created, Ready, Reserved, InProgress, Suspended, Completed, Failed, Error, Exited, ObsoleteThese values correspond to the values of the enum
org.kie.api.task.model.Status. -
The query will retrieve the union (OR) of all tasks that have the
statuses passed. -
However, when the list of
statuses is used in a query, the results returned are: - an intersection of - the union of tasks that have the status listed - with the union of the tasks that satisfy the other query criteria listed.
-
The task/content/{contentId: \\d+} and task/{taskId: \\d+}/content operations both return the
serialized content associated with a task.
Content associated with a task is stored in the human-task database schema in serialized form.
Whether the content is a string (with xml content) or a (hash-)map with several different key-value
pairs, this content is serialized using the protobuf based algorithm that jbpm uses. This
serialization process is normally carried out by the static methods in the
org.jbpm.services.task.utils.ContentMarshallerHelper class.
However, clients that call the rest operations may not necessarily have access to this class, which
is why the any objects present in the task content are first deserialized using the
ContentMarshallerHelper class and then serialized using the normal Java serialization mechanism.
However, there are limits on what can be returned by these rest operations. Only the following objects can be returned by the task content operations:
- Task content can be returned by get task content rest operations if the content is one of two
types of objects:
- An instance of a class that implements the
Serializableinterface. - An instance of a Map<String, Object>, which only contains values that implement the
Serializableinterface.
- An instance of a class that implements the
- Furthermore, for all instances of the
Serializableinterface mentioned above, these instances must also: - NOT be an instance of a local class, an anonymous class or an array of a local or anonymous class - be present in the class path of the server