Chapter 17. Remote API

17.1. REST API

Representational State Transfer (REST) is a style of software architecture of distributed systems (applications). It allows for a highly abstract client-server communication: clients initiate requests to servers to a particular URL with parameters if needed and servers process the requests and return appropriate responses based on the requested URL. The requests and responses are built around the transfer of representations of resources. A resource can be any coherent and meaningful concept that may be addressed (such as a repository, a Process, a Rule, etc.).
Red Hat JBoss BPM Suite and Red Hat JBoss BRMS provide REST API for individual application components. The REST API implementations differ slightly:
  • Knowledge Store (Artifact Repository) REST API calls are calls to the static data (definitions) and are asynchronous, that is, they continue running after the call as a job. These calls return a job ID, which can be used after the REST API call was performed to request the job status and verify whether the job finished successfully. Parameters of these calls are provided in the form of JSON entities.
    The following two API's are only available in Red Hat JBoss BPM Suite.
  • Deployment REST API calls are asynchronous or synchronous, depending on the operation performed. These calls perform actions on the deployments or retrieve information about one ore more deployments.
  • Runtime REST API calls are calls to the Execution Server and to the Process Execution Engine, Task Execution Engine, and Business Rule Engine. They are synchronous and return the requested data as JAXB objects.
All REST API calls use the following URL with the request body: http://SERVER_ADDRESS:PORT/business-central/rest/REQUEST_BODY

Note

Note that it is not possible to issue REST API calls over project resources, such as, rules files, work item definitions, process definition files, etc. are not supported. Perform operation over such files with Git and its REST API directly.

17.1.1. Knowledge Store REST API

REST API calls to Knowledge Store allow you to manage the Knowledge Store content and manipulate the static data in the repositories of the Knowledge Store.
The calls are asynchronous; that is, they continue their execution after the call was performed as a job. All POST and DELETE return details of the request as a well as a job id that can be used to request the job status and verify whether the job finished successfully. The GET operations return information about repositories, projects and organizational units.
Parameters and results of these calls are provided in the form of JSON entities.

17.1.1.1. Job calls

Most Knowledge Store REST calls return a job ID after it is sent. This is necessary as the calls are asynchronous and you need to be able to reference the job to check its status as it goes through its lifecycle. During its lifecycle, a job can have the following statuses:
  • ACCEPTED: the job was accepted and is being processed.
  • BAD_REQUEST: the request was not accepted as it contained incorrect content.
  • RESOURCE_NOT_EXIST: the requested resource (path) does not exist.
  • DUPLICATE_RESOURCE: the resource already exists.
  • SERVER_ERROR: an error on the server occurred.
  • SUCCESS: the job finished successfully.
  • FAIL: the job failed.
  • APPROVED: the job was approved.
  • DENIED: the job was denied.
  • GONE: the job ID could not be found.
    A job can be GONE in the following cases:
    • The job was explicitly removed.
    • The job finished and has been deleted from the status cache (the job is removed from status cache after the cache has reached its maximum capacity).
    • The job never existed.
The following job calls are provided:
[GET]   /jobs/{jobID}
returns the job status - [GET]

Example 17.1. Response of the job call on a repository clone request

"{"status":"SUCCESS","jodId":"1377770574783-27","result":"Alias: testInstallAndDeployProject, Scheme: git, Uri: git://testInstallAndDeployProject","lastModified":1377770578194,"detailedResult":null}"
[DELETE]   /jobs/{jobID}
removes the job - [DELETE]

17.1.1.2. Repository calls

Repository calls are calls to the Knowledge Store that allow you to manage its Git repositories and their projects.
The following repositories calls are provided:
[GET]   /repositories
This returns a list of the repositories in the Knowledge Store as a JSON entity - [GET]

Example 17.2. Response of the repositories call

[{"name":"bpms-assets","description":"generic assets","userName":null,"password":null,"requestType":null,"gitURL":"git://bpms-assets"},{"name":"loanProject","description":"Loan processes and rules","userName":null,"password":null,"requestType":null,"gitURL":"git://loansProject"}]
[GET]   /repositories/{repositoryName}
This returns information on a specific repository - [GET]
[DELETE]   /repositories/{repositoryName}
This deletes the repository - [DELETE]
[POST]   /repositories/
This creates or clones the repository defined by the JSON entity - [POST]

Example 17.3. JSON entity with repository details of a repository to be cloned

{"name":"myClonedRepository", "description":"", "userName":"", "password":"", "requestType":"clone", "gitURL":"git://localhost/example-repository"}
[GET]   /repositories/{repositoryName}/projects/
This returns a list of the projects in a specific repository as a JSON entity - [POST]

Example 17.4. JSON entity with details of existing projects

[ {
  "name" : "my-project-name",
  "description" : "Project to illustrate REST output",
  "groupId" : "com.acme",
  "version" : "1.0"
}, {
  "name" : "yet-another-project-name",
  "description" : "Yet Another Project to illustrate REST output",
  "groupId" : "com.acme",
  "version" : "2.2.1"
} ]
[POST]   /repositories/{repositoryName}/projects/
This creates a project in the repository - [POST]

Example 17.5. Request body that defines the project to be created

"{"name":"myProject","description": "my project"}"
[DELETE]   /repositories/{repositoryName}/projects/
This deletes the project in the repository - [DELETE]

Example 17.6. Request body that defines the project to be deleted

"{"name":"myProject","description": "my project"}"

17.1.1.3. Organizational unit calls

Organizational unit calls are calls to the Knowledge Store that allow you to manage its organizational units.
The following organizationalUnits calls are provided:
[GET]   /organizationalunits/
This returns a list of all the organizational units - [GET].

Example 17.7. Organizational unit list in JSON

[ {
  "name" : "EmployeeWage",
  "description" : null,
  "owner" : "Employee",
  "defaultGroupId" : "org.bpms",
  "repositories" : [ "EmployeeRepo", "OtherRepo" ]
}, {
  "name" : "OrgUnitName",
  "description" : null,
  "owner" : "OrgUnitOwner",
  "defaultGroupId" : "org.group.id",
  "repositories" : [ "repository-name-1", "repository-name-2" ]
} ]
[GET]   /organizationalunits/{organizationalUnitName}
This returns a JSON entity with info about a specific organizational unit - [GET].
[POST]   /organizationalunits/
This creates an organizational unit in the Knowledge Store - [POST]. The organizational unit is defined as a JSON entity. This consumes an OrganizationalUnit instance and returns a CreateOrganizationalUnitRequest instance.

Example 17.8. Organizational unit in JSON

{
  "name":"testgroup",
  "description":"",
  "owner":"tester",
  "repositories":["testGroupRepository"]
}
[POST]   /organizationalunits/{organizationalUnitName}
This updates the details of an existing organizational unit - [POST].
Both the name and owner fields in the consumed UpdateOrganizationalUnit instance can be left empty. Both the description field and the repository association can not be updated via this operation.

