Running Rules on WildFly with Kie Server

User Rating: 5 / 5

Star ActiveStar ActiveStar ActiveStar ActiveStar Active
 

In this article we are going to show how the Kie Server works and how to use it in WildFly 8.2.

What is the KIE Execution Server? The Kie Server is a Java web application that allow us to expose rules and business process to be executed remotely using REST and JMS interfaces. The difference between Kie Server and jBPM Console is that Kie Server is focused in remote execution, while jBPM console offers a complete authoring environment, including process execution features and a remote API.

How it works? The Kie Server itself is a web application that can be deployed in JBoss EAP, Wildfly, tomcat and other Java application servers or web containers. It works by accessing kjars from a Maven repository and exposing its rules and process throught HTTP or JMS.

Maven Repository <- KIE SERVER  <-> Remote JMS/REST Clients

The important concepts behind the KIE Execution server for us today are:

Kie Server: execution server purely focusing on providing runtime environment for both rules and processes. These capabilities are provided by Kie Server Extensions. More capabilities can be added by further extensions (e.g. customer could add his own extensions in case of missing functionality that will then use infrastructure of the KIE Server). A Kie Server instance is a standalone Kie Server executing on a given application server/web container. A Kie Server instantiates and provides support for multiple Kie Containers.

Kie Server Extension: a "plugin" for the Kie Server that adds capabilities to the server. The Kie Server ships with two default kie server extensions: BRM and BPM.

Kie Container: an in-memory instantiation of a kjar, allowing for the instantiation and usage of its assets (domain models, processes, rules, etc). A Kie Server exposes Kie Containers through a standard API over transport protocols like REST and JMS.

Controller: a server-backed REST endpoint that will be responsible for managing KIE Server instances. Such end point must provide following capabilities:

  • respond to connect requests
  • sync all registered containers on the corresponding Kie Server ID
  • respond to disconnect requests

Kie Server state: currently known state of given Kie Server instance. This is a local storage (by default in file) that maintains the following information:

  • list of registered controllers
  • list of known containers
  • kie server configuration

The server state is persisted upon receival of events like: Kie Container created, Kie Container is disposed, controller accepts registration of Kie Server instance, etc.

Kie Server ID: an arbitrary assigned identifier to which configurations are assigned. At boot, each Kie Server Instance is assigned an ID, and that ID is matched to a configuration on the controller. The Kie Server Instance fetches and uses that configuration to setup itself.

This was took from KIE Server documentation. Notice that the concept of controller is similar to Widlfly/JBoss EAP domain mode, however, today we will use the server in unmanaged mode - it will make easy to achieve our goal, which is introduce how Kie Server works.

Installing Kie Server on Wildfly 8.2 

Supposing the same server you will run the Kie Server application has Java 8 and Maven installed, the steps to install Kie Server on Widlfly 8.2 would be:

  • Download and unzip wildfly 8.2;
  • Download and unzip Kie Server 6.3;
  • Copy the file kie-server-6.3.0.Final-ee7.war into wildfly-8.2.0.Final/standalone/deployments/ directory;
  • Add an application user with the role kie-server using the add-user script:
 $ ./add-user.sh -a -u kieserver -p password1! -g admin,kie-server

Start wildfly using the standalone-full.xml profile and providing a few Kie server parameters:

$ standalone.sh  -c standalone-full.xml -Dorg.kie.server.id=hello-kie-server -Dorg.kie.server.location=http://localhost:8080/kie-server-6.3.0.Final-ee7/services/rest/server

Test the installation using a browser or curl. Accessing the endpoint http://localhost:8080/kie-server-6.3.0.Final-ee7/services/rest/server should return the main information about the Kie Server installation:

Containers and kjars

We can use the Kie Server REST API to add containers. Each container is related to a GAV - Group, ArtifactId and Version, of a Maven artifact. This maven artifact must be a kjar and once we create a container from it, we can execute its processes and rules.

If you don’t know what a kjar is, here’s a brief description took from jBPM documentation: kjars are simple JAR files that include a descriptor for KIE system to produce KieBase and KieSession. Descriptor of the kjar is represented as XML file.

Our simple kjar:

For this article we will use a simple kjar with a single Drools business rule and a really simple process. Remember that kjars are maven artifacts and structure of a kjar is the same of the default structure of a maven artifact, see our project files and structure:

kie server tutorial jboss

And here is the content of each file:

pom.xml: It is the maven descriptor of our project:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.mastertheboss.kieserver</groupId>
  <artifactId>hello-kie-server</artifactId>
  <packaging>jar</packaging>
  <version>1.0</version>
  <name>hello-kie-server</name>
  <url>http://www.mastertheboss.com/</url>
</project>

kmodule.xml: kmodule is a XML file, the descriptor used in kjars.

<kmodule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://jboss.org/kie/6.0.0/kmodule" />

hello.drl: A simple rule file that will be fired once a String is in the working memory:

rule 'hello'
when
	$name: String()
then
	System.out.println("Hello " + $name);
end

hello.bpmn2: it translate to the following simple process:

kie server tutorial jboss

The content of Say Hello Script script task is:

System.out.println("Hello World from process, " + name + "!");

name is a process variable that can be passed as parameter when starting the process. This project can be found at github at: https://github.com/jesuino/hello-kie-server

Now we must install the kjar on our local maven repository. It can be done using the following maven command:

mvn clean install

Creating the container

To create the container we use the REST API by sending a PUT HTTP request to the endpoint http://localhost:8080/kie-server-6.3.0.Final-ee7/services/rest/server/containers/hello, where hello is the name and the ID of the container. This request uses authentication(remember the user you added later?) and we must send the kjar artifact maven information, see:

