Chapter 22. KIE Execution Server

Property	Value	Description	Required
org.drools.server.ext.disabled	boolean (default is "false")	If true, disables the BRM support (i.e. rules support).	No
org.jbpm.server.ext.disabled	boolean (default is "false")	If true, disables the BPM support (i.e. processes support)	No
org.kie.server.id	string	An arbitrary ID to be assigned to this server. If a remote controller is configured, this is the ID under which the server will connect to the controller to fetch the kie container configurations.	No. If not provided, an ID is automatically generated.
org.kie.server.user	string (default is "kieserver")	User name used to connect with the kieserver from the controller, required when running in managed mode	No
org.kie.server.pwd	string (default is "kieserver1!")	Password used to connect with the kieserver from the controller, required when running in managed mode	No
org.kie.server.controller	comma separated list of urls	List of urls to controller REST endpoint. E.g.: `http://localhost:8080/kie-wb/rest`	Yes when using a controller
org.kie.server.controller.user	string (default is "kieserver")	Username used to connect to the controller REST api	Yes when using a controller
org.kie.server.controller.pwd	string (default is "kieserver1!")	Password used to connect to the controller REST api	Yes when using a controller
org.kie.server.location	URL location of kie server instance	The URL used by the controller to call back on this server. E.g.: `http://localhost:8230/kie-server/services/rest/server`	Yes when using a controller
org.kie.server.domain	string	JAAS LoginContext domain that shall be used to authenticate users when using JMS	No
org.kie.server.bypass.auth.user	boolean (default is "false")	Allows to bypass the authenticated user for task related operations e.g. queries	No
org.kie.server.repo	valid file system path (default is ".")	Location on local file system where kie server state files will be stored	No
org.kie.server.persistence.ds	string	Datasource JNDI name	Yes when BPM support enabled
org.kie.server.persistence.tm	string	Transaction manager platform for Hibernate properties set	Yes when BPM support enabled
org.kie.server.persistence.dialect	string	Hibernate dialect to be used	Yes when BPM support enabled
org.jbpm.ht.callback	string	One of supported callbacks for Task Service (default jaas)	No
org.jbpm.ht.custom.callback	string	Custom implementation of UserGroupCallback in case org.jbpm.ht.callback was set to ‘custom’	No
kie.maven.settings.custom	valid file system path	Location of custom settings.xml for maven configuration	No
org.kie.executor.interval	integer (default is 3)	Number of time units between polls by executor	No
org.kie.executor.pool.size	integer (default is 1)	Number of threads in the pool for async work	No
org.kie.executor.retry.count	integer (default is 3)	Number of retries to handle errors	No
org.kie.executor.timeunit	TimeUnit (default is "SECONDS")	TimeUnit representing interval	No
org.kie.executor.disabled	boolean (default is "false")	Disables executor completely	No
kie.server.jms.queues.response	string (default is "queue/KIE.SERVER.RESPONSE")	JNDI name of response queue for JMS	No
org.kie.server.controller.connect	long (default is 10000)	Waiting time in milliseconds between repeated attempts to connect kie server to controller when kie server starts up	No

22.2.2. Installation details for different containers

22.2.2.1. Tomcat 7.x/8.x

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.Final-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. Please read the table above for the bootstrap switches that can be used to properly configure the instance. For instance:
```
./startup.sh -Dorg.kie.server.id=first-kie-server 
             -Dorg.kie.server.location=http://localhost:8080/kie-server/services/rest/server
```
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.

Important

You can not leverage the JMS interface when running on Tomcat, or any other Web container. The Web container version of the WAR contains only the REST interface.

22.2.2.2. WildFly 8.x

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.Final-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 'kieserver' -p 'kieserver1!' -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 <bootstrap_switches>. You can check out the standard output or WildFly logs in WILDFLY_HOME/standalone/logs to see if the application deployed successfully. Please read the table above for the bootstrap switches that can be used to properly configure the instance. For instance:
```
./standalone.sh  --server-config=standalone-full.xml 
                 -Djboss.socket.binding.port-offset=150
                 -Dorg.kie.server.id=first-kie-server 
                 -Dorg.kie.server.location=http://localhost:8230/kie-server/services/rest/server
```
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.

22.3. Kie Server setup

Important

Server setup and registration changed significantly from versions 6.2 and before. The following applies only to version 6.3 and forward.

22.3.1. Managed Kie Server

A managed instance is one that requires a controller to be available to properly startup the Kie Server instance.

A Controller is a component responsible for keeping and managing a Kie Server Configuration in centralized way. Each controller can manager multiple configurations at once and there can be multiple controllers in the environment. Managed KIE Servers can be configured with a list of controllers but will connect to only one at a time.