Example 17.9. Update organizational unit input in JSON

{
  "owner" : "NewOwner",
  "defaultGroupId" : "org.new.default.group.id"
}
[DELETE]   /organizationalunits/{organizationalUnitName}
This deletes an organizational unit - [GET].
[POST]   /organizationalunits/{organizationalUnitName}/repositories/{repositoryName}
This adds the repository to the organizational unit - [POST].
[DELETE]   /organizationalunits/{organizationalUnitName}/repositories/{repositoryName}
This removes a repository from the organizational unit - [POST].

17.1.1.4. Maven calls

Maven calls are calls to a Project in the Knowledge Store that allow you to compile and deploy the Project resources.
The following maven calls are provided below:
[POST]   /repositories/{repositoryName}/projects/{projectName}/maven/compile/
This compiles the project (equivalent to mvn compile) - [POST]. It consumes a BuildConfig instance, which must be supplied but is not needed for the operation and may be left blank. It also returns a CompileProjectRequest instance.
[POST]   /repositories/{repositoryName}/projects/{projectName}/maven/install/
This installs the project (equivalent to mvn install) - [POST]. It consumes a BuildConfig instance, which must be supplied but is not needed for the operation and may be left blank. It also returns a InstallProjectRequest instance.
[POST]   /repositories/{repositoryName}/projects/{projectName}/maven/test/
This compiles and runs the tests - [POST]. It consumes a BuildConfig instance and returns a TestProjectRequest instance.
[POST]   /repositories/{repositoryName}/projects/{projectName}/maven/deploy/
This deploys the project (equivalent to mvn deploy) - [POST]. It consumes a BuildConfig instance, which must be supplied but is not needed for the operation and may be left blank. It also returns a DeployProjectRequest instance.

17.1.2. Deployment REST API

The kieModule jar files can be deployed or undeployed using the UI or REST API calls. This section details about the REST API deployment calls and their components.
Additionally, starting with the 6.1 release, the activate and deactivate operations are available. When a deployment is deployed, it is "activated" by default: that means that new process instances can be started using the process definitions and other information in the deployment. However, at later point in time, users may want to make sure that a deployment is no longer used without necessarily aborting or stopping the existing (running) process instances. In order to do this, the deployment can first be deactivated before it is removed at a later date.

Note

Configuration options like the runtime strategy should be defined before deploying the JAR files and cannot be changed post deployment.
A standard regular expression for a deploymentid call is:
  	[\w\.-]+(:[\w\.-]+){2,2}(:[\w\.-]*){0,2}
Where the "\w" refers to a character set that can contain the following character sets:
  • [A-Z]
  • [a-z]
  • [0-9]
  • _
  • .
  • -
Following are the elements of a Deployment ID and are separated from each other by a (:) character:
  1. Group Id
  2. Artifact Id
  3. Version
  4. kbase Id (optional)
  5. ksession Id (optional)

17.1.2.1. Asynchronous calls

Deployment calls perform 2 [POST] asynchronous REST operations:
  1. /deployment/{deploymentId}/deploy
  2. /deployment/{deploymentId}/undeploy
Asynchronous calls can allow a user to issue a request and jump to the next task before the previous task in the queue is finished. So the information received after posting a call does not reflect the actual state or eventual status of the operation. This returns a status 202 upon the completion of the request which says that "The request has been accepted for processing, but the processing has not been completed.".
This even means that:
  • The posted request would have been successfully accepted but the actual operation (deploying or undeploying the deployment unit) may have failed.
  • The deployment information retrieved on calling the GET operations may even have changed (including the status of the deployment unit).

17.1.2.2. Deployment calls

The following deployment calls are provided:
[GET] /deployment/
returns a list of all available deployed instances [GET]
[GET] /deployment/{deploymentId}
Returns a JaxbDeploymentUnit instance containing the information (including the configuration) of the deployment unit [GET]
[POST] /deployment/{deploymentId}/deploy
Deploys the deployment unit which is referenced by the deploymentid and returns a JaxbDeploymentJobResult instance with the status of the request [POST]
[POST] /deployment/{deploymentId}/undeploy
Undeploys the deployment unit referenced by the deploymentId and returns a JaxbDeploymentJobResult instance with the status of the request [POST]

Note

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 job cache size.
[POST] /deployment/{deploymentId}/activate
Activates a deployment [POST]
[POST] /deployment/{deploymentId}/deactivate
Deactivates a deployment [POST]

Note

How to use the activate and deactivate operations:
  • The deactivate operation ensures that no new process instances can be started with the existing deployment.
  • If users decide that a deactivated deployment should be reactivated (instead of deleted), they can then use the activate operation to reactivate the deployment. A deployment is always "activated" by default when it is initially deployed.

17.1.3. Runtime REST API

Runtime REST API are calls to the Execution Server and to the Process Execution Engine, Task Execution Engine, and Business Rule Engine. As such they allow you to request and manipulate runtime data.
Except the Execute calls, all other REST calls can either use JAXB or JSON
The calls are synchronous and return the requested data as JAXB objects.
While using JSON, the JSON media type ("application/json") should be added to the ACCEPT header of the REST Call.
Their parameters are defined as query string parameters. To add a query string parameter to a runtime REST API call, add the ? symbol to the URL and the parameter with the parameter value; for example, http://localhost:8080/business-central/rest/task/query?workItemId=393 returns a TaskSummary list of all tasks based on the work item with ID 393. Note that parameters and their values are case-sensitive.
Some runtime REST API calls can use a Map parameter, which means that you can submit key-value pairs to the operation using a query parameter prefixed with the keyword map_ keyword; for example,
map_age=5000
is translated as
{ "age" => Long.parseLong("5000") }

Example 17.10. A GET call that returns all tasks to a locally running application using curl

curl -v -H 'Accept: application/json' -u eko 'localhost:8080/kie/rest/tasks/'
To perform runtime REST calls from your Java application you need to create a RemoteRestSessionFactory object and request a newRuntimeEngine() object from the RemoteRestSessionFactory. The RuntimeEngine can be then used to create a KieSession.

Example 17.11. A GET call that returns a task details to a locally running application in Java with the direct tasks/TASKID request

package rest;

import java.io.InputStream;
import java.net.URL;

import javax.xml.bind.JAXBContext;
import javax.xml.transform.stream.StreamSource;

