Show Table of Contents
10.6. The REST API for Realtime Decision Server Execution
You can communicate with the Realtime Decision Server through the REST API.
- The base URL for sending requests is the endpoint defined earlier (http://SERVER:PORT/kie-server/services/rest/server/).
- All requests require basic HTTP Authentication for the role kie-server.
Following methods support three formats of the requests: JSON, JAXB, and XSTREAM. You must provide following HTTP headers:
- Accept: application/json or application/xml
- Content-Type: application/json or application/xml
If you want to define the marshaller, provide also
X-KIE-ContentType: has three possible values - JSON, JAXB, or XSTREAM. Set it according to the format of your request to the server.
The examples use the Curl utility. You can use any REST client. Curl commands use the following parameters:
-u: specifies username:password for the Realtime Decision Server authentication.-H: specifies HTTP headers.-X: specifies the HTTP method of the request, that is [GET], [POST], [PUT], or [DELETE].
Note
BRMS Commands endpoints will work only if your Realtime Decision Server has BRM capability. The rest of the endpoints will work only if your Realtime Decision Server has BPM capabilities. Check the following URI for capabilities of your Realtime Decision Server: http://SERVER:PORT/kie-server/services/rest/server.
10.6.1. BRMS Commands
Table 10.2. BRMS Commands Endpoints
| URI | Method | Request Type | Response Type | Description |
|---|---|---|---|---|
| /containers/instances/{containerID} | POST | A single org.drools.core.command.impl.GenericCommand command or multiples commands in BatchExecutionCommand wrapper. | org.kie.server.api.model.ServiceResponse<String> | Executes the commands sent to the specified containerId and returns the commands execution results. For more information, See supported commands below. |
List of supported commands:
For more information about the commands, see the
AgendaGroupSetFocusCommandClearActivationGroupCommandClearAgendaCommandClearAgendaGroupCommandClearRuleFlowGroupCommandDeleteCommandInsertObjectCommandModifyCommandGetObjectCommandInsertElementsCommandFireAllRulesCommandQueryCommandSetGlobalCommandGetGlobalCommandGetObjectsCommandBatchExecutionCommand
org.drools.core.command.runtime package. Alternatively, see Supported JBoss BRMS Commands from the Red Hat JBoss Develompent Guide.
Example 10.1. [POST] Drools Commands Execution
- Change into a directory of your choice and create
commandsRequest.json:{ "lookup" : null, "commands" : [ { "insert" : { "object" : "testing", "disconnected" : false, "out-identifier" : null, "return-object" : true, "entry-point" : "DEFAULT" } }, { "fire-all-rules" : { } } ] } - Execute the following command:
$ curl -X POST -H 'X-KIE-ContentType: JSON' -H 'Content-type: application/json' -u 'kieserver:kieserver1!' --data @commandsRequest.json http://localhost:8080/kie-server/services/rest/server/containers/instances/myContainer
The command generates a request that sends the Insert Object and Fire All Rules commands to the server.Lookupspecifies a ksession configured in your kjar. If you use a null lookup value, the default KIE session will be used.
An example response:
{
"type" : "SUCCESS",
"msg" : "Container hello successfully called.",
"result" : "{\n \"results\" : [ ],\n \"facts\" : [ ]\n}"
}
10.6.2. Managing Processes
Use the following entry point: server/containers/{containerId}/processes. See table Process Management Endpoints for a list of endpoints.
Table 10.3. Process Management Endpoints
| URI | Method | Request Type | Response Type | Description |
|---|---|---|---|---|
| /instances | DELETE | N/A | N/A | Aborts multiple process instances specified by the query parameter instanceId. |
| /instances/{processInstanceId}/signals | GET | N/A | A list of Strings | Returns all the available signal names for processInstanceId as a list of Strings |
| /instances/{processInstanceId}/variable/{varName} | PUT | The variable marshalled value | N/A | Sets the value of variable varName for process instance processInstanceId. If successful, the return value is HTTP code 201. |
| /instances/{processInstanceId}/variable/{varName} | GET | N/A | The variable value | Returns the marshalled value of varName for processInstanceId. |
| /instances/{processInstanceId}/variables | POST | A map with variable names and values | N/A | Sets multiple processInstanceId variables. The request is a map, in which the key is the name of the variable and the value is the new value of the variable. |
| /instances/{processInstanceId}/variables | GET | N/A | A map with the variable names and values | Gets all variables for processInstanceId as a map, in which the key is the name of the variable and the value is the value of the variable |
| /instances/{processInstanceId}/workitems/ | GET | N/A | A list of WorkItemInstance objects | Gets all the work items of the given processInstanceId. |
| /instances/{processInstanceId}/workitems/{workItemId} | GET | N/A | A WorkItemInstance object | Gets the workItemId work item of the given processInstanceId. |
| /instances/{processInstanceId}/workitems/{workItemId}/aborted | PUT | N/A | N/A | Aborts the workItemId work item of the given processInstanceId. If successful, the return value is HTTP code 201. |
| /instances/{processInstanceId}/workitems/{workItemId}/completed | PUT | N/A | N/A | Completes the workItemId work item of the given processInstanceId. If successful, the return value is HTTP code 201. |
| /{processId}/instances | POST | A map with variables used to start the process. | Plain text with the process instance id. | Creates a business process instance specified by processId. Accepted input is a map with the process variables and its values. |
| instances/signal/{signalName} | POST | A marshalled object | N/A | Signals multiple process instances of a query parameter instanceId with signal signalName. You can provide the signal payload marshalled in the request body. |
| instances/{processInstanceId} | DELETE | N/A | N/A | Aborts a process specified by processInstanceId. If successful, the return value is HTTP code 204. |
| instances/{processInstanceId} | GET | N/A | A ProcessInstance object | Returns the details of processInstanceId. You can request variable information by setting the withVars parameter as true. |
| instances/{processInstanceId}/signal/{signalName} | POST | A marshalled object | N/A | Signals the process instance processInstanceId with signal signalName. You can provide the signal payload marshalled in the request body. |
| {processId}/instances/correlation/{correlationKey} | POST | A map with variables used to start the process. | Plain text with the process instance id. | Creates a business process instance specified by the processId with the correlation key correlationKey. Accepted input is a map with the process variables and its values. |
Example 10.2. Managing Processes
- Create
person.js:{ "p" : { "org.kieserver.test.Person": { "id" : 13, "name": "William" } }Start a process using a custom object (Person) as a parameter:$ curl -X POST -u 'kieserver:kieserver1!' -H 'Content-type: application/json' -H 'X-KIE-ContentType: JSON' --data @person.js 'http://localhost:8080/kie-server/services/rest/server/containers/person/processes/proc-with-pojo.p-proc/instances'
- Create a new process instance of process definition
com.sample.rewards-basicwith parameters:$ curl -X POST -u 'kieserver:kieserver1!' -H 'Content-type: application/json' -H 'X-KIE-ContentType: JSON' --data '{"employeeName": "William"}' 'http://localhost:8080/kie-server/services/rest/server/containers/rewards/processes/com.sample.rewards-basic/instances'Returns process instance ID. - Get the variables of process instance
3$ curl -u 'kieserver:kieserver1!' -H 'Accept: application/json' 'http://localhost:8080/kie-server/services/rest/server/containers/rewards/processes/instances/3/variables'
Example response:{ "employeeName" : "William" } - Send a TEST signal to the process instance with ID
5$ curl -X POST -u 'kieserver:kieserver1!' -H 'Content-type: application/json' -H 'X-KIE-ContentType: JSON' --data '"SIGNAL DATA"' 'http://localhost:8080/kie-server/services/rest/server/containers/test/processes/instances/signal/TEST?instanceId=5'
10.6.3. Managing Process Definitions
Use the following entry point: server/containers/{containerId}/processes/definitions. See table Process Queries Endpoints for a list of endpoints. To use pagination, use the
page and pageSize parameters.
Table 10.4. Process Queries Endpoints
| URI | Method | Request Type | Response Type | Description |
|---|---|---|---|---|
| / | GET | N/A | A list of ProcessDefinition objects | Returns a list of process definitions available for the container containerId |
| /{processId}/variables | GET | N/A | A VariablesDefinition object | Returns a map of the variable definitions for processId. The map contains the name of the variable and its type. |
| /{processId}/tasks/service | GET | N/A | A ServiceTaskDefinition object | Returns all service tasks for processId. The return value is a map with the names and types of the service tasks. If no tasks are found, the return value is an empty list. |
| /{processId}/tasks/users | GET | N/A | A list of UserTaskDefinition objects | Returns all the user tasks for processId. The response also contains maps of the input and output parameters. The key is the name and the value is the type of a parameter. |
| /{processId}/subprocesses | GET | N/A | A SubProcessDefinition object | Returns a list of reusable sub-process IDs for processId. |
| /{processId}/entities | GET | N/A | An AssociatedEntitiesDefinition object | Returns a map with the entities associated with processId. |
| /{processId}/tasks/users/{taskName}/inputs | GET | N/A | A TaskInputsDefinition object | Returns a map with all the task input parameter definitions for taskName of processId. The key is the name of the input and the value is its type. |
| /{processId}/tasks/users/{taskName}/outputs | GET | N/A | A TaskOutputsDefinition object | Returns a map with all the task output parameter definitions for taskName of processId. The key is the name of the input and the value is its type. |
Example 10.3. [GET] Process Definitions for a Specified Container
The following command displays process definitions for the
rewards container and uses pagination:
$ curl -u 'kieserver:kieserver1!' -H 'accept: application/json' 'http://localhost:8080/kie-server/services/rest/server/queries/containers/instances/rewards/processes/definitions?page=0&pageSize=1000'
An example response:
{
"processes" : [ {
"process-id" : "com.sample.rewards-basic",
"process-name" : "Rewards Basic",
"process-version" : "1",
"package" : "com.sample",
"container-id" : "rewards"
} ]
}
Example 10.4. [GET] User Tasks for a Specified Process
The following command displays user tasks for the the
com.sample.rewards-basic process in the rewards container:
$ curl -u 'kieserver:kieserver1!' -H 'accept: application/json' 'http://localhost:8080/kie-server/services/rest/server/containers/instances/rewards/processes/definitions/com.sample.rewards-basic/tasks/users'
An example response:
{
"task" : [ {
"task-name" : "Approval by PM",
"task-priority" : 0,
"task-skippable" : false,
"associated-entities" : [ "PM" ],
"task-inputs" : {
"Skippable" : "Object",
"TaskName" : "java.lang.String",
"GroupId" : "Object"
},
"task-outputs" : {
"_approval" : "Boolean"
}
}, {
"task-name" : "Approval by HR",
"task-priority" : 0,
"task-skippable" : false,
"associated-entities" : [ "HR" ],
"task-inputs" : {
"Skippable" : "Object",
"TaskName" : "java.lang.String",
"GroupId" : "Object"
},
"task-outputs" : {
"_approval" : "Boolean"
}
} ]
}
Example 10.5. [GET] Variable Definitions for Specified Process
The following command displays the variable definitions of the
com.sample.rewards-basic process in the rewards container:
$ curl -u 'kieserver:kieserver1!' -H 'accept: application/json' 'http://localhost:8080/kie-server/services/rest/server/containers/instances/rewards/processes/definitions/com.sample.rewards-basic/variables'
An example response:
{
"variables" : {
"result" : "String",
"hrApproval" : "Boolean",
"pmApproval" : "Boolean",
"employeeName" : "String"
}
}
10.6.4. Managing User Tasks
Use this base URI: server/containers/{containerId}/tasks.
10.6.4.1. Managing Task Instances
Use this base URI: server/containers/{containerId}/tasks/{taskId}/states/. If successful, the return value is HTTP code 201. See table Task Instance Endpoints for a list of endpoints.
Table 10.5. Task Instance Endpoints
| URI | Method | Request Type | Response Type | Description |
|---|---|---|---|---|
| activated | PUT | N/A | N/A | Activates the taskId task. |
| claimed | PUT | N/A | N/A | Claims the taskId task. |
| started | PUT | N/A | N/A | Starts the taskId task. |
| stopped | PUT | N/A | N/A | Stops the taskId task. |
| completed | PUT | A map with the output parameters name/value | N/A | Completes the taskId task. You can provide the output parameters in form of a map, where the key is the parameter name and the value is the value of the output parameter. |
| delegated | PUT | N/A | N/A | Delegates the taskId task to a user provided by the targetUser query parameter. |
| exited | PUT | N/A | N/A | Exits the taskId task. |
| failed | PUT | N/A | N/A | Fails the taskId task. |
| forwarded | PUT | N/A | N/A | Forwards the taskId task to the user provided by the targetUser query parameter. |
| released | PUT | N/A | N/A | Releases the taskId task. |
| resumed | PUT | N/A | N/A | Resumes the taskId task. |
| skipped | PUT | N/A | N/A | Skips the taskId task. |
| suspended | PUT | N/A | N/A | Suspends the taskId task. |
| nominated | PUT | N/A | N/A | Nominates the taskId task to the potential owners by the potOwner query parameter. You can use the parameter multiple times (for example: potOwner=usr1&potOwner=usr2). |
Example 10.6. Task Instances
- Start task with
taskId4 in the containertest$ curl -X PUT -u 'kieserver:kieserver1!' http://localhost:8080/kie-server/services/rest/server/containers/test/tasks/4/states/started
- Complete the task 1 by passing an output parameter
$ curl -X PUT -u 'kieserver:kieserver1!' -H 'Content-type: application/json' -H 'X-KIE-ContentType: JSON' --data '{ "_approval" : true }' 'http://localhost:8080/kie-server/services/rest/server/containers/test/tasks/1/states/completed'
Note
Certain operations are illegal, for example starting a completed task. If you make such a request, you will receive one of the following errors:
Unexpected error during processing User '[UserImpl:'{USER ID}']' does not have permissions to execute operation OPERATION on task id {TASK ID}
Unexpected error during processing: User '[UserImpl:'{USER ID}']' was unable to execute operation OPERATION on task id {TASK ID} due to a no 'current status' match
To remove it, make sure the operation you are executing is allowed for the current task status. If you use
-Dorg.kie.server.bypass.auth.user=true, you also must provide a user using the query parameter user, who has the permission to execute the operation. If you do not use the parameter, the logged user will be used to perform the action.
10.6.4.2. Managing Task Instance Data
Use this base URI: server/containers/{containerId}/tasks/{taskId}. See table Task Instance Data Management Endpoints for a list of endpoints.
Table 10.6. Task Instance Data Management Endpoints
| URI | Method | Request Type | Response Type | Description |
|---|---|---|---|---|
| / | GET | N/A | A TaskInstance object | Gets task instance details of a taskId task. |
| attachments | POST | The content of the attachment | N/A | Adds a new attachment for the task. The ID of the created content is returned in the response, which is HTTP code 201. The name of the attachment is set using the query parameter name. It is not an idempotent method, thus if you make multiples request, it will create multiple attachements. |
| attachments | GET | N/A | A list of TaskAttachment objects | Gets all task attachments for the task. |
| attachments/{attachmentId} | GET | N/A | A TaskAttachment object | Gets the attachmentId task attachment. |
| attachments/{attachmentId} | DELETE | N/A | N/A | Removes the attachmentId attachment. |
| attachments/{attachmentId}/content | GET | N/A | An attachment type object | Gets the attachmentId task attachment content. |
| comments | POST | A TaskComment object | Long | Adds a new comment for the task. The ID of the created content is returned in the response, which HTTP code is 201. It is not an idempotent method, thus if you make multiples request, it will create multiple comments. |
| comments | GET | N/A | A list of TaskComment objects | Gets all task comments for the task. |
| comments/{commentId} | GET | N/A | A TaskComment object | Gets a task comment identified by commentId. |
| comments/{commentId} | DELETE | N/A | N/A | Removes the commentId comment for the task. |
| contents/input | GET | N/A | A map with the input parameters name/value | Gets the task input content in form of a map, where the key is the parameter name and the value is the value of the output parameter. |
| contents/output | PUT | A map with the output parameters name/value | N/A | Updates the task output parameters and returns HTTP 201 if successful. You must provide the output parameters in form of a map, where the key is the parameter name and the value is the value of the output parameter. |
| contents/output | GET | N/A | A map with the output parameters name/value | Gets the task output content in form of a map, where the key is the parameter name and the value is the value of the output parameter. |
| contents/{contentId} | DELETE | N/A | N/A | Deletes the task contentId content and returns HTTP code 204. |
| description | PUT | Marshalled String value | N/A | Updates the task description and returns HTTP code 201 if successful. You must provide the new value for description in the request body. |
| expiration | PUT | Marshalled Date value | N/A | Updates the task expiration date and returns HTTP 201 if successful. You must provide the new value for the expiration date in the request body. |
| name | PUT | Marshalled String value | N/A | Updates the task name and returns HTTP code 201 if successful. You must provide the new value for name in the request body. |
| priority | PUT | Marshalled int value | N/A | Updates the task priority and returns HTTP code 201 if successful. You must provide the new value for priority in the request body. |
| skipable | PUT | Marshalled boolean value | N/A | Updates the task property skipable and returns HTTP 201 if successful. You must provide the new value for the skipable property in the request body. |
Example 10.7. User Task Instance Data
- Get a user task instance for container
test:$ curl -X GET -u 'kieserver:kieserver1!' 'http://localhost:8080/kie-server/services/rest/server/containers/test/tasks/1'
Example response:<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <task-instance> <task-id>1</task-id> <task-priority>0</task-priority> <task-name>Approval by PM</task-name> <task-subject></task-subject> <task-description></task-description> <task-form>ApprovalbyPM</task-form> <task-status>Ready</task-status> <task-actual-owner></task-actual-owner> <task-created-by></task-created-by> <task-created-on>2016-02-15T13:31:10.624-02:00</task-created-on> <task-activation-time>2016-02-15T13:31:10.624-02:00</task-activation-time> <task-skippable>false</task-skippable> <task-workitem-id>1</task-workitem-id> <task-process-instance-id>1</task-process-instance-id> <task-parent-id>-1</task-parent-id> <task-process-id>com.sample.rewards-basic</task-process-id> <task-container-id>rewards</task-container-id> </task-instance> - Set priority to 3 for task 1:
$ curl -X PUT -u 'kieserver:kieserver1!' -H 'Content-type: application/json' -H 'X-KIE-ContentType: JSON' --data '3' 'http://localhost:8080/kie-server/services/rest/server/containers/test/tasks/1/priority'
- Add a comment to a task 2:
$ curl -X POST -u 'kieserver:kieserver1!' -H 'Content-type: application/json' -H 'X-KIE-ContentType: JSON' --data '{ "comment" : "One last comment", "comment-added-by": "kieserver"}' 'http://localhost:8080/kie-server/services/rest/server/containers/test/tasks/2/comments' - Get all task comments:
$ curl -u 'kieserver:kieserver1!' -H 'Accept: application/json' 'http://localhost:8080/kie-server/services/rest/server/containers/test/tasks/2/comments'
Example response:{ "task-comment" : [ { "comment-id" : 1, "comment" : "Some task comment", "comment-added-by" : "kieserver" }, { "comment-id" : 3, "comment" : "One last comment", "comment-added-by" : "kieserver" } ] }
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.