Note

It's important to mention that even though there can be multiple controllers they should be kept in sync to make sure that regardless which one of them is contacted by KIE Server instance it will provide same set of configuration.

At startup, if a Kie Server is configured with a list of controllers, it will try succesivelly to connect to each of them until a connection is successfully stablished with one of them. If for any reason a connection can't be stablished, the server will not start, even if there is local storage available with configuration. This happens by design in order to ensure consistency. For instance, if the Kie Server was down and the configuration has changed, this restriction guarantees that it will run with up to date configuration or not at all.

Note

In order to run the Kie Server in standalone mode, without connecting to any controllers, please see "Unmanaged Kie Server".

The configuration sets, among other things:

kie containers to be deployed and started
configuration items - currently this is a place holder for further enhancements that will allow remotely configure KIE Execution Server components - timers, persistence, etc

The Controller, besides providing configuration management, is also responsible for overall management of Kie Servers. It provides a REST api that is divided into two parts:

the controller itself that is exposed to interact with KIE Execution Server instances
an administration API that allows to remotely manage Kie Server instances:

The controller deals only with the Kie Server configuration or definition to put it differently. It does not handle any runtime components of KIE Execution Server instances. They are always considered remote to controller. The controller is responsible for persisting the configuration to preserve restarts of the controller itself. It should manage the synchronization as well in case multiple controllers are configured to keep all definitions up to date on all instances of the controller.

By default controller is shipped with Kie Workbench and provides a fully featured management interface (both REST api and UI). It uses underlying git repository as persistent store and thus when GIT repositories are clustered (using Apache Zookeeper and Apache Helix) it will cover the controllers synchronization as well.

The diagram above illustrates the single controller (workbench) setup with multiple Kie Server instances managed by it.

The diagram bellow illustrates the clustered setup where there are multiple instances of controller synchronized over Zookeeper.

In the above diagram we can see that the Kie Server instances are capable of connecting to any controllers, but they will connect to only one. Each instance will attempt to connect to controller as long as it can reach one. Once connection is established with one of the controllers it will skip the others.

22.3.1.1. Working with managed servers

There are two approaches that users can take when working with managed KIE Server instances:

Configuration first: with this approach, a user will start working with the controller (either UI or REST api) and create and configure Kie Server definitions. That consists basically of an identification for the server definition (id and name + optionally version for improved readability) and the configuration for the Kie Containers to run on the server.
Registration first: with this approach, the Kie Server instances are started first and auto register themselves on controller. The user then can configure the Kie Containers. This option simply skips the registration step done in the first approach and populates it with server id, name and version directly upon auto registration. There are no other differences between the two approaches.

22.3.2. Unmanaged KIE Execution Server

An unmanaged Kie Server is in turn just a standalone instance, and thus must be configured individually using REST/JMS api from the Kie Server itself. There is no controller involved. The configuration is automatically persisted by the server into a file and that is used as the internal server state, in case of restarts.

The configuration is updated during the following operations:

deploy Kie Container
undeploy Kie Container
start Kie Container
stop Kie Container

Note

if the Kie Server is restarted, it will try to restablish the same state that was persisted before shutdown. That means that Kie Containers that were running, will be started, but the ones that were stopped/disposed before, will not.

In most use cases, the Kie Server should be executed in managed mode as that provides some benefits, like a web user interface (if using the workbench as a controller) and some facilities for clustering.

22.4. Creating a Kie Container

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).

Important
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.

Important
The Container name must be unique inside each execution server and must not contain any spaces.

Note

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.

22.5. Managing Containers

Containers within the Execution Server can be started, stopped and updated from within KIE Workbench.⁠

22.5.1. Starting a Container

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).⁠

22.5.2. Stopping and Deleting a Container

22.5.3. Updating a Container

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:

Important

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.

22.6. REST API

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.

22.6.1. [GET] /

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>

22.6.2. [POST] /

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.

22.6.3. [GET] /containers

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>

22.6.4. ⁠[GET] /containers/{id}

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>

22.6.5. [PUT] /containers/{id}

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>

22.6.6. [DELETE] /containers/{id}

⁠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."/>

22.6.7. [POST] /containers/{id}

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):

Example 22.9. Example Server Request to fire all rules

<fire-all-rules/>

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.

22.6.8. [GET] /containers/{id}/release-id

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>

22.6.9. [POST] /containers/{id}/release-id

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>

22.6.10. [GET] /containers/{id}/scanner

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>

22.6.11. [POST] /containers/{id}/scanner

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.

22.6.12. Native REST client for Execution Server

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());