Chapter 17. Remote API
17.1. REST API
- 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.
http://SERVER_ADDRESS:PORT/business-central/rest/REQUEST_BODY
Note
17.1.1. Knowledge Store REST API
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.
17.1.1.1. Job calls
- 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.
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
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
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
OrganizationalUnitinstance and returns aCreateOrganizationalUnitRequestinstance.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
nameandownerfields in the consumedUpdateOrganizationalUnitinstance can be left empty. Both thedescriptionfield 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 provided below:
- [POST] /repositories/{repositoryName}/projects/{projectName}/maven/compile/
- This compiles the project (equivalent to
mvn compile) - [POST]. It consumes aBuildConfiginstance, which must be supplied but is not needed for the operation and may be left blank. It also returns aCompileProjectRequestinstance. - [POST] /repositories/{repositoryName}/projects/{projectName}/maven/install/
- This installs the project (equivalent to
mvn install) - [POST]. It consumes aBuildConfiginstance, which must be supplied but is not needed for the operation and may be left blank. It also returns aInstallProjectRequestinstance. - [POST] /repositories/{repositoryName}/projects/{projectName}/maven/test/
- This compiles and runs the tests - [POST]. It consumes a
BuildConfiginstance and returns aTestProjectRequestinstance. - [POST] /repositories/{repositoryName}/projects/{projectName}/maven/deploy/
- This deploys the project (equivalent to mvn deploy) - [POST]. It consumes a
BuildConfiginstance, which must be supplied but is not needed for the operation and may be left blank. It also returns aDeployProjectRequestinstance.
17.1.2. Deployment REST API
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
[\w\.-]+(:[\w\.-]+){2,2}(:[\w\.-]*){0,2}
- [A-Z]
- [a-z]
- [0-9]
- _
- .
- -
- Group Id
- Artifact Id
- Version
- kbase Id (optional)
- ksession Id (optional)
17.1.2.1. Asynchronous calls
/deployment/{deploymentId}/deploy/deployment/{deploymentId}/undeploy
- 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
- [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
- 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
activate and deactivate operations:
- The
deactivateoperation 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
activateoperation to reactivate the deployment. A deployment is always "activated" by default when it is initially deployed.
17.1.3. Runtime REST API
? 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.
map_ keyword; for example,
map_age=5000
{ "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/'
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());
}task, consider using the execute call (refer to Section 17.1.5, “Execute Operations”).
17.1.3.1. Usage Information
17.1.3.1.1. Pagination
pageorp- number of the page to be returned (by default set to
1, that is, page number1is returned) pageSizeors- number of items per page (default value
10)
/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
\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
startProcess command in the execute call; refer to Section 17.1.5, “Execute Operations”).
17.1.3.2. Runtime calls
/runtime/{deploymentId}/execute/{CommandObject}; refer to Section 17.1.5, “Execute Operations”).
17.1.3.2.1. Process calls
/runtime/{deploymentId}/process/ calls are send to the Process Execution Engine.
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
processDefIdexists, and if it does, returns a URL to show the form as aJaxbProcessInstanceFormResponseon 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
signal/ calls send a signal defined by the provided query map parameters either to the deployment or to a particular process instance.
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
signalparameter value is used as the name of the signal. This parameter is required.- Theeventparameter 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 theksession.signal("signalName", eventValue)method.
17.1.3.2.3. Work item calls
/runtime/{deploymentId}/workitem/ calls allow you to complete or abort a particular work item.
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
/history/ calls administer logs of process instances, their nodes, and process variables.
Note
/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.
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
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
/runtime/{deploymentId}/withvars/ calls allow you to work with Process variables. Note that all variable values are returned as strings in the JaxbVariablesResponse object.
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
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
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).
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
task/content/{contentId: \\d+} and task/{taskId: \\d+}/content operations return the serialized content associated with the given task.
org.jbpm.services.task.utils.ContentMarshallerHelper class.
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.
- The requested objects are instances of a class that implements the
Serializableinterface. In the case of Map objects, they only contain values that implement theSerializableinterface. - 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
/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
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,CompletedorFailed);taskOwner: returns tasks assigned to the particular user (Created,Ready,Reserved,InProgress,Suspended,Completed,Failed,Error,Exited, orObsolete).processInstanceId: returns tasks generated by the Process instance.union: specifies whether the query should query the union or intersection of the parameters.
Example 17.18. Query usage
http://server:port/rest/task/query?workItemId=3&workItemId=4&workItemId=5
http://server:port/rest/task/query?workItemId=11&taskId=27
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
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
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
Created` or `Ready`.
http://server:port/rest/task/query?status=created&status=ready&potentialOwner=bob&processInstanceId=201
- process instance id 201, potential owner `bob`, status `Ready`
- process instance id 201, potential owner `bob`, status `Created`
- 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
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.
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
17.1.4.1. URL Layout
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 variables17.1.4.2. Query Parameters
- "query parameters" are strings like
processInstanceId,taskIdandtid. 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,29andharry.
http://localhost:8080/business-central/rest/query/runtime/process?processId=org.process.frombulator&piid=29
Example 17.19. Repeated query parameters
processId=org.example.process&processInstanceId=27&processInstanceId=29
- 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
- can be given in ranges have an
Xin the min/max column in the table below. - use regular expressions have an
Xin the regex column below.
17.1.4.2.2. Range Query Parameters
_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.
Example 17.20. Range parameters
processId=org.example.process&taskId_min=50&taskId_max=53
- 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.
processId=org.example.process&taskId_min=52
- 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
_re to the end of the parameter name.
*means 0 or more characters.means 1 character
\) is not interpreted.
Example 17.21. Regular expression parameters
processId_re=org.example.*&processVersion=2.0
- only contains information about process instances associated with a process definition whose name matches the regular expression org.example.*. This includes:
org.example.processorg.example.process.definition.example.long.nameorgXexampleX
- only contains information about process instances that have a process (definition) version of 2.0
17.1.4.3. Parameter Table
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
|
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)
|
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
var_myVar=value3 queries for process instances with variables4 that are called myVar and that have the value value3
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.
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
- a list of process instance info (JaxbQueryProcessInstanceInfo) objects
- or a list of task instance info (JaxbQueryTaskInfo) objects
- a process instance object
- a list of 0 or more variable objects
- 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
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”.
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.
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
/runtimeor/taskendpoints
execute operations in cases when you are running any other client besides Java.
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));
}
}
Kie-Deployment-Id that is also available using the Java constant JaxbSerializationProvider.EXECUTE_DEPLOYMENT_ID_HEADER.
/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.
/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.
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>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.
17.1.5.1. Execute Operation Commands
execute operation accepts. See the constructor and set methods on the actual command classes for further information about which parameters these commands accept.
| AbortWorkItemCommand | SignalEventCommand |
| CompleteWorkItemCommand | StartCorrelatedProcessCommand |
| GetWorkItemCommand | StartProcessCommand |
| AbortProcessInstanceCommand | GetVariableCommand |
| GetProcessIdsCommand | GetFactCountCommand |
| GetProcessInstanceByCorrelationKeyCommand | GetGlobalCommand |
| GetProcessInstanceCommand | GetIdCommand |
| GetProcessInstancesCommand | FireAllRulesCommand |
| SetProcessInstanceVariablesCommand |
| 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 |
| ClearHistoryLogsCommand | FindSubProcessInstancesCommand |
| FindActiveProcessInstancesCommand | FindSubProcessInstancesCommand |
| FindNodeInstancesCommand | FindVariableInstancesByNameCommand |
| FindProcessInstanceCommand | FindVariableInstancesCommand |
| FindProcessInstancesCommand |
17.1.6. REST summary
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:
|
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
web.xml.
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 |

Where did the comment section go?
Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.