JBoss.org Community Documentation

- Prev
- Next

## Chapter 19. KIE Execution Server

## 19.1. Introduction

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.

## 19.2. Installing the KIE Execution Server

The KIE Execution Server is distributed as a web application archive (WAR) file. The WAR file comes in three different flavors:

- webc - WAR for ordinary Web (Servlet) containers like Tomcat
- ee6 - WAR for JavaEE 6 containers like JBoss EAP 6.x
- ee7 - WAR for JavaEE 7 containers like WildFly 8.x

To install the KIE Execution Server and verify it is running, complete the following steps:

1. Deploy the WAR file into your web container.

2. Create a user with the role of `kie-server` on the container.

3. Test that you can access the execution engine by navigating to the endpoint in a browser window: `http://SERVER:PORT/CONTEXT/services/rest/server/`.

4. When prompted for username/password, type in the username and password that you created in step 2.

5. Once authenticated, you will see an XML response in the form of engine status, similar to this:

   Example 19.1. Sample handshaking server response

       <response type="SUCCESS" msg="KIE Server info">
         <kie-server-info>
           <version>6.2.0.Final</version>
         </kie-server-info>
       </response>

### 19.2.1. Installation details for different containers

#### 19.2.1.1. Tomcat 7.x/8.x

1. 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`.

2. Download kie-server-6.2.0.Final-webc.war and place it into `TOMCAT_HOME/webapps`.

3. 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 19.2. Username and role definition for Tomcat

       <role rolename="kie-server"/>
       <user username="serveruser" password="my.s3cr3t.pass" roles="kie-server"/>

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

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

#### 19.2.1.2. WildFly 8.x

1. 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`.

2. Download kie-server-6.2.0.Final-ee7.war and place it into `WILDFLY_HOME/standalone/deployments`.

3. 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`.

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

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

## 19.3. Registering a 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

## 19.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.

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

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

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

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

## 19.5. Managing Containers

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

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

### 19.5.2. Stopping and Deleting a Container

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

### 19.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.

## 19.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.

### 19.6.1. [GET] /

Returns the Execution Server information

Example 19.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>

### 19.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.

### 19.6.3. [GET] /containers

Returns a list of containers that have been created on this Execution Server.

Example 19.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>

### 19.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 19.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>

### 19.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 19.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 19.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>

### 19.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 19.8. Example Server Response disposing a container

    <response type="SUCCESS" msg="Container MyProjectContainer successfully disposed."/>

### 19.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 19.9. Example Server Request to fire all rules

    <fire-all-rules/>

Any valid command (of the type org.kie.api.Command) with correct attributes can be used.

### 19.6.8. [GET] /containers/{id}/release-id

Returns the full release id for the Container specified by the id.

Example 19.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>

### 19.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 19.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 19.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>

### 19.6.10. [GET] /containers/{id}/scanner

Returns information about the scanner for this Container's automatic updates.⁠

Example 19.13. Example Server Response

    <response type="SUCCESS" msg="Scanner info successfully retrieved">
      <kie-scanner status="DISPOSED"/>
    </response>

### 19.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 19.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 19.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.

- PrevPart VI. KIE Server
- Up
- Home
- NextPart VII. Drools Examples