import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.impl.client.DefaultHttpClient;
import org.jboss.resteasy.client.ClientExecutor;
import org.jboss.resteasy.client.ClientRequest;
import org.jboss.resteasy.client.ClientRequestFactory;
import org.jboss.resteasy.client.ClientResponse;
import org.jboss.resteasy.client.core.executors.ApacheHttpClient4Executor;
import org.jboss.resteasy.spi.ResteasyProviderFactory;
import org.kie.api.task.model.Task;
import org.kie.services.client.serialization.jaxb.impl.task.JaxbTaskResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public Task getTaskInstanceInfo(long taskId) throws Exception {
    URL address = new URL(url + "/task/" + taskId);
    ClientRequest restRequest = createRequest(address);

    ClientResponse<JaxbTaskResponse> responseObj = restRequest.get(JaxbTaskResponse.class);
    ClientResponse<InputStream> taskResponse = responseObj.get(InputStream.class);
    JAXBContext jaxbTaskContext = JAXBContext.newInstance(JaxbTaskResponse.class);
    StreamSource source  = new StreamSource(taskResponse.getEntity());
    return jaxbTaskContext.createUnmarshaller().unmarshal(source, JaxbTaskResponse.class).getValue();

}

private ClientRequest createRequest(URL address) {
    return getClientRequestFactory().createRequest(address.toExternalForm());
    }

private ClientRequestFactory getClientRequestFactory() {
    DefaultHttpClient httpClient = new DefaultHttpClient();
    httpClient.getCredentialsProvider().setCredentials(new AuthScope(AuthScope.ANY_HOST,
    AuthScope.ANY_PORT, AuthScope.ANY_REALM), new UsernamePasswordCredentials(userId, password));
    ClientExecutor clientExecutor = new ApacheHttpClient4Executor(httpClient);
    return new ClientRequestFactory(clientExecutor, ResteasyProviderFactory.getInstance());
}
Note that if you want to send multiple commands to an entity, in this case task, consider using the execute call (refer to Section 17.1.5, “Execute Operations”).
While interacting with the Remote API, some classes are to be included in the deployment to enable a user to pass instances of their own classes as parameters to certain operations. REST calls that start with /task often do not contain any information about the associated deployment. In such a case and extra query parameter (deploymentId) is added to the REST call allowing the server to find the appropriate deployment class and deserialize the information passed with the call.

17.1.3.1. Usage Information

17.1.3.1.1. Pagination
The pagination parameters allow you to define pagination of the results a REST call returns. The following pagination parameters are available:
page or p
number of the page to be returned (by default set to 1, that is, page number 1 is returned)
pageSize or s
number of items per page (default value 10)
If both, the long option and the short option, are included in a URL, the longer version of the parameter takes precedence. When no pagination parameters are included, the returned results are not paginated.
Pagination parameters can be applied to the following REST requests:
/task/query
/history/instances
/history/instance/{id: [0-9]+}
/history/instance/{id: [0-9]+}/child
/history/instance/{id: [0-9]+}/node
/history/instance/{id: [0-9]+}/node/{id: [a-zA-Z0-9-:\\.]+}
/history/instance/{id: [0-9]+}/variable/
/history/instance/{id: [0-9]+}/variable/{id: [a-zA-Z0-9-:\\.]+}
/history/process/{id: [a-zA-Z0-9-:\\.]+}

Example 17.12. REST request body with the pagination parameter

/history/instances?page=3&pageSize=20
/history/instances?p=3&s=20
17.1.3.1.2. Object data type parameters
By default, any object parameters provided in a REST call are considered to be Strings. If you need to explicitly define the data type of a parameter of a call, you can do so by adding one of the following values to the parameter:
  • \d+i: Integer
  • \d+l: Long

Example 17.13. REST request body with the Integer mySignal parameter

/rest/runtime/business-central/process/org.jbpm.test/start?map_var1=1234i
Note that the intended use of these object parameters is to define data types of send Signal and Process variable values (consider for example the use in the startProcess command in the execute call; refer to Section 17.1.5, “Execute Operations”).

17.1.3.2. Runtime calls

