9.6. The REST API for Intelligent Process Server Execution

You can communicate with the Intelligent Process 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 Intelligent Process 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 Intelligent Process Server has BRM capability. The rest of the endpoints will work only if your Intelligent Process Server has BPM capabilities. Check the following URI for capabilities of your Intelligent Process Server: http://SERVER:PORT/kie-server/services/rest/server.

9.6.1. BRMS Commands

Table 9.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:
  • AgendaGroupSetFocusCommand
  • ClearActivationGroupCommand
  • ClearAgendaCommand
  • ClearAgendaGroupCommand
  • ClearRuleFlowGroupCommand
  • DeleteCommand
  • InsertObjectCommand
  • ModifyCommand
  • GetObjectCommand
  • InsertElementsCommand
  • FireAllRulesCommand
  • QueryCommand
  • SetGlobalCommand
  • GetGlobalCommand
  • GetObjectsCommand
  • BatchExecutionCommand
For more information about the commands, see the org.drools.core.command.runtime package. Alternatively, see Supported JBoss BRMS Commands from the Red Hat JBoss Develompent Guide.

Example 9.1. [POST] Drools Commands Execution

  1. 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" : { }
		      } ]
		    }
  2. 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. Lookup specifies 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}"
    }

9.6.2. Managing Processes

Use the following entry point: server/containers/{containerId}/processes. See table Process Management Endpoints for a list of endpoints.

Table 9.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 9.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-basic with 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'

9.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 9.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 9.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 9.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 9.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"
      }
    }

9.6.4. Managing User Tasks

Use this base URI: server/containers/{containerId}/tasks.

9.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 9.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 9.6. Task Instances

  • Start task with taskId 4 in the container test 
    $ 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.

9.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 9.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 9.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"
  } ]
}

9.6.5. Managing Job Execution

REST API allows you to access information about asynchronous jobs without using the Business Central directly. The Intelligent Process Server exposes a component for executing asynchronous tasks through REST and JMS. The exposed API then offers you an access to:
  • schedule a new job,
  • cancel an already scheduled job,
  • add a failed job to the queue again (giving the relevant jobId),
  • get a particular job (by its jobId),
  • query jobs scheduled to execute the same command (given as a parameter),
  • query jobs scheduled with the same given businessKey,
  • query jobs with the given status as a parameter.
To control job execution, use the URI
http://SERVER_ADDRESS:PORT/kie-server/services/rest/server/jobs.
For example http://localhost:8080/kie-server/services/rest/server/jobs.

Job Execution Endpoints

See the list of available endpoints:
/
Method: GET
Response type: list of RequestInfoInstance objects
Description: Use this endpoint to query jobs in the server. Moreover, you can specify the parameters page, pageSize, and status; possible values for status are QUEUED, DONE, CANCELLED, ERROR, RETRYING, and RUNNING. Note that these values must be capitalized.
/
Method: POST
Request type: RequestInfoInstance object
Response type: created jobId
Description: Creates a new job request and returns its ID. It is possible to assign the job to a container by setting containerId.
/commands/{jobCommandName}
Method: GET
Response type: list of RequestInfoInstance objects
Description: Returns a list of jobs configured to run with the jobCommandName command class.
/{jobId}
Method: GET
Response type: RequestInfoInstance object
Description: Returns details of a job request with the provided jobId. You can specify the parameters withErrors (boolean) to include errors of an execution and withData to include the data associated with the job.
/{jobId}
Method: DELETE
Description: Cancels a job with the given jobId. If successful, returns HTTP code 204, otherwise HTTP code 500.
/{jobId}
Method: PUT
Request type: RequestInfoInstance object
Description: Requests unfinished or failed job request with the given jobId and reassigns it into the job queue.
/keys/{businessKey}
Method: GET
Response type: list of RequestInfoInstance objects
Description: Returns a list of jobs that match the given businessKey.

Example 9.8. [POST] New Job

  1. Change into a directory of your choice and create a jobRequest.xml file with the following content: 
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<job-request-instance>
	<job-command>org.jbpm.executor.commands.PrintOutCommand</job-command>
	<scheduled-date>2016-02-11T00:00:00-02:00</scheduled-date>
	<data />
</job-request-instance>
  2. Execute the following command: 
    $ curl -X POST --data @jobRequest.xml -u 'kieserver:kieserver1!' -H 'content-type: application/xml' 'http://localhost:8080/kie-server/services/rest/server/jobs/'
An example response: 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<long-type>
	<value>4</value>
</long-type>

Example 9.9. [GET] List All Jobs

To list all jobs in the JSON format, execute the following command: 
$ curl -u 'kieserver:kieserver1!' -H 'Accept: application/json' 'http://localhost:8080/kie-server/services/rest/server/jobs?status=QUEUED&status=DONE&status=CANCELLED&status=ERROR&status=RETRYING&status=RUNNING'
An example response: 
{
 "request-info-instance" : [ {
    "request-instance-id"    :  3,
    "request-status"         : "CANCELLED",
    "request-message"        : "Ready to execute",
    "request-retries"        :  3,
    "request-executions"     :  0,
    "request-command"        : "org.jbpm.executor.commands.PrintOutCommand",
    "request-scheduled-date" :  1455156000000
 }, {
    "request-instance-id"    :  2,
    "request-status"         : "QUEUED",
    "request-message"        : "Ready to execute",
    "request-retries"        :  3,
    "request-executions"     :  0,
    "request-command"        : "org.jbpm.executor.commands.PrintOutCommand",
    "request-scheduled-date" :  1454983200000
 }, {
    "request-instance-id"    :  1,
    "request-status"         : "DONE",
    "request-message"        : "Ready to execute",
    "request-retries"        :  3,
    "request-executions"     :  0,
    "request-command"        : "org.jbpm.executor.commands.PrintOutCommand",
    "request-scheduled-date" :  1454918401190
 } ]
}