Chapter 4. Runtime commands in Red Hat Decision Manager
Red Hat Decision Manager 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 Red Hat Decision Manager 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 Chapter 1, 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 Chapter 2, KIE Server Java client API for KIE containers and business assets.
4.1. Sample runtime commands in Red Hat Decision Manager
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 -
QueryCommand -
SetGlobalCommand -
GetGlobalCommand
For the full list of supported runtime commands, see the org.drools.core.command.runtime package in your Red Hat Decision Manager 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 4.1. Command attributes
Name Description Requirement commandsList of commands to be executed.
Required
lookupSets 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
NoteKIE session IDs are in the
kmodule.xmlfile of your Red Hat Decision Manager project. To view or add a KIE session ID in Business Central to use with thelookupcommand attribute, navigate to the relevant project in Business Central and go to project Settings → KIE bases → KIE sessions. If no KIE bases exist, click Add KIE base → KIE sessions to define the new KIE base and KIE sessions.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
InsertObjectCommand insertCommand = new InsertObjectCommand(new Person("john", 25)); FireAllRulesCommand fireCommand = new FireAllRulesCommand(); BatchExecutionCommand batch = new BatchExecutionCommandImpl(Arrays.asList(insertCommand, fireCommand), "ksession1");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 4.2. Command attributes
Name Description Requirement objectThe object to be inserted
Required
out-identifierID of the
FactHandlecreated from the object insertion and added to the execution resultsOptional
return-objectBoolean to determine whether the object must be returned in the execution results (default:
true)Optional
entry-pointEntry 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 4.3. Command attributes
Name Description Requirement fact-handleThe
FactHandleassociated with the object to be retractedRequired
Example JSON request body
{ "commands": [ { "retract": { "fact-handle": "0:4:436792766:-2127720265:4:DEFAULT:NON_TRAIT:java.util.LinkedHashMap" } } ] }Example Java command: Use
FactHandleFromStringRetractCommand retractCommand = new RetractCommand(); retractCommand.setFactHandleFromString("123:234:345:456:567");Example Java command: Use
FactHandlefrom inserted objectRetractCommand 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 4.4. Command attributes
Name Description Requirement fact-handleThe
FactHandleassociated with the object to be modifiedRequired
settersList 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 4.5. Command attributes
Name Description Requirement fact-handleThe
FactHandleassociated with the object to be retrievedRequired
out-identifierID of the
FactHandlecreated from the object insertion and added to the execution resultsOptional
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 4.6. Command attributes
Name Description Requirement object-filterFilter for the objects returned from the KIE session
Optional
out-identifierIdentifier 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 4.7. Command attributes
Name Description Requirement objectsThe list of objects to be inserted into the KIE session
Required
out-identifierID of the
FactHandlecreated from the object insertion and added to the execution resultsOptional
return-objectBoolean to determine whether the object must be returned in the execution results. Default value:
true.Optional
entry-pointEntry 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 4.8. Command attributes
Name Description Requirement maxMaximum number of rules to be executed. The default is
-1and does not put any restriction on execution.Optional
out-identifierID to be used for retrieving the number of fired rules in execution results.
Optional
agenda-filterAgenda 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": [] } } } ] }- QueryCommand
Executes a query defined in the KIE base.
Table 4.9. Command attributes
Name Description Requirement nameQuery name.
Required
out-identifierID of the query results. The query results are added in the execution results with this identifier.
Optional
argumentsList 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 4.10. Command attributes
Name Description Requirement identifierID of the global variable defined in the KIE base
Required
objectObject to be set into the global variable
Optional
outBoolean to exclude the global variable you set from the execution results
Optional
out-identifierID 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 4.11. Command attributes
Name Description Requirement identifierID of the global variable defined in the KIE base
Required
out-identifierID 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": [] } } } ] }