Runtime REST calls allow you to acquire and manage data related to the runtime environment; you can provide direct REST calls to the Process Engine and Task Engine of the Process Server (refer to the Components section of the Administration and Configuration Guide.
To send calls to other Execution Engine components or issue calls that are not available as direct REST calls, use the generic execute call to runtime (/runtime/{deploymentId}/execute/{CommandObject}; refer to Section 17.1.5, “Execute Operations”).
17.1.3.2.1. Process calls
The REST /runtime/{deploymentId}/process/ calls are send to the Process Execution Engine.
The following process calls are provided:
/runtime/{deploymentId}/process/{processDefId}/start
creates and starts a Process instance of the provided Process definition [POST]
/runtime/{deploymentId}/process/{processDefId}/startform
Checks to see if the process defined by the processDefId exists, and if it does, returns a URL to show the form as a JaxbProcessInstanceFormResponse on a remote application [POST].
/runtime/{deploymentId}/process/instance/{procInstanceID}
returns the details of the given Process instance [GET]
/runtime/{deploymentId}/process/instance/{procInstanceID}/signal
sends a signal event to the given Process instance [POST]
The call accepts query map parameter with the Signal details.

Example 17.14. A local signal invocation and its REST version

ksession.signalEvent("MySignal", "value", 23l);
curl -v -u admin 'localhost:8080/business-central/rest/runtime/myDeployment/process/instance/23/signal?signal=MySignal&event=value'
/runtime/{deploymentId}/process/instance/{procInstanceID}/abort
aborts the Process instance [POST]
/runtime/{deploymentId}/process/instance/{procInstanceID}/variables
returns variable of the Process instance [GET]
Variables are returned as JaxbVariablesResponse objects. Note that the returned variable values are strings.
17.1.3.2.2. Signal calls
The REST signal/ calls send a signal defined by the provided query map parameters either to the deployment or to a particular process instance.
The following signal calls are provided:
/runtime/{deploymentId}/process/instance/{procInstanceID}/signal
sends a signal to the given process instance [POST]
See the previous subsection for an example of this call.
/runtime/{deploymentId}/signal
This operation takes a signal and a event query parameter and sends a signal to the deployment [POST].
- 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 earlier.

Example 17.15. Signal Call Example

/runtime/{deploymentId}/signal?signal={signalCode}
This call is equivalent to the ksession.signal("signalName", eventValue) method.
17.1.3.2.3. Work item calls
The REST /runtime/{deploymentId}/workitem/ calls allow you to complete or abort a particular work item.
The following task calls are provided:
/runtime/{deploymentId}/workitem/{workItemID}/complete
completes the given work item [POST]
The call accepts query map parameters containing information about the results.

Example 17.16. A local invocation and its REST version

Map<String, Object> results = new HashMap<String, Object>();
results.put("one", "done");
results.put("two", 2);
kieSession.getWorkItemManager().completeWorkItem(23l, results);
curl -v -u admin 'localhost:8080/business-central/rest/runtime/myDeployment/workitem/23/complete?map_one=done&map_two=2i'
/runtime/{deploymentId}/workitem/{workItemID}/abort
aborts the given work item [POST]
17.1.3.2.4. History calls
The REST /history/ calls administer logs of process instances, their nodes, and process variables.

Note

While the REST /history/calls specified in 6.0.0.GA of JBoss BPM Suite are still available, as of 6.0.1.GA, the /history/ calls have been made independent of any deployment, which is also reflected in the URLS used.
The following history calls are provided:
/history/clear
clears all process, variable, and node logs [POST]
/history/instances
returns logs of all Process instances [GET]
/history/instance/{procInstanceID}
returns all logs of Process instance (including child logs) [GET]
/history/instance/{procInstanceID}/child
returns logs of child Process instances [GET]
/history/instance/{procInstanceID}/node
returns logs of all nodes of the Process instance [GET]
/history/instance/{procInstanceID}/node/{nodeID}
returns logs of the node of the Process instance [GET]
/history/instance/{procInstanceID}/variable
returns variables of the Process instance with their values [GET]
/history/instance/{procInstanceID}/variable/{variableID}
returns the log of the process instance that have the given variable id [GET]
/history/process/{procInstanceID}
returns the logs of the given Process instance excluding logs of its nodes and variables [GET]
History calls that search by variable
The following REST calls can be used using variables to search process instance, variables and their values.
The REST calls below also accept an optional activeProcesses parameter that limits the selection to information from active process instances.
/history/variable/{varId}
returns the variable logs of the specified process variable [GET]
/history/variable/{varId}/instances
returns the process instance logs for processes that contain the specified process variable [GET]
/history/variable/{varId}/value/{value}
returns the variable logs for specified process variable with the specified value [GET]

Example 17.17. A local invocation and its REST version

auditLogService.findVariableInstancesByNameAndValue("countVar", "three", true);
curl -v -u admin 'localhost:8080/business-central/rest/history/variable/countVar/value/three?activeProcesses=true'
/history/variable/{varId}/value/{value}/instances
returns the process instance logs for process instances that contain the specified process variable with the specified value [GET]
17.1.3.2.5. Calls to process variables
The REST /runtime/{deploymentId}/withvars/ calls allow you to work with Process variables. Note that all variable values are returned as strings in the JaxbVariablesResponse object.
The following withvars calls are provided:
/runtime/{deploymentId}/withvars/process/{procDefinitionID}/start
creates and starts Process instance and returns the Process instance with its variables Note that even if a passed variable is not defined in the underlying Process definition, it is created and initialized with the passed value. [POST]
/runtime/{deploymentId}/withvars/process/instance/{procInstanceID}
returns Process instance with its variables [GET]
/runtime/{deploymentId}/withvars/process/instance/{procInstanceID}/signal
sends signal event to Process instance (accepts query map parameters).

17.1.3.3. Task calls

The REST task calls are send to the Task Execution Engine.
The following task calls are provided:
/task/{taskId: \\d+}
returns the task in JAXB format [GET]
Further call paths are provided to perform other actions on tasks; refer to Section 17.1.3.3.1, “Task ID operations”)
/task/query
returns a TaskSummary list returned [GET]
Further call paths are provided to perform other actions on task/query; refer to Section 17.1.3.3.3, “Query operations”).
/task/content/{contentId: \\d+}
returns the task content in the JAXB format [GET]
For further information, refer to Section 17.1.3.3.2, “Content operations”)
17.1.3.3.1. Task ID operations
The task/{taskId: \\d+}/ACTION calls allow you to execute an action on the given task (if no action is defined, the call is a GET call that returns the JAXB representation of the task).
The following actions can be invoked on a task using the call:

Table 17.1. Task Actions

Task Action
activate activate task (taskId as query param)
claim claim task [POST] (The user used in the authentication of the REST url call claims it.)
claimnextavailable claim next available task [POST] (This operation claims the next available task assigned to the user.)
complete complete task [POST] (accepts "query map parameters".)
delegate delegate task [POST] (Requires a targetIdquery parameter, which identifies the user to which the task is delegated.)
exit exit task [POST]

Note

The exit operation can be performed by any user or group specified as the administrator of a human task. If the task does not specify any values, the system automatically adds user Administrator and group Administrators to a task.
fail fail task [POST]
forward forward task [POST]
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] (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.)
17.1.3.3.2. Content operations
The task/content/{contentId: \\d+} and task/{taskId: \\d+}/content operations return the serialized content associated with the given task.
The content associated with a task is stored in the human-task database schema in serialized form either as a string with XML content or a map with several different key-value pairs. The content is serialized using the protobuf based algorithm. This serialization process is normally carried out by the static methods in the org.jbpm.services.task.utils.ContentMarshallerHelper class.
If the client that call the REST operation do not have access to the org.jbpm.services.task.utils.ContentMarshallerHelper class, they cannot deserialize the task content. When using the REST call to obtain task content, the content is first deserialized usint the ContentMarshallerHelper class and then serialized with the common Java serialization mechanism.
Due to restrictions of REST operations, only the objects for which the following is true can be returned to the task content operations:
  • The requested objects are instances of a class that implements the Serializable interface. In the case of Map objects, they only contain values that implement the Serializable interface.
  • The objects are not instances of a local class, an anonymous class or arrays of a local or anonymous class.
  • The object classes are present on the class path of the server .
17.1.3.3.3. Query operations
The /task/query call is a GET call that returns a TaskSummary list of the tasks that meet the criteria defined in the call parameters. Note that you can use the pagination feature to define the amount of data to be return.
Parameters
The following parameters can be used with the task/query call:
  • workItemId: returns only tasks based on the work item.
  • taskId: returns only the task with the particular ID.
  • businessAdministrator: returns task with an identified business administrator.
  • potentialOwner: returns tasks that can be claimed by the potentialOwner user.
  • status: returns tasks that are in the given status (Created, Ready, Reserved, InProgress, Completed or Failed);
  • taskOwner: returns tasks assigned to the particular user (Created, Ready, Reserved, InProgress, Suspended, Completed, Failed, Error, Exited, or Obsolete).
  • processInstanceId: returns tasks generated by the Process instance.
  • union: specifies whether the query should query the union or intersection of the parameters.
At the moment, although the name of a parameter is interpreted regardless of case, please make sure use the appropriate case for the values of the parameters.

Example 17.18. Query usage

This call retrieves the task summaries of all tasks that have a work item id of 3, 4, or 5. If you specify the same parameter multiple times, the query will select tasks that match any of that parameter.
  • http://server:port/rest/task/query?workItemId=3&workItemId=4&workItemId=5
The next call will retrieve any task summaries for which the task id is 27 and for which the work item id is 11. Specifying different parameters will result in a set of tasks that match both (all) parameters.
  • http://server:port/rest/task/query?workItemId=11&taskId=27
The next call will retrieve any task summaries for which the task id is 27 or the work item id is 11. While these are different parameters, the union parameter is being used here so that the union of the two queries (the work item id query and the task id query) is returned.
  • http://server:port/rest/task/query?workItemId=11&taskId=27&union=true
