JBoss.orgCommunity Documentation
The KIE Execution Server is a standalone, out-of-the-box component that can be used to instantiate and execute rules via interfaces available for REST, JMS or a Java client side application. Created as a web deployable WAR file, this engine can be deployed on any web container.
This server has a low footprint, with minimal memory consumption, and therefore, can be deployed easily on a cloud instance. Each instance of this server can open and instantiate multiple Kie Containers which allows you to execute multiple rule services in parallel.
You can provision execution server instances via KIE Workbench. In this chapter, we will go through the steps required to setup an execution server, provision and connect to this server via KIE Workbench, control what rule artifacts go in each instance and go through its lifecycle.
The KIE Execution Server is distributed as a web application archive (WAR) file. The WAR file comes in three different flavors:
To install the KIE Execution Server and verify it is running, complete the following steps:
Deploy the WAR file into your web container.
Create a user with the role of kie-server on the container.
Test that you can access the execution engine by navigating to the endpoint in a
browser window: http://SERVER:PORT/CONTEXT/services/rest/server/.
When prompted for username/password, type in the username and password that you created in step 2.
Once authenticated, you will see an XML response in the form of engine status, similar to this:
Example 22.1. Sample handshaking server response
<response type="SUCCESS" msg="KIE Server info">
<kie-server-info>
<version>6.3.0.CR2</version>
</kie-server-info>
</response>
Download and unzip the Tomcat distribution. Let's call the root of the distribution TOMCAT_HOME.
This directory is named after the Tomcat version, so for example apache-tomcat-7.0.55.
Download kie-server-6.3.0.CR2-webc.war and place it into TOMCAT_HOME/webapps.
Configure user(s) and role(s). Make sure that file TOMCAT_HOME/conf/tomcat-users.xml
contains the following username and role definition. You can of course choose different username and password,
just make sure that the user has role kie-server:
Example 22.2. Username and role definition for Tomcat
<role rolename="kie-server"/>
<user username="serveruser" password="my.s3cr3t.pass" roles="kie-server"/>
Start the server by running TOMCAT_HOME/bin/startup.[sh|bat]. You can check out
the Tomcat logs in TOMCAT_HOME/logs to see if the application deployed successfully.
Verify the server is running. Go to http://SERVER:PORT/CONTEXT/services/rest/server/ and
type the specified username and password. You should see simple XML message with basic information about
the server.
Download and unzip the WildFly distribution. Let's call the root of the distribution WILDFLY_HOME.
This directory is named after the WildFly version, so for example wildfly-8.2.0.Final.
Download kie-server-6.3.0.CR2-ee7.war and place it into WILDFLY_HOME/standalone/deployments.
Configure user(s) and role(s). Execute the following command
WILDFLY_HOME/bin/add-user.[sh|bat] -a -u 'serveruser' -p 'my.s3cr3t.pass' -ro 'kie-server'.
You can of course choose different username and password, just make sure that the user has role kie-server.
Start the server by running WILDFLY_HOME/bin/standalone.[sh|bat] -c standalone-full.xml.
You can check out the standard output or WildFly logs in WILDFLY_HOME/standalone/logs to see if the application
deployed successfully.
Verify the server is running. Go to http://SERVER:PORT/CONTEXT/services/rest/server/ and
type the specified username and password. You should see simple XML message with basic information about
the server.
To register a new KIE Execution Server instance, click on Deploy → Rule Deployments in KIE Workbench. This will open up the screen to show you any existing servers that you have registered. Click on Register to bring up the screen for entering details for a new server.
Enter details of your new server by specifying the endpoint and giving it a unique and identifiable name.
The endpoint should be the same you used to verify that the server was running in the
previous section and looks like this:
http://SERVER:PORT/CONTEXT/services/rest/server. Also provide a unique
identifiable name for this server.
Although the username/password sections are not mandatory, unless you specifically take
away the authentication required for your kie-server webapp, then you will need to
enter these. These values should match the ones created in the previous section when
you were installing this webapp with the role of kie-server.
Click Connect to connect and register this server. If you have successfully entered all the details, your server will be listed in the Rule Deployments Screen.
Common errors at this stage include issues like invalid username/password or the
username not having the required kie-server role or the endpoint not
being correct. All of these issues will give the same error: Can't connect to endpoint
Once your Execution Server is registered, you can start adding Kie Containers to it.
Kie Containers are self contained environments that have been provisioned to hold instances of your packaged and deployed rule instances.
Start by clicking the + icon next to the Execution Server where you want to deploy your Container. This will bring up the New Container screen.
If you know the Group Name, Artifact Id and Version (GAV) of your deployed package, then you can enter those details and click the Ok button to select that instance (and provide a name for the Container);
If you don't know these values, you can search KIE Workbench for all packages that can be deployed. Click the Search button without entering any value in the search field (you can narrow your search by entering any term that you know exists in the package that you want to deploy).
INSERT SCREENSHOT HERE
The figure above shows that there are three deployable packages available to be used as containers on the Execution Server. Select the one that you want by clicking the Select button. This will auto-populate the GAV and you can then click the Ok button to use this deployable as the new Container.
Enter a name for this Container at the top and then press the Ok button.
The Container name must be unique inside each execution server and must not contain any spaces.
Just below the GAV row, you will see an uneditable row that shows you the URL for your Container against which you will be able to execute REST commands.
Containers within the Execution Server can be started, stopped and updated from within KIE Workbench.
Once registered, a Container is in the 'Stopped' mode. It can be started by first selecting it and then clicking the Start button. You can also select multiple Containers and start them all at the same time.
Once the Container is in the 'Running' mode, a green arrow appears next to it. If there are any errors starting the Container(s), red icons appear next to Containers and the Execution Server that they are deployed on.
You should check the logs of both the Execution Server and the current Business Central to see what the errors are before redeploying the Containers (and possibly the Execution Server).
Similar to starting a Container, select the Container(s) that you want to stop (or delete) and click the Stop button (which replaces the Start button for that Container once it has entered the 'Running' mode) or the Delete button.
You can update deployed KieContainers without restarting the
Execution Server. This is useful in cases where the Business Rules change,
creating new versions of packages to be provisioned.
You can have multiple versions of the same package provisioned and deployed,
each to a different KieContainer.
To update deployments in a KieContainer dynamically, click on the
icon next to the Container. This will open up the Container Info screen. An
example of this screen is shown here:
INSERT SCREENSHOT HERE
The Container Info screen is a useful tool because it not only allows you to see
the endpoint for this KieContainer, but it also allows you to
either manually or automatically refresh the provision if an update is
available. The update can be manual or automatic:
Manual Update: To manually update a
KieContainer, enter the new Version number in the Version
box and click on the Update button. You can of
course, update the Group Id or the Artifact Id , if these have changed as well.
Once updated, the Execution server updates the container and shows you the
resolved GAV attributes at the bottom of the screen in the Resolved Release Id section.
Automatic Update: If you want a deployed
Container to always have the latest version of your deployment without manually
editing it, you will need to set the Version property to the value of
LATEST and start a Scanner. This will ensure
that the deployed provision always contains the latest version. The Scanner can
be started just once on demand by clicking the Scan Now button or you can start
it in the background with scans happening at a specified interval (in
seconds).You can also set this value to LATEST when you are first
creating this deployment. The Resolved Release
Id in this case will show you the actual, latest version
number.
The Execution Server supports the following commands via the REST API.
Please note the following before using these commands:
The base URL for these will remain as the endpoint defined earlier
(for example:
http://SERVER:PORT/CONTEXT/services/rest/server/
)
All requests require basic HTTP Authentication for the role kie-server as indicated earlier.
Returns the Execution Server information
Example 22.3. Example Server Response
<response type="SUCCESS" msg="KIE Server info">
<kie-server-info>
<version>6.2.0.redhat-1</version>
</kie-server-info>
</response>Using POST HTTP method, you can execute various commands on the Execution Server. E.g: create-container, list-containers, dispose-container and call-container.
Following is the full list of commands:
CreateContainerCommand
GetServerInfoCommand
ListContainersCommand
CallContainerCommand
DisposeContainerCommand
GetContainerInfoCommand
GetScannerInfoCommand
UpdateScannerCommand
UpdateReleaseIdCommand
The commands itself can be found in the org.kie.server.api.commands package.
Returns a list of containers that have been created on this Execution Server.
Example 22.4. Example Server Response
<response type="SUCCESS" msg="List of created containers">
<kie-containers>
<kie-container container-id="MyProjectContainer" status="STARTED">
<release-id>
<artifact-id>Project1</artifact-id>
<group-id>com.redhat</group-id>
<version>1.0</version>
</release-id>
<resolved-release-id>
<artifact-id>Project1</artifact-id>
<group-id>com.redhat</group-id>
<version>1.0</version>
</resolved-release-id>
</kie-container>
</kie-containers>
</response>Returns the status and information about a particular container. For example,
executing
http://SERVER:PORT/CONTEXT/services/rest/server/containers/MyProjectContainer
could return the following example container info.
Example 22.5. Example Server Response
<response type="SUCCESS" msg="Info for container MyProjectContainer">
<kie-container container-id="MyProjectContainer" status="STARTED">
<release-id>
<artifact-id>Project1</artifact-id>
<group-id>com.redhat</group-id>
<version>1.0</version>
</release-id>
<resolved-release-id>
<artifact-id>Project1</artifact-id>
<group-id>com.redhat</group-id>
<version>1.0</version>
</resolved-release-id>
</kie-container>
</response>Allows you to create a new Container in the Execution Server. For example, to
create a Container with the id of MyRESTContainer the complete endpoint will be:
http://SERVER:PORT/CONTEXT/services/rest/server/containers/MyRESTContainer.
An example of request is:
Example 22.6. Example Request to create a container
<kie-container container-id="MyRESTContainer">
<release-id>
<artifact-id>Project1</artifact-id>
<group-id>com.redhat</group-id>
<version>1.0</version>
</release-id>
</kie-container>And the response from the server, if successful, would be be:
Example 22.7. Example Server Response when creating a container
<response type="SUCCESS" msg="Container MyRESTContainer successfully deployed with module com.redhat:Project1:1.0">
<kie-container container-id="MyProjectContainer" status="STARTED">
<release-id>
<artifact-id>Project1</artifact-id>
<group-id>com.redhat</group-id>
<version>1.0</version>
</release-id>
<resolved-release-id>
<artifact-id>Project1</artifact-id>
<group-id>com.redhat</group-id>
<version>1.0</version>
</resolved-release-id>
</kie-container>
</response>Disposes the Container specified by the id. For example, executing
http://SERVER:PORT/CONTEXT/services/rest/server/containers/MyProjectContainer
using the DELETE HTTP method will return the following server response:
Example 22.8. Example Server Response disposing a container
<response type="SUCCESS" msg="Container MyProjectContainer successfully disposed."/>Executes operations and commands against the specified Container. You can send
commands to this Container in the body of the POST request. For example, to
fire all rules for Container with id MyRESTContainer
(http://SERVER:PORT/CONTEXT/services/rest/server/containers/MyRESTContainer),
you would send the fire-all-rules command to it as shown below (in the body of
the POST request):
Following is the list of supported commands:
AgendaGroupSetFocusCommand
ClearActivationGroupCommand
ClearAgendaCommand
ClearAgendaGroupCommand
ClearRuleFlowGroupCommand
DeleteCommand
InsertObjectCommand
ModifyCommand
GetObjectCommand
InsertElementsCommand
FireAllRulesCommand
QueryCommand
SetGlobalCommand
GetGlobalCommand
GetObjectsCommand
BatchExecutionCommand
These commands can be found in the org.drools.core.command.runtime package.
Returns the full release id for the Container specified by the id.
Example 22.10. Example Server Response
<response type="SUCCESS" msg="ReleaseId for container MyProjectContainer">
<release-id>
<artifact-id>Project1</artifact-id>
<group-id>com.redhat</group-id>
<version>1.0</version>
</release-id>
</response>Allows you to update the release id of the container deployment. Send the new complete release id to the Server.
Example 22.11. Example Server Request
<release-id>
<artifact-id>Project1</artifact-id>
<group-id>com.redhat</group-id>
<version>1.1</version>
</release-id> The Server will respond with a success or error message, similar to the one below:
Example 22.12. Example Server Response
<response type="SUCCESS" msg="Release id successfully updated.">
<release-id>
<artifact-id>Project1</artifact-id>
<group-id>com.redhat</group-id>
<version>1.0</version>
</release-id>
</response>Returns information about the scanner for this Container's automatic updates.
Example 22.13. Example Server Response
<response type="SUCCESS" msg="Scanner info successfully retrieved">
<kie-scanner status="DISPOSED"/>
</response>Allows you to start or stop a scanner that controls polling for updated
Container deployments. To start the scanner, send a request similar to:
http://SERVER:PORT/CONTEXT/services/rest/server/containers/{container-id}/scanner
with the following POST data.
Example 22.14. Example Server Request to start the scanner
<kie-scanner status="STARTED" poll-interval="20"/>The poll-interval attribute is in seconds. The response from the server will be similar to:
Example 22.15. Example Server Response
<response type="SUCCESS" msg="Kie scanner successfully created.">
<kie-scanner status="STARTED"/>
</response>To stop the Scanner, replace the status with DISPOSED and remove
the poll-interval attribute.
Commands outlined in this section can be sent with any REST client, whether it is curl, RESTEasy or .NET based application. However, when sending requests from Java based application, users can utilize out of the box native client for remote communication with Execution Server. This client is part of the org.kie:kie-server-client project. It doesn't allow creating XML request, therefore it is necessary generate them before, for example, using Drools API.
Example 22.16. Generate XML request
import java.util.ArrayList;
import java.util.List;
import org.drools.core.command.impl.GenericCommand;
import org.drools.core.command.runtime.BatchExecutionCommandImpl;
import org.drools.core.command.runtime.rule.FireAllRulesCommand;
import org.drools.core.command.runtime.rule.InsertObjectCommand;
import org.kie.api.command.BatchExecutionCommand;
import org.kie.internal.runtime.helper.BatchExecutionHelper;
public class DecisionClient {
public static void main(String args[]) {
Bean1 bean1 = new Bean1();
bean1.setName("Robert");
InsertObjectCommand insertObjectCommand = new InsertObjectCommand(bean1, "f1");
FireAllRulesCommand fireAllRulesCommand = new FireAllRulesCommand("myFireCommand");
List<GenericCommand<?>> commands = new ArrayList<GenericCommand<?>>();
commands.add(insertObjectCommand);
commands.add(fireAllRulesCommand);
BatchExecutionCommand command = new BatchExecutionCommandImpl(commands);
String xStreamXml = BatchExecutionHelper.newXStreamMarshaller().toXML(command); // actual XML request
}
}
Once the request is generated it can be sent using kie-server-client as follows:
Example 22.17. Sending XML request with kie-server-client
import org.kie.server.api.model.ServiceResponse;
import org.kie.server.client.KieServicesClient;
import org.kie.server.client.KieServicesConfiguration;
import org.kie.server.client.KieServicesFactory;
//user "anton" must have role "kie-server" assigned
KieServicesConfiguration config = KieServicesFactory.
newRestConfiguration("http://localhost:8080/kie-server/services/rest/server",
"anton",
"password1!");
KieServicesClient client = KieServicesFactory.newKieServicesClient(config);
// the request "xStreamXml" we generated in previous step
// "ListenerReproducer" is the name of the Container
ServiceResponse<String> response = client.executeCommands("ListenerReproducer", xStreamXml);
System.out.println(response.getResult());