$ curl -X PUT -H 'Content-type: application/xml' -u 'kieserver:kieserver1!' --data @createHelloContainer.xml http://localhost:8080/kie-server-6.3.0.Final-ee7/services/rest/server/containers/hello

The content of the file createHelloContainer.xml is:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<kie-container container-id="hr">
    <release-id>
        <group-id>org.mastertheboss.kieserver</group-id>
        <artifact-id>hello-kie-server</artifact-id>
        <version>1.0</version>
    </release-id>
</kie-container>

Now that the container is created and started. We can see it in the server logs:

22:00:48,576 INFO  [org.drools.compiler.kie.builder.impl.KieRepositoryImpl] (EJB default - 1) KieModule was added: ZipKieModule[releaseId=org.mastertheboss.kieserver:hello-kie-server:1.0,file=/home/wsiqueir/.m2/repository/org/mastertheboss/kieserver/hello-kie-server/1.0/hello-kie-server-1.0.jar]
22:00:48,694 INFO  [org.kie.scanner.embedder.MavenEmbedderUtils] (EJB default - 1) Not in OSGi: using plexus based maven parser
22:00:49,378 INFO  [org.kie.server.services.jbpm.JbpmKieServerExtension] (EJB default - 1) Container hello created successfully
22:00:49,379 INFO  [org.kie.server.services.impl.KieServerImpl] (EJB default - 1) Container hello (for release id org.mastertheboss.kieserver:hello-kie-server:1.0) successfully started

The endpoint to send commands and interact with business process for the container hello is: http://localhost:8080/kie-server-6.3.0.Final-ee7/services/rest/server/containers/instances/hello

Below you can see the details about the instances we created:

$ curl -u 'kieserver:kieserver1!'  -H 'Accept: application/json' 'http://localhost:8080/kie-server/services/rest/server/containers/hello' 
{
  "type" : "SUCCESS",
  "msg" : "Info for container hello",
  "result" : {
    "kie-container" : {
      "status" : "STARTED",
      "scanner" : {
        "status" : "DISPOSED",
        "poll-interval" : null
      },
      "container-id" : "hello",
      "release-id" : {
        "version" : "1.0",
        "group-id" : "org.mastertheboss.kieserver",
        "artifact-id" : "hello-kie-server"
      },
      "resolved-release-id" : {
        "version" : "1.0",
        "group-id" : "org.mastertheboss.kieserver",
        "artifact-id" : "hello-kie-server"
      }
    }
  }
}

Now we are ready to execute rules and business process using REST. The REST endpoint works by supportting JSON and XML formats currently - XML can be based on JAXB or XStream java XML frameworks.

Executing business rules

The execution of rules is more HTTP oriented, personally I would not say it is REST, but POX, because we send requests with marshalled Drools commands to a single endpoint. In the command below, marshalled in JSON, we send two insert and a fire all rules command (actually they are inside a BatchExecutionCommand object):

{
  "commands" : [ 
    { "insert" : { "object" : "William"   } }, 
    { "insert" : { "object" : "Francesco" } }, 
    { "fire-all-rules" : { } }
  ]
}

To send the HTTP request we must include the HTTP header X-KIE-ContentType informing what data format we are using and now we use the method POST, see:

$ curl -X POST -H 'X-KIE-ContentType: JSON' -H 'Content-type: application/json' -u 'kieserver:kieserver1!' --data @droolsCommands.json http://localhost:8080/kie-server-6.3.0.Final-ee7/services/rest/server/containers/instances/hello

kie server tutorial jboss

If you check the server logs, you can see that the rules were correctly fired:

21:10:11,095 INFO  [stdout] (default task-15) Hello Francesco
21:10:11,095 INFO  [stdout] (default task-15) Hello William

Executing business processes

Execute processes uses a REST API. We can start by querying the available processes definitions using the URL http://localhost:8080/kie-server-6.3.0.Final-ee7/services/rest/server/queries/processes/definitions

You can see our business process was correctly installed in Kie Server. Now let’s start a process instance by using POST and JSON format on the following URL: http://localhost:8080/kie-server-6.3.0.Final-ee7/services/rest/server/containers/hello/processes/hello/instances

$ curl -X POST -H 'Content-type: application/json' -H 'X-KIE-ContentType: JSON' -u 'kieserver:kieserver1!' --data @startProcess.json http://localhost:8080/kie-server-6.3.0.Final-ee7/services/rest/server/containers/hello/processes/hello/instances

kie server tutorial jboss

The content of the file startProcess.json is a map to send the value of the process parameter name:

{
  "name" : "William"
}

It will return the process instance ID. In this case we have a simple process, but in other cases we can keep it to do other operations with the server. Anyway, once we send this request, we should be able to see in the server logs that the process was correct

21:35:40,841 INFO  [stdout] (default task-23) Hello World from process, William!

That’s all for process. Of course the API is a little more complex, since it includes signalling process, tasks management, variables, etc. But this is all for today.

Conclusion

In this article we introduced the Kie Server project. The source code of the sample kjar and the commands can be found at github (https://github.com/jesuino/hello-kie-server).

Of course there are a lot to learn, like how to use the API to manage tasks and jobs and explore the controller mode. Maciej has a good and complete article series about the Kie Server, you can refer to it if you want to learn more about it.

Author: William Antônio Siqueira has about 6 years of Java programming experience. He started with JavaFX since its first release and since then he follows all the JavaFX updates. He regularly blogs about JavaFX, JBoss and Java application on fxapps.blogspot.com He also founded a JUG on his region which has about 100 members. Currently he works for Red Hat supporting and helping on JBoss products maintenance. His main areas of interest are Java EE, REST Web Services, jBPM and JavaFX.

Follow us on Twitter