The next call will retrieve any task summaries for which the status is `Created` and the potential owner of the task is `Bob`. Note that the letter case for the status parameter value is case-insensitve.
  • http://server:port/rest/task/query?status=creAted&potentialOwner=Bob
The next call will return any task summaries for which the status is `Created` and the potential owner of the task is `bob`. Note that the potential owner parameter is case-sensitive. `bob` is not the same user id as `Bob`!
  • http://server:port/rest/task/query?status=created&potentialOwner=bob
The next call will return the intersection of the set of task summaries for which the process instance is 201, the potential owner is `bob` and for which the status is `Created` or `Ready`.
  • http://server:port/rest/task/query?status=created&status=ready&potentialOwner=bob&processInstanceId=201
That means that the task summaries that have the following characteristics would be included:
  • process instance id 201, potential owner `bob`, status `Ready`
  • process instance id 201, potential owner `bob`, status `Created`
And that following task summaries will not be included:
  • process instance id 183, potential owner `bob`, status `Created`
  • process instance id 201, potential owner `mary`, status `Ready`
  • process instance id 201, potential owner `bob`, status `Complete`
Usage
The parameters can be used by themselves or in certain combinations. If an unsupported parameter combination is used, the system returns an empty list.
You can use certain parameters multiple times with different values: the returned result will contain the union of the entities that met at least one of the defined parameter value. This applies to the workItemId, taskId, businessAdministrator, potentialOwner, taskOwner, and processInstanceId. If entering the status parameter multiple times, the intersection of tasks that have any of the status values and union of tasks that satisfy the other criteria.
Note that the language parameter is required and if not defined the en-UK value is used. The parameter can be defined only once.

17.1.4. The REST Query API

The REST Query API allows developers to richly query tasks, variables and process instances.
The results for both operations are organized around the process instance. For example, when querying tasks, the results will be organized so that the variables and tasks returned are grouped by which process instance they belong to.

17.1.4.1. URL Layout

The rich query operations can be reached via the following URLs:
http://server.address:port/{application-id}/rest/query/
  runtime
    task                     * [GET] rich query for task summaries and process variables
    process                  * [GET] rich query for process instances and process variables
Both URL's take a number of different query parameters. See the next section for a description of these.

17.1.4.2. Query Parameters

In the documentation below,
  • "query parameters" are strings like processInstanceId, taskId and tid. The case (lowercase or uppercase) of these parameters does not matter, except when the query parameter also specifies the name of a user-defined variable.
  • "parameters" are the values that are passed with some query parameters. These are values like org.process.frombulator, 29 and harry.
When you submit a REST call to the query operation, your URL will look something like this:
http://localhost:8080/business-central/rest/query/runtime/process?processId=org.process.frombulator&piid=29
A query containing multiple different query parameters will search for the intersection of the given parameters.
However, many of the query parameters described below can be entered multiple times: when multiple values are given for the same query parameter, the query will then search for any results that match one or more of the values entered.

Example 17.19. Repeated query parameters

The following process instance query:
processId=org.example.process&processInstanceId=27&processInstanceId=29
will return a result that
  • only contains information about process instances with the org.example.process process definition
  • only contains information about process instances that have an id of 27 or 29
17.1.4.2.1. Range and Regular Expression Parameters
Some query criteria can be given in ranges while for others, a simple regular expression language can be used to describe the value.
Query parameters that
  • can be given in ranges have an X in the min/max column in the table below.
  • use regular expressions have an X in the regex column below.
17.1.4.2.2. Range Query Parameters
In order to pass the lower end or start of a range, add _min to end of the parameter name. In order to pass the upper end or end of a range, add _max to end of the parameter name.
Range ends are inclusive.
Only passing one end of the range (the lower or upper end), results in querying on an open ended range.

Example 17.20. Range parameters

The following task query:
processId=org.example.process&taskId_min=50&taskId_max=53
will return a result that
  • only contains information about tasks associated with the org.example.process process definition
  • only contains information about tasks that have a task id between 50 and 53, inclusive.
While the following task query:
processId=org.example.process&taskId_min=52
will return a result that
  • only contains information about tasks associated with the org.example.process process definition
  • only contains information about tasks that have a task id that is larger than or equal to 52
17.1.4.2.3. Regular Expression Query Parameters
In order to apply regular expressions to a query parameter, add _re to the end of the parameter name.
The regular expression language contains 2 special characters:
  • * means 0 or more characters
  • . means 1 character
The slash character (\) is not interpreted.

Example 17.21. Regular expression parameters

The following process instance query
processId_re=org.example.*&processVersion=2.0
will return a result that
  • only contains information about process instances associated with a process definition whose name matches the regular expression org.example.*. This includes:
    • org.example.process
    • org.example.process.definition.example.long.name
    • orgXexampleX
  • only contains information about process instances that have a process (definition) version of 2.0

17.1.4.3. Parameter Table

The task or process column describes whether or not a query parameter can be used with the task and/or the process instance query operations.

Table 17.2. Query Parameters

parameter short form description regex min / max task or process
processinstanceid
piid
Process instance id
 
X
T,P
processid
pid
Process id
X
 
T,P
workitemid
wid
Work item id
  
T,P
deploymentid
did
Deployment id
X
 
T,P
taskid
tid
Task id
 
X
T
initiator
init
Task initiator/creator
X
 
T
stakeholder
stho
Task stakeholder
X
 
T
potentialowner
po
Task potential owner
X
 
T
taskowner
to
Task owner
X
 
T
businessadmin
ba
Task business admin
X
 
T
taskstatus
tst
Task status
  
T
processinstancestatus
pist
Process instance status
  
T,P
processversion
pv
Process version
X
 
T,P
startdate
stdt
Process instance start date1
 
X
T,P
enddate
edt
Process instance end date1
 
X
T,P
varid
vid
Variable id
X
 
T,P
varvalue
vv
Variable value
X
 
T,P
var
var
Variable id and value 2
  
T,P
varregex
vr
Variable id and value 3
X
 
T,P
all
all
Which variable history logs 4
  
T,P
[1] The date operations take strings with a specific date format as their values: yy-MM-dd_HH:mm:ss. However, users can also submit only part of the date:
  • Submitting only the date (yy-MM-dd) means that a time of 00:00:00 is used (the beginning of the day).
  • Submitting only the time (HH:mm:ss) means that the current date is used.

Table 17.3. Example date strings

Date str ing Actual meaning
15-05-29_13:40:12
May 29th, 2015, 13:40:12 (1:40:12 PM)
14-11-20
November 20th, 2014, 00:00:00
9:30:00
Today, 9:30:00 (AM)
For the format used, see the SimpleDateFormat documentation.
[2] The var query parameter is used differently than other parameters. If you want to specify both the variable id and value of a variable (as opposed to just the variable id), then you can do it by using the var query parameter. The syntax is var_<variable-id>=<variable-value>

