jBPM supports runtime commands that you can send to KIE Server for asset-related operations, such as executing all rules or inserting or retracting objects in a KIE session. The full list of supported runtime commands is located in the org.drools.core.command.runtime package in your jBPM instance.
In the KIE Server REST API, you use the global org.drools.core.command.runtime commands or the rule-specific org.drools.core.command.runtime.rule commands as the request body for POST requests to http://SERVER:PORT/kie-server/services/rest/server/containers/instances/{containerId}. For more information about using the KIE Server REST API, see KIE Server REST API for KIE containers and business assets.
In the KIE Server Java client API, you can embed these commands in your Java application along with the relevant Java client. For example, for rule-related commands, you use the RuleServicesClient Java client with the embedded commands. For more information about using the KIE Server Java client API, see KIE Server Java client API for KIE containers and business assets.
18.9.1. Sample runtime commands in jBPM
The following are sample runtime commands that you can use with the KIE Server REST API or Java client API for asset-related operations in KIE Server:
BatchExecutionCommand
InsertObjectCommand
RetractCommand
ModifyCommand
GetObjectCommand
GetObjectsCommand
InsertElementsCommand
FireAllRulesCommand
StartProcessCommand
SignalEventCommand
CompleteWorkItemCommand
AbortWorkItemCommand
QueryCommand
SetGlobalCommand
GetGlobalCommand
For the full list of supported runtime commands, see the org.drools.core.command.runtime package in your jBPM instance.
Each command in this section includes a REST request body example (JSON) for the KIE Server REST API and an embedded Java command example for the KIE Server Java client API. The Java examples use an object org.drools.compiler.test.Person with the fields name (String) and age (Integer).
BatchExecutionCommand
Contains multiple commands to be executed together.
Table 55. Command attributes Name Description Requirement
commands
List of commands to be executed.
Required
lookup
Sets the KIE session ID on which the commands will be executed. For stateless KIE sessions, this attribute is required. For stateful KIE sessions, this attribute is optional and if not specified, the default KIE session is used.
Required for stateless KIE session, optional for stateful KIE session
Example JSON request body
{
"lookup": "ksession1",
"commands": [ {
"insert": {
"object": {
"org.drools.compiler.test.Person": {
"name": "john",
"age": 25
}
}
}
},
{
"fire-all-rules": {
"max": 10,
"out-identifier": "firedActivations"
}
}
]
}
Example Java command
BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
InsertObjectCommand insertObjectCommand = new InsertObjectCommand(new Person("john", 25));
FireAllRulesCommand fireAllRulesCommand = new FireAllRulesCommand();
command.getCommands().add(insertObjectCommand);
command.getCommands().add(fireAllRulesCommand);
ksession.execute(command);
Example server response (JSON)
{
"response": [
{
"type": "SUCCESS",
"msg": "Container command-script-container successfully called.",
"result": {
"execution-results": {
"results": [
{
"value": 0,
"key": "firedActivations"
}
],
"facts": []
}
}
}
]
}
InsertObjectCommand
Inserts an object into the KIE session.
Table 56. Command attributes Name Description Requirement
object
The object to be inserted
Required
out-identifier
ID of the FactHandle created from the object insertion and added to the execution results
Optional
return-object
Boolean to determine whether the object must be returned in the execution results (default: true)
Optional
entry-point
Entry point for the insertion
Optional
Example JSON request body
{
"commands": [ {
"insert": {
"entry-point": "my stream",
"object": {
"org.drools.compiler.test.Person": {
"age": 25,
"name": "john"
}
},
"out-identifier": "john",
"return-object": false
}
}
]
}
Example Java command
Command insertObjectCommand =
CommandFactory.newInsert(new Person("john", 25), "john", false, null);
ksession.execute(insertObjectCommand);
Example server response (JSON)
{
"response": [
{
"type": "SUCCESS",
"msg": "Container command-script-container successfully called.",
"result": {
"execution-results": {
"results": [],
"facts": [
{
"value": {
"org.drools.core.common.DefaultFactHandle": {
"external-form": "0:4:436792766:-2127720265:4:DEFAULT:NON_TRAIT:java.util.LinkedHashMap"
}
},
"key": "john"
}
]
}
}
}
]
}
RetractCommand
Retracts an object from the KIE session.
Table 57. Command attributes Name Description Requirement
fact-handle
The FactHandle associated with the object to be retracted
Required
Example JSON request body
{
"commands": [ {
"retract": {
"fact-handle": "0:4:436792766:-2127720265:4:DEFAULT:NON_TRAIT:java.util.LinkedHashMap"
}
}
]
}
Example Java command: Use FactHandleFromString
RetractCommand retractCommand = new RetractCommand();
retractCommand.setFactHandleFromString("123:234:345:456:567");
Example Java command: Use FactHandle from inserted object
RetractCommand retractCommand = new RetractCommand(factHandle);
Example server response (JSON)
{
"response": [
{
"type": "SUCCESS",
"msg": "Container employee-rostering successfully called.",
"result": {
"execution-results": {
"results": [],
"facts": []
}
}
}
]
}
ModifyCommand
Modifies a previously inserted object in the KIE session.
Table 58. Command attributes Name Description Requirement
fact-handle
The FactHandle associated with the object to be modified
Required
setters
List of setters for object modifications
Required
Example JSON request body
{
"commands": [ {
"modify": {
"fact-handle": "0:4:436792766:-2127720265:4:DEFAULT:NON_TRAIT:java.util.LinkedHashMap",
"setters": {
"accessor": "age",
"value": 25
}
}
}
]
}
Example Java command
ModifyCommand modifyCommand = new ModifyCommand(factHandle);
List<Setter> setters = new ArrayList<Setter>();
setters.add(new SetterImpl("age", "25"));
modifyCommand.setSetters(setters);
Example server response (JSON)
{
"response": [
{
"type": "SUCCESS",
"msg": "Container employee-rostering successfully called.",
"result": {
"execution-results": {
"results": [],
"facts": []
}
}
}
]
}
GetObjectCommand
Retrieves an object from a KIE session.
Table 59. Command attributes Name Description Requirement
fact-handle
The FactHandle associated with the object to be retrieved
Required
out-identifier
ID of the FactHandle created from the object insertion and added to the execution results
Optional
Example JSON request body
{
"commands": [ {
"get-object": {
"fact-handle": "0:4:436792766:-2127720265:4:DEFAULT:NON_TRAIT:java.util.LinkedHashMap",
"out-identifier": "john"
}
}
]
}
Example Java command
GetObjectCommand getObjectCommand = new GetObjectCommand();
getObjectCommand.setFactHandleFromString("123:234:345:456:567");
getObjectCommand.setOutIdentifier("john");
Example server response (JSON)
{
"response": [
{
"type": "SUCCESS",
"msg": "Container command-script-container successfully called.",
"result": {
"execution-results": {
"results": [
{
"value": null,
"key": "john"
}
],
"facts": []
}
}
}
]
}
GetObjectsCommand
Retrieves all objects from the KIE session as a collection.
Table 60. Command attributes Name Description Requirement
object-filter
Filter for the objects returned from the KIE session
Optional
out-identifier
Identifier to be used in the execution results
Optional
Example JSON request body
{
"commands": [ {
"get-objects": {
"out-identifier": "objects"
}
}
]
}
Example Java command
GetObjectsCommand getObjectsCommand = new GetObjectsCommand();
getObjectsCommand.setOutIdentifier("objects");
Example server response (JSON)
{
"response": [
{
"type": "SUCCESS",
"msg": "Container command-script-container successfully called.",
"result": {
"execution-results": {
"results": [
{
"value": [
{
"org.apache.xerces.dom.ElementNSImpl": "<?xml version=\"1.0\" encoding=\"UTF-16\"?>\n<object xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:type=\"person\"><age>25</age><name>john</name>\n <\/object>"
},
{
"org.drools.compiler.test.Person": {
"name": "john",
"age": 25
}
}
],
"key": "objects"
}
],
"facts": []
}
}
}
]
}
InsertElementsCommand
Inserts a list of objects into the KIE session.
Table 61. Command attributes Name Description Requirement
objects
The list of objects to be inserted into the KIE session
Required
out-identifier
ID of the FactHandle created from the object insertion and added to the execution results
Optional
return-object
Boolean to determine whether the object must be returned in the execution results. Default value: true.
Optional
entry-point
Entry point for the insertion
Optional
Example JSON request body
{
"commands": [ {
"insert-elements": {
"objects": [
{
"containedObject": {
"@class": "org.drools.compiler.test.Person",
"age": 25,
"name": "john"
}
},
{
"containedObject": {
"@class": "Person",
"age": 35,
"name": "sarah"
}
}
]
}
}
]
}
Example Java command
List<Object> objects = new ArrayList<Object>();
objects.add(new Person("john", 25));
objects.add(new Person("sarah", 35));
Command insertElementsCommand = CommandFactory.newInsertElements(objects);
Example server response (JSON)
{
"response": [
{
"type": "SUCCESS",
"msg": "Container command-script-container successfully called.",
"result": {
"execution-results": {
"results": [],
"facts": [
{
"value": {
"org.drools.core.common.DefaultFactHandle": {
"external-form": "0:4:436792766:-2127720265:4:DEFAULT:NON_TRAIT:java.util.LinkedHashMap"
}
},
"key": "john"
},
{
"value": {
"org.drools.core.common.DefaultFactHandle": {
"external-form": "0:4:436792766:-2127720266:4:DEFAULT:NON_TRAIT:java.util.LinkedHashMap"
}
},
"key": "sarah"
}
]
}
}
}
]
}
FireAllRulesCommand
Executes all rules in the KIE session.
Table 62. Command attributes Name Description Requirement
max
Maximum number of rules to be executed. The default is -1 and does not put any restriction on execution.
Optional
out-identifier
ID to be used for retrieving the number of fired rules in execution results.
Optional
agenda-filter
Agenda Filter to be used for rule execution.
Optional
Example JSON request body
{
"commands" : [ {
"fire-all-rules": {
"max": 10,
"out-identifier": "firedActivations"
}
} ]
}
Example Java command
FireAllRulesCommand fireAllRulesCommand = new FireAllRulesCommand();
fireAllRulesCommand.setMax(10);
fireAllRulesCommand.setOutIdentifier("firedActivations");
Example server response (JSON)
{
"response": [
{
"type": "SUCCESS",
"msg": "Container command-script-container successfully called.",
"result": {
"execution-results": {
"results": [
{
"value": 0,
"key": "firedActivations"
}
],
"facts": []
}
}
}
]
}
StartProcessCommand
Starts a process using the process ID. You can also pass parameters and initial data to be inserted.
Table 63. Command attributes Name Description Requirement
processId
ID of the process to be started
Required
parameters
A Map <String,Object> argument to pass parameters in the process startup
Optional
data
List of objects to be inserted into the KIE session before the process startup
Optional
Example JSON request body
{
"commands": [
{
"start-process": {
"processId": "myProject.myProcess",
"data": null,
"parameter": [],
"out-identifier": null
}
}
]
}
Example Java command
StartProcessCommand startProcessCommand = new StartProcessCommand();
startProcessCommand.setProcessId("org.drools.task.processOne");
Example server response (JSON)
{
"type": "SUCCESS",
"msg": "Container stateful-session successfully called.",
"result": {
"execution-results": {
"results": [],
"facts": []
}
}
}
SignalEventCommand
Sends a signal event to the KIE session.
Table 64. Command attributes Name Description Requirement
event-type
Type of the incoming event
Required
process-instance-id
ID of the process instance to be signalled
Optional
event
Data of the incoming event
Optional
Example JSON request body
{
"commands": [
{
"signal-event": {
"process-instance-id": 1001,
"correlation-key": null,
"event-type": "start",
"event": {
"org.kie.server.testing.Person": {
"fullname": "john",
"age": 25
}
}
}
}
]
}
Example Java command
SignalEventCommand signalEventCommand = new SignalEventCommand();
signalEventCommand.setProcessInstanceId(1001);
signalEventCommand.setEventType("start");
signalEventCommand.setEvent(new Person("john", 25));
Example server response (JSON)
{
"type": "SUCCESS",
"msg": "Container stateful-session successfully called.",
"result": {
"execution-results": {
"results": [],
"facts": []
}
}
}
CompleteWorkItemCommand
Completes a work item in the KIE session.
Table 65. Command attributes Name Description Requirement
workItemId
ID of the work item to be completed
Required
results
Result of the work item
Optional
Example JSON request body
{
"commands": [ {
"complete-work-item": {
"id": 1001
}
}
]
}
Example Java command
CompleteWorkItemCommand completeWorkItemCommand = new CompleteWorkItemCommand();
completeWorkItemCommand.setWorkItemId(1001);
Example server response (JSON)
{
"response": [
{
"type": "SUCCESS",
"msg": "Container employee-rostering successfully called.",
"result": {
"execution-results": {
"results": [],
"facts": []
}
}
}
]
}
AbortWorkItemCommand
Aborts a work item in the KIE session in the same way as ksession.getWorkItemManager().abortWorkItem(workItemId).
Table 66. Command attributes Name Description Requirement
workItemId
ID of the work item to be aborted
Required
Example JSON request body
{
"commands": [ {
"abort-work-item": {
"id": 1001
}
}
]
}
Example Java command
AbortWorkItemCommand abortWorkItemCommand = new AbortWorkItemCommand();
abortWorkItemCommand.setWorkItemId(1001);
Example server response (JSON)
{
"response": [
{
"type": "SUCCESS",
"msg": "Container employee-rostering successfully called.",
"result": {
"execution-results": {
"results": [],
"facts": []
}
}
}
]
}
QueryCommand
Executes a query defined in the KIE base.
Table 67. Command attributes Name Description Requirement
name
Query name.
Required
out-identifier
ID of the query results. The query results are added in the execution results with this identifier.
Optional
arguments
List of objects to be passed as a query parameter.
Optional
Example JSON request body
{
"commands": [
{
"query": {
"name": "persons",
"arguments": [],
"out-identifier": "persons"
}
}
]
}
Example Java command
QueryCommand queryCommand = new QueryCommand();
queryCommand.setName("persons");
queryCommand.setOutIdentifier("persons");
Example server response (JSON)
{
"type": "SUCCESS",
"msg": "Container stateful-session successfully called.",
"result": {
"execution-results": {
"results": [
{
"value": {
"org.drools.core.runtime.rule.impl.FlatQueryResults": {
"idFactHandleMaps": {
"type": "LIST",
"componentType": null,
"element": [
{
"type": "MAP",
"componentType": null,
"element": [
{
"value": {
"org.drools.core.common.DisconnectedFactHandle": {
"id": 1,
"identityHashCode": 1809949690,
"objectHashCode": 1809949690,
"recency": 1,
"object": {
"org.kie.server.testing.Person": {
"fullname": "John Doe",
"age": 47
}
},
"entryPointId": "DEFAULT",
"traitType": "NON_TRAIT",
"external-form": "0:1:1809949690:1809949690:1:DEFAULT:NON_TRAIT:org.kie.server.testing.Person"
}
},
"key": "$person"
}
]
}
]
},
"idResultMaps": {
"type": "LIST",
"componentType": null,
"element": [
{
"type": "MAP",
"componentType": null,
"element": [
{
"value": {
"org.kie.server.testing.Person": {
"fullname": "John Doe",
"age": 47
}
},
"key": "$person"
}
]
}
]
},
"identifiers": {
"type": "SET",
"componentType": null,
"element": [
"$person"
]
}
}
},
"key": "persons"
}
],
"facts": []
}
}
}
SetGlobalCommand
Sets an object to a global state.
Table 68. Command attributes Name Description Requirement
identifier
ID of the global variable defined in the KIE base
Required
object
Object to be set into the global variable
Optional
out
Boolean to exclude the global variable you set from the execution results
Optional
out-identifier
ID of the global execution result
Optional
Example JSON request body
{
"commands": [
{
"set-global": {
"identifier": "helper",
"object": {
"org.kie.server.testing.Person": {
"fullname": "kyle",
"age": 30
}
},
"out-identifier": "output"
}
}
]
}
Example Java command
SetGlobalCommand setGlobalCommand = new SetGlobalCommand();
setGlobalCommand.setIdentifier("helper");
setGlobalCommand.setObject(new Person("kyle", 30));
setGlobalCommand.setOut(true);
setGlobalCommand.setOutIdentifier("output");
Example server response (JSON)
{
"type": "SUCCESS",
"msg": "Container stateful-session successfully called.",
"result": {
"execution-results": {
"results": [
{
"value": {
"org.kie.server.testing.Person": {
"fullname": "kyle",
"age": 30
}
},
"key": "output"
}
],
"facts": []
}
}
}
GetGlobalCommand
Retrieves a previously defined global object.
Table 69. Command attributes Name Description Requirement
identifier
ID of the global variable defined in the KIE base
Required
out-identifier
ID to be used in the execution results
Optional
Example JSON request body
{
"commands": [ {
"get-global": {
"identifier": "helper",
"out-identifier": "helperOutput"
}
}
]
}
Example Java command
GetGlobalCommand getGlobalCommand = new GetGlobalCommand();
getGlobalCommand.setIdentifier("helper");
getGlobalCommand.setOutIdentifier("helperOutput");
Example server response (JSON)
{
"response": [
{
"type": "SUCCESS",
"msg": "Container command-script-container successfully called.",
"result": {
"execution-results": {
"results": [
{
"value": null,
"key": "helperOutput"
}
],
"facts": []
}
}
}
]
}