Example 17.22.  var_X=Y example

The query parameter and parameter pair var_myVar=value3 queries for process instances with variables4 that are called myVar and that have the value value3
[3] The varreggex (or shortened version vr) parameter works similarly to the var query parameter. However, the value part of the query parameter can be a regular expression.
[4] By default, only the information from most recent (last) variable instance logs is retrieved. However, users can also retrieve all variable instance logs (that match the given criteria) by using this parameter.

17.1.4.4. Parameter Examples

Table 17.4. Query parameters examples

parameter short form example
processinstanceid
piid
piid=23
processid
pid
processid=com.acme.example
workitemid
wid
wid_max=11
deploymentid
did
did_re=com.willy.loompa.*
taskid
tid
taskid=4
initiator
init
init_re=Davi*
stakeholder
stho
stho=theBoss&stho=theBossesAssistant
potentialowner
po
potentialowner=sara
taskowner
to
taskowner_re=*anderson
businessadmin
ba
ba=admin
taskstatus
tst
tst=Reserved
processinstancestatus
pist
pist=3&pist=4
processversion
pv
processVersion_re=4.2*
startdate
stdt
stdt_min=00:00:00
enddate
edt
edt_max=15-01-01
varid
vid
varid=numCars
varvalue
vv
vv=abracadabra
var
var
var_numCars=10
varregex
vr
vr_nameCar=chitty*
all
all
all

17.1.4.5. Query Output Format

The process instance query returns a JaxbQueryProcessInstanceResult instance.
The task query returns a JaxbQueryTaskResult instance.
Results are structured as follows:
A JaxbQueryProcessInstanceInfo object contains:
  • a process instance object
  • a list of 0 or more variable objects
A JaxbQueryTaskInfo info object contains:
  • the process instance id
  • a list of 0 or more task summary obejcts
  • a list of 0 or more variable objects

17.1.5. Execute Operations

For remote communication, we recommend you to use Java Remote API, which can be obtained from the class org.kie.remote.client.api.RemoteRestRuntimeEngineFactory and is shipped with JBoss BPM Suite. For performing runtime operations (such as, starting a process instance with process variables, or completing a task with task variables) that involves passing a custom Java object used in the process, you can use the approach mentioned in the section Section 17.4.3, “Custom Model Objects and Remote API”.
If for some reason, using Java Remote API is not possible, or if your requirement is to use the Rest API, you may consider using the execute operation. However, the Rest API accepts only String or Integer values as parameters. The execute operation enables you to send complex Java objects to perform JBoss BPM Suite runtime operations.
The execute operations are created in order to support the Java Remote Runtime API. Use the execute operations only in exceptional circumstances such as:
  • When you need to pass complex objects as parameters
  • When it is not possible to use /runtime or /task endpoints
Additionally, you can consider using the execute operations in cases when you are running any other client besides Java.
Let us consider an example, where we are passing a complex object org.MyPOJO as a parameter to start a process:

package com.redhat.gss.jbpm;

import java.io.StringReader;
import java.io.StringWriter;
import java.net.URL;
import java.nio.charset.Charset;
import java.util.ArrayList;
import java.util.List;

import javax.ws.rs.core.MediaType;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Marshaller;
import javax.xml.bind.Unmarshaller;

import org.MyPOJO;
import org.apache.commons.codec.binary.Base64;
import org.jboss.resteasy.client.ClientRequest;
import org.jboss.resteasy.client.ClientRequestFactory;
import org.jboss.resteasy.client.ClientResponse;
import org.kie.api.command.Command;
import org.kie.remote.client.jaxb.JaxbCommandsRequest;
import org.kie.remote.client.jaxb.JaxbCommandsResponse;
import org.kie.remote.jaxb.gen.JaxbStringObjectPairArray;
import org.kie.remote.jaxb.gen.StartProcessCommand;
import org.kie.remote.jaxb.gen.util.JaxbStringObjectPair;
import org.kie.services.client.serialization.JaxbSerializationProvider;
import org.kie.services.client.serialization.jaxb.impl.JaxbCommandResponse;

public class StartProcessWithPOJO {

	  /*
	   * Set the parameters according your installation
	   */
	  private static final String DEPLOYMENT_ID = "org.kie.example:project1:3.0";
	  private static final String PROCESS_ID = "project1.proc_start";
	  private static final String PROCESS_PARAM_NAME = "myPOJO";
	  private static final String APP_URL = "http://localhost:8080/business-central/rest";
	  private static final String USER = "jesuino";
	  private static final String PASSWORD = "redhat2014!";



	    public static void main(String[] args) throws Exception {
	        // List of commands to be executed;
	        List<Command> commands = new ArrayList<Command>();
	        // a sample command to start a process:
	        StartProcessCommand startProcessCommand = new StartProcessCommand();
	        JaxbStringObjectPairArray params = new JaxbStringObjectPairArray();
	        params.getItems().add(new JaxbStringObjectPair(PROCESS_PARAM_NAME, new MyPOJO("My POJO TESTING")));
	        startProcessCommand.setProcessId(PROCESS_ID);
	        startProcessCommand.setParameter(params);
	        commands.add(startProcessCommand);
	        List<JaxbCommandResponse<?>> response = executeCommand(DEPLOYMENT_ID,
	                commands);
	        System.out.printf("Command %s executed.\n", response.toString());
	        System.out.println("commands1" + commands);
	    }

	    static List<JaxbCommandResponse<?>> executeCommand(String deploymentId,
	            List<Command> commands) throws Exception {
	        URL address = new URL(APP_URL + "/execute");
	        ClientRequest request = createRequest(address);


	        request.header(JaxbSerializationProvider.EXECUTE_DEPLOYMENT_ID_HEADER, DEPLOYMENT_ID);
	        JaxbCommandsRequest commandMessage = new JaxbCommandsRequest();
	        commandMessage.setCommands(commands);
	        commandMessage.setDeploymentId(DEPLOYMENT_ID);
	        String body = convertJaxbObjectToString(commandMessage);
	        request.body(MediaType.APPLICATION_XML, body);
	        ClientResponse<String> responseObj = request.post(String.class);
	        String strResponse = responseObj.getEntity();
	        System.out.println("RESPONSE FROM THE SERVER: \n" + strResponse);
	        JaxbCommandsResponse cmdsResp = convertStringToJaxbObject(strResponse);
	        return cmdsResp.getResponses();
	    }

	    static private ClientRequest createRequest(URL address) {
	        return new ClientRequestFactory().createRequest(
	                address.toExternalForm()).header("Authorization",
	                getAuthHeader());
	    }

	    static private String getAuthHeader() {
	        String auth = USER + ":" + PASSWORD;
	        byte[] encodedAuth = Base64.encodeBase64(auth.getBytes(Charset.forName("US-ASCII")));
	        return "Basic " + new String(encodedAuth);
	    }

	    static String convertJaxbObjectToString(Object object) throws JAXBException {
	    	// TODO: Add your classes here
	        Class<?>[] classesToBeBound = { JaxbCommandsRequest.class, MyPOJO.class };
	        Marshaller marshaller = JAXBContext.newInstance(classesToBeBound)
	                .createMarshaller();
	        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
	        StringWriter stringWriter = new StringWriter();
	        marshaller.marshal(object, stringWriter);
	        String output = stringWriter.toString();
	        System.out.println("REQUEST CONTENT: \n" + output);
	        return output;
	    }

	    static JaxbCommandsResponse convertStringToJaxbObject(String str)
	            throws JAXBException {
	        Unmarshaller unmarshaller = JAXBContext.newInstance(
	                JaxbCommandsResponse.class).createUnmarshaller();
	        return (JaxbCommandsResponse) unmarshaller.unmarshal(new StringReader(
	                str));
	    }
}
In this example, the org.kie.remote.jaxb.gen package classes are used for the client, which are in present the org.kie.remote:kie-remote-client artifact. The deployment ID is set using a new HTTP header Kie-Deployment-Id that is also available using the Java constant JaxbSerializationProvider.EXECUTE_DEPLOYMENT_ID_HEADER.
The /execute call takes the JaxbCommandsRequest object as its parameter. The JaxbCommandsRequest object contains a list of org.kie.api.command.Command objects. The commands are stored in the JaxbCommandsRequest object, which are converted to String representation and sent to the execute REST call. The JaxbCommandsRequest parameters are deploymentId and a Command object.
When you send a command to /execute, you use Java code to convert the Command(which is a Java object) to String (which is in the XML format). Once you generate the XML, you can use any Java or non-Java client to send it to a Rest endpoint exposed by Business Central.
Note that it is important that the org.MyPOJO class is the same on both your client code as well as the server side. One way of achieving this is by sharing it through the maven dependency. You can create the org.MyPOJO class using the data modeler tool of Business Central and in your Rest client, import the dependency of the business-central project, which includes this org.MyPOJO class. Here is an example of the pom.xml file with the Business Central project dependency (that contains the org.MyPOJO class) and other required dependencies:
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>org.redhat.gss</groupId>
	<artifactId>sample-rest-client</artifactId>
	<version>1</version>
	<name>Rest Client - Execute</name>

	<properties>
		<version.org.jboss.bom.eap>6.4.4.GA</version.org.jboss.bom.eap>
		<!-- Define the version of brms/bpmsuite core artifacts -->
		<version.org.jboss.bom.brms>6.2.1.GA-redhat-2</version.org.jboss.bom.brms>
		<maven.compiler.target>1.7</maven.compiler.target>
		<maven.compiler.source>1.7</maven.compiler.source>
	</properties>

	<dependencyManagement>
		<dependencies>
			<dependency>
				<groupId>org.jboss.bom.eap</groupId>
				<artifactId>jboss-javaee-6.0-with-resteasy</artifactId>
				<version>${version.org.jboss.bom.eap}</version>
				<type>pom</type>
				<scope>import</scope>
			</dependency>
			<dependency>
				<groupId>org.jboss.bom.brms</groupId>
				<artifactId>jboss-brms-bpmsuite-bom</artifactId>
				<version>${version.org.jboss.bom.brms}</version>
				<type>pom</type>
				<scope>import</scope>
			</dependency>
		</dependencies>
	</dependencyManagement>

	<dependencies>
		<dependency>
			<groupId>org.kie.remote</groupId>
			<artifactId>kie-remote-client</artifactId>
		</dependency>
		<dependency>
			<groupId>org.drools</groupId>
			<artifactId>drools-core</artifactId>
		</dependency>
		<dependency>
			<groupId>org.jboss.resteasy</groupId>
			<artifactId>resteasy-jaxrs</artifactId>
		</dependency>
		<dependency>
			<groupId>commons-logging</groupId>
			<artifactId>commons-logging</artifactId>
			<version>1.2</version>
		</dependency>
		<dependency>
			<groupId>commons-codec</groupId>
			<artifactId>commons-codec</artifactId>
			<version>1.9</version>
		</dependency>
		<!-- STARTING MY BUSINESS CENTRAL PROJECT DEPENDENCY WHICH CONTAINS THE POJO -->
		<dependency>
			<artifactId>ExecuteProject</artifactId>
			<groupId>org.redhat.gss</groupId>
			<version>1.0</version>
		</dependency>
		<!-- ENDING MY BUSINESS CENTRAL PROJECT DEPENDENCY WHICH CONTAINS THE POJO -->
	</dependencies>

</project>
Here, the com.redhat.gss:remote-process-start-with-bean:1.0 is the kjar created by Business Central. This kjar includes the org.MyPOJO class. Therefore by sharing the dependency, you ensure that your org.MyPOJO class on the server matches with that on the client.
Another way to achieve this is to create data model using JBoss Developer Studio, export the JAR file, and add it as a dependency of both Business Central kjar and your Rest client.

17.1.5.1. Execute Operation Commands

The following is a list of commands that the execute operation accepts. See the constructor and set methods on the actual command classes for further information about which parameters these commands accept.
The following is the list of accepted commands used to interact with the process engine:
AbortWorkItemCommand SignalEventCommand
CompleteWorkItemCommand StartCorrelatedProcessCommand
GetWorkItemCommand StartProcessCommand
AbortProcessInstanceCommand GetVariableCommand
GetProcessIdsCommand GetFactCountCommand
GetProcessInstanceByCorrelationKeyCommand GetGlobalCommand
GetProcessInstanceCommand GetIdCommand
GetProcessInstancesCommand FireAllRulesCommand
SetProcessInstanceVariablesCommand  
The following is the list of accepted commands that interact with task instances:
ActivateTaskCommand GetTaskAssignedAsPotentialOwnerCommand
AddTaskCommand GetTaskByWorkItemIdCommand
CancelDeadlineCommand GetTaskCommand
ClaimNextAvailableTaskCommand GetTasksByProcessInstanceIdCommand
ClaimTaskCommand GetTasksByStatusByProcessInstanceIdCommand
CompleteTaskCommand GetTasksOwnedCommand
CompositeCommand NominateTaskCommand
DelegateTaskCommand ProcessSubTaskCommand
ExecuteTaskRulesCommand ReleaseTaskCommand
ExitTaskCommand ResumeTaskCommand
FailTaskCommand SkipTaskCommand
ForwardTaskCommand StartTaskCommand
GetAttachmentCommand StopTaskCommand
GetContentCommand SuspendTaskCommand
GetTaskAssignedAsBusinessAdminCommand  
The following is the list of accepted commands for managing and retrieving historical (audit) information:
ClearHistoryLogsCommand FindSubProcessInstancesCommand
FindActiveProcessInstancesCommand FindSubProcessInstancesCommand
FindNodeInstancesCommand FindVariableInstancesByNameCommand
FindProcessInstanceCommand FindVariableInstancesCommand
FindProcessInstancesCommand  

17.1.6. REST summary

The URL templates in the table below are relative to the following URL:
  • http://server:port/business-central/rest

Table 17.5. Knowledge Store REST calls

URL Template Type Description
/jobs/{jobID} GET return the job status
/jobs/{jobID} DELETE remove the job
/organizationalunits GET return a list of organizational units
/organizationalunits POST
create an organizational unit in the Knowledge Store described by the JSON OrganizationalUnit entity
/organizationalunits/{organizationalUnitName}/repositories/{repositoryName} POST add a repository to an organizational unit
/repositories/ POST
add the repository to the organizational unit described by the JSON RepositoryReqest entity
/repositories GET return the repositories in the Knowledge Store
/repositories/{repositoryName} DELETE remove the repository from the Knowledge Store
/repositories/ POST create or clone the repository defined by the JSON RepositoryRequest entity
/repositories/{repositoryName}/projects/ POST create the project defined by the JSON entity in the repository
/repositories/{repositoryName}/projects/{projectName}/maven/compile/ POST compile the project
/repositories/{repositoryName}/projects/{projectName}/maven/install POST install the project
/repositories/{repositoryName}/projects/{projectName}/maven/test/ POST
compile the project and run tests as part of compilation
/repositories/{repositoryName}/projects/{projectName}/maven/deploy/ POST deploy the project

Table 17.6. runtime REST calls

URL Template Type Description
/runtime/{deploymentId}/process/{procDefID}/start POST start a process instance based on the Process definition (accepts query map parameters)
/runtime/{deploymentId}/process/instance/{procInstanceID} GET return a process instance details
/runtime/{deploymentId}/process/instance/{procInstanceID}/abort POST abort the process instance
/runtime/{deploymentId}/process/instance/{procInstanceID}/signal POST send a signal event to process instance (accepts query map parameters)
/runtime/{deploymentId}/process/instance/{procInstanceID}/variable/{varId} GET return a variable from a process instance
/runtime/{deploymentId}/signal/{signalCode} POST send a signal event to deployment
/runtime/{deploymentId}/workitem/{workItemID}/complete POST complete a work item (accepts query map parameters)
/runtime/{deploymentId}/workitem/{workItemID}/abort POST abort a work item
/runtime/{deploymentId}/withvars/process/{procDefinitionID}/start POST
start a process instance and return the process instance with its variables
Note that even if a passed variable is not defined in the underlying process definition, it is created and initialized with the passed value.
/runtime/{deploymentId}/withvars/process/instance/{procInstanceID}/ GET
return a process instance with its variables
/runtime/{deploymentId}/withvars/process/instance/{procInstanceID}/signal POST
send a signal event to the process instance (accepts query map parameters)
The following query parameters are accepted:
  • The signal parameter specifies the name of the signal to be sent
  • The event parameter specifies the (optional) value of the signal to be sent

Table 17.7. task REST calls

URL Template Type Description
/task/query GET
return a TaskSummary list
/task/content/{contentID} GET
returns the content of a task
/task/{taskID} GET
return the task
/task/{taskID}/activate POST
activate the task
/task/{taskID}/claim POST
claim the task
/task/{taskID}/claimnextavailable POST
claim the next available task
/task/{taskID}/complete POST
complete the task (accepts query map paramaters)
/task/{taskID}/delegate POST
delegate the task
/task/{taskID}/exit POST
exit the task
/task/{taskID}/fail POST
fail the task
/task/{taskID}/forward POST
forward the task
/task/{taskID}/nominate POST
nominate the task
/task/{taskID}/release POST
release the task
/task/{taskID}/resume POST
resume the task (after suspending)
/task/{taskID}/skip POST
skip the task
/task/{taskID}/start POST
start the task
/task/{taskID}/stop POST
stop the task
/task/{taskID}/suspend POST
suspend the task
/task/{taskID}/showTaskForm GET
Generates a URL to show the task form on a remote application as a JaxbTaskFormResponse instance.
/task/{taskID}/content GET
returns the content of a task

Table 17.8. history REST calls

URL Template Type Description
/history/clear/ POST delete all process, node and history records
/history/instances GET return the list of all process instance history records
/history/instance/{procInstId} GET return a list of process instance history records for a process instance
/history/instance/{procInstId}/child GET return a list of process instance history records for the subprocesses of the process instance
/history/instance/{procInstId}/node GET return a list of node history records for a process instance
/history/instance/{procInstId}/node/{nodeId} GET return a list of node history records for a node in a process instance
/history/instance/{procInstId}/variable GET return a list of variable history records for a process instance
/history/instance/{procInstId}/variable/{variableId} GET return a list of variable history records for a variable in a process instance
/history/process/{procDefId} GET return a list of process instance history records for process instances using a given process definition
/history/variable/{varId} GET return a list of variable history records for a variable
/history/variable/{varId}/instances GET return a list of process instance history records for process instances that contain a variable with the given variable id
/history/variable/{varId}/value/{value} GET return a list of variable history records for variable(s) with the given variable id and given value
/history/variable/{varId}/value/{value}/instances GET return a list of process instance history records for process instances with the specified variable that contains the specified variable value

Table 17.9. deployment REST calls

URL Template Type Description
/deployment GET return a list of (deployed) deployments
/deployment/{deploymentId} GET return the status and information about the deployment
/deployment/{deploymentId}/deploy POST
submit a request to deploy a deployment
/deployment/{deploymentId}/undeploy POST
submit a request to undeploy a deployment
/deployment/{deploymentId}/deactivate POST
deactivate a deployment
/deployment/{deploymentId}/activate POST
activate a deployment

Table 17.10. query REST calls

URL Template Type Description
/query/runtime/process GET query process instances and process variables
/query/runtime/task GET query tasks and process variables
/query/task POST
query tasks

17.1.7. Control of the REST API

Red Hat JBoss BPM Suite provides a way to control access when using the REST API by introducing access-restricting user roles. This feature is enabled by default. You can disable it in web.xml.
You can use following roles:

Table 17.11. Available roles, their type and scope of access

Name Type Scope of access
rest-all GET, POST, DELETE All direct REST calls (excluding remote client)
rest-project GET, POST, DELETE Knowledge store REST calls
rest-deployment GET, POST Deployment unit REST calls
rest-process GET, POST Runtime and history REST calls
rest-process-read-only GET Runtime and history REST calls
rest-task GET, POST Task REST calls
rest-task-read-only GET Task REST calls
rest-query GET REST query API calls
rest-client POST Remote client calls