Chapter 6. Getting Started with Rules and Facts

1. Create a fact model.

   Create a Plain old Java object (POJO) on which a rule will operate. In this example, a Person.java file in a directory my-project is created. The Person class contains getter and setter methods to set and retrieve the first name, last name, hourly rate, and the wage of a person:

   import org.kie.api.KieServices;
   import org.kie.api.runtime.KieContainer;
   import org.kie.api.runtime.KieSession;
   
     public class Person {
       private String firstName;
       private String lastName;
       private Integer hourlyRate;
       private Integer wage;
   
       public String getFirstName() {
         return firstName;
       }
   
       public void setFirstName(String firstName) {
         this.firstName = firstName;
       }
   
       public String getLastName() {
         return lastName;
       }
   
       public void setLastName(String lastName) {
         this.lastName = lastName;
       }
   
       public Integer getHourlyRate() {
         return hourlyRate;
       }
   
       public void setHourlyRate(Integer hourlyRate) {
         this.hourlyRate = hourlyRate;
       }
   
       public Integer getWage(){
         return wage;
       }
   
       public void setWage(Integer wage){
         this.wage = wage;
       }
     }

2. Create a rule.

   Create a rule file in the .drl format under the my-project directory. The following Person.drl rule calculates the wage and hourly rate values and displays a message based on the result afterwards.

   dialect "java"
   
   rule "Wage"
     when
       Person(hourlyRate * wage > 100)
       Person(name : firstName, surname : lastName)
     then
       System.out.println("Hello" + " " + name + " " + surname + "!");
       System.out.println("You are rich!");
   end

3. Create a main class.

   Create a main class and save it to the same directory as the POJO created earlier. The main class will load the knowledge base and fire rules. In the following example, a main class DroolsTest.java is created.

   In the main class:

   1. Add the following import statements to import KIE services, a KIE container, and a KIE session:

      import org.kie.api.KieServices;
      import org.kie.api.runtime.KieContainer;
      import org.kie.api.runtime.KieSession;

   2. Load the knowledge base, insert facts, and fire the rule from the main() method which passes the fact model to the rule:

      public class DroolsTest {
        public static final void main(String[] args) {
          try {
            // Load the knowledge base:
            KieServices ks = KieServices.Factory.get();
            KieContainer kContainer = ks.getKieClasspathContainer();
            KieSession kSession = kContainer.newKieSession();
      
            // Go!
            Person p = new Person();
            p.setWage(12);
            p.setFirstName("Tom");
            p.setLastName("Summers");
            p.setHourlyRate(10);
      
            kSession.insert(p);
            kSession.fireAllRules();
          }
      
          catch (Throwable t) {
            t.printStackTrace();
          }
        }
      }

4. Download the Red Hat JBoss BRMS 6.4 Core Engine ZIP file from the Red Hat Customer Portal and extract it under my-project/BRMS-engine-jars/.

5. In the my-project/META-INF directory, create a kmodule.xml metadata file with the following content:

   <?xml version="1.0" encoding="UTF-8"?>
   <kmodule xmlns="http://www.drools.org/xsd/kmodule">
   </kmodule>

6. Build the example.

   To compile and build your Java files, navigate to the my-project directory on the command line and run the following command:

   javac -classpath "./BRMS-engine-jars/*:." DroolsTest.java

7. Run the example.

   If there are no compilation errors, run the following command to execute the rule:

   java -classpath "./BRMS-engine-jars/*:." DroolsTest

   The expected output looks similar to the following:

   Hello Tom Summers!
   You are rich!

1. Create a basic Maven archetype.

   Navigate to a directory where you want to create a Maven archetype and run the following command:

   mvn archetype:generate -DgroupId=com.sample.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

   This creates a directory my-app with the following structure:

   my-app
   |-- pom.xml
   `-- src
       |-- main
       |   `-- java
       |       `-- com
       |           `-- mycompany
       |               `-- app
       |                   `-- App.java
       `-- test
           `-- java
               `-- com
                   `-- mycompany
                       `-- app
                           `-- AppTest.java

   The my-app directory contains:

   • A src/main directory for storing the application’s sources.
   • A src/test directory for storing the test sources.
   • A pom.xml file with the project’s configuration.

2. Create a fact model.

   A fact model is a POJO, based on which a rule will operate. Create a Person.java file under the my-app/src/main/java/com/mycompany/app directory. The Person class contains getter and setter methods to set and retrieve the first name, last name, hourly rate, and the wage of a person.

   package com.mycompany.app;
   
     public class Person {
   
       private String firstName;
       private String lastName;
       private Integer hourlyRate;
       private Integer wage;
   
       public String getFirstName() {
         return firstName;
       }
   
       public void setFirstName(String firstName) {
         this.firstName = firstName;
       }
   
       public String getLastName() {
         return lastName;
       }
   
       public void setLastName(String lastName) {
         this.lastName = lastName;
       }
   
       public Integer getHourlyRate() {
         return hourlyRate;
       }
   
       public void setHourlyRate(Integer hourlyRate) {
         this.hourlyRate = hourlyRate;
       }
   
       public Integer getWage(){
         return wage;
       }
   
       public void setWage(Integer wage){
         this.wage = wage;
       }
     }

3. Create a rule.

   Create a rule file in the .drl format under the my-app/src/main/resources/rules directory. See the following example with a simple rule Person.drl which imports the Person class:

   package com.mycompany.app;
   import com.mycompany.app.Person;
   
   dialect "java"
   
   rule "Wage"
     when
       Person(hourlyRate * wage > 100)
       Person(name : firstName, surname : lastName)
     then
       System.out.println("Hello " + name + " " + surname + "!");
       System.out.println("You are rich!");
   end

   The rule above calculates the wage and hourly rate values and displays a message based on the result afterwards.

4. In the my-app/src/main/resources/META-INF directory, create a metadata file kmodule.xml with the following content:

   <?xml version="1.0" encoding="UTF-8"?>
   <kmodule xmlns="http://www.drools.org/xsd/kmodule">
   </kmodule>

5. Set project dependencies.

   Specify the libraries your application requires in the my-app/pom.xml configuration file. Provide the Red Hat JBoss BRMS dependencies as well as the group ID, artifact ID, and version (GAV) of your application as shown below:

   <?xml version="1.0" encoding="UTF-8"?>
   <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/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.mycompany.app</groupId>
   <artifactId>my-app</artifactId>
   <version>1.0.0</version>
   <repositories>
     <repository>
       <id>jboss-ga-repository</id>
       <url>http://maven.repository.redhat.com/ga/</url>
     </repository>
   </repositories>
   <dependencies>
     <dependency>
       <groupId>org.drools</groupId>
       <artifactId>drools-compiler</artifactId>
       <version>VERSION</version>
     </dependency>
     <dependency>
       <groupId>org.kie</groupId>
       <artifactId>kie-api</artifactId>
       <version>VERSION</version>
     </dependency>
     <dependency>
       <groupId>junit</groupId>
       <artifactId>junit</artifactId>
       <version>4.11</version>
       <scope>test</scope>
     </dependency>
   </dependencies>
   </project>

   For the supported Maven artifact version, see section Supported Component Versions of the Red Hat JBoss BPM Suite Installation Guide.

6. Test the example.

   Use the testApp method in my-app/src/test/java/com/mycompany/app/AppTest.java to test the rule. The AppTest.java file is created by Maven by default.

   In the AppTest.java file:

   1. Add the following import statements to import KIE services, a KIE container, and a KIE session:

      import org.kie.api.KieServices;
      import org.kie.api.runtime.KieContainer;
      import org.kie.api.runtime.KieSession;

   2. Load the knowledge base, insert facts, and fire the rule from the testApp() method which passes the fact model to the rule:

      public void testApp() {
      
        // Load the knowledge base:
        KieServices ks = KieServices.Factory.get();
        KieContainer kContainer = ks.getKieClasspathContainer();
        KieSession kSession = kContainer.newKieSession();
      
        // Set up the fact model:
        Person p = new Person();
        p.setWage(12);
        p.setFirstName("Tom");
        p.setLastName("Summers");
        p.setHourlyRate(10);
      
        // Insert the person into the session:
        kSession.insert(p);
      
        // Fire all rules:
        kSession.fireAllRules();
      }

7. Build the example.

   On the command line, navigate to the my-app directory and run the following command:

   mvn clean install

   Note that executing this command for the first time may take a while.

   The expected output looks similar to the following:

   Hello Tom Summers!
   You are rich!
   Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.194 sec
   
   Results :
   
   Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
   
   [INFO]
   ...
   [INFO] --------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] --------------------------------------------------------------
   [INFO] Total time: 6.393 s
   ...
   [INFO] --------------------------------------------------------------

1. Create a BRMS project.

   To create a BRMS project in Red Hat JBoss Developer Studio:

   1. Start Red Hat JBoss Developer Studio and click File → New → Project.
   2. In the New Project dialog window that opens, select Drools → Drools Project and click Next.
   3. Click on the second icon to create a project and populate it with some example files to help you get started quickly. Click Next.

   4. Enter a name of the project a select the Maven radio button as the project building option. Specify the GAV values which form the project’s fully qualified name, for example:

      • Group ID: com.mycompany.app
      • Artifact ID: my-app
      • Version: 1.0.0
   5. Click Finish.

   This configuration sets up a basic project structure, class path, and sample rules. The project structure is as follows:

   My-Project
    `-- src/main/java
       | `-- com.sample
       |    `-- DecisionTable.java
       |    `-- DroolsTest.java
       |    `-- ProcessTest.java
       |
    `-- src/main/resources
       | `-- dtables
       |    `-- Sample.xls
       | `-- process
       |    `-- sample.bpmn
       | `-- rules
       |    `-- Sample.drl
       | `-- META-INF
       |
    `-- JRE System Library
       |
    `-- Maven Dependencies
       |
    `-- Drools Library
       |
    `-- src
       |
    `-- target
       |
    `-- pom.xml

   Notice the following:

   • A Sample.drl rule file in the src/main/resources directory, containing an example Hello World and GoodBye rules.
   • A DroolsTest.java file under the src/main/java directory in the com.sample package. The DroolsTest class can be used to execute rules.
   • The Drools Library directory which acts as a custom class path containing JAR files necessary for execution.

2. Create a fact model.

   The DroolsTest.java file contains a sample POJO Message with getter and setter methods. You can edit this class or create a different POJO. In this example, a class Person containing methods to set and retrieve the first name, last name, hourly rate, and wage of a person is used.

   public static class Person {
   
     private String firstName;
     private String lastName;
     private Integer hourlyRate;
     private Integer wage;
   
     public String getFirstName() {
       return firstName;
     }
   
     public void setFirstName(String firstName) {
       this.firstName = firstName;
     }
   
     public String getLastName() {
       return lastName;
     }
   
     public void setLastName(String lastName) {
       this.lastName = lastName;
     }
   
     public Integer getHourlyRate() {
       return hourlyRate;
     }
   
     public void setHourlyRate(Integer hourlyRate) {
       this.hourlyRate = hourlyRate;
     }
   
     public Integer getWage(){
       return wage;
     }
   
     public void setWage(Integer wage){
       this.wage = wage;
     }
   }

3. Update the main() method.

   The DroolsTest.java file contains a main() method that loads the knowledge base, inserts facts, and fires rules. Update the method to pass the object Person to a rule:

   public static final void main(String[] args) {
     try {
       // Load the knowledge base:
       KieServices ks = KieServices.Factory.get();
       KieContainer kContainer = ks.getKieClasspathContainer();
       KieSession kSession = kContainer.newKieSession("ksession-rules");
   
       // Go!
       Person p = new Person();
       p.setWage(12);
       p.setFirstName("Tom");
       p.setLastName("Summers");
       p.setHourlyRate(10);
   
       kSession.insert(p);
       kSession.fireAllRules();
     }
   
     catch (Throwable t) {
       t.printStackTrace();
     }
   }

   To load the knowledge base, get a KieServices instance and a class-path-based KieContainer and build the KieSession with the KieContainer. In the example above, a session ksession-rules matching the one defined in kmodule.xml file is passed.

4. Create a rule.

   The rule file Sample.drl contains an example of two rules. Edit this file or create a new one. In your rule file:

   1. Specify the package name:

      package com.sample

   2. Import facts:

      import com.sample.DroolsTest.Person;

   3. Write the rule:

      dialect "java"
      
      rule "Wage"
        when
          Person(hourlyRate * wage > 100)
          Person(name : firstName, surname : lastName)
        then
          System.out.println("Hello" + " " + name + " " + surname + "!");
          System.out.println("You are rich!");
      end

5. Test the rule.

   Right-click the DroolsTest.java file and select Run As → Java Application.

   The expected output looks similar to the following:

   Hello Tom Summers!
   You are rich!

1. Start the server and log in to Business Central. For more information how to do so, see sections Starting Server and Logging into Business Central of Red Hat JBoss BPM Suite Installation Guide.

2. Create a repository structure and a project.

   1. In Business Central, click Authoring → Administration.
   2. Click Organizational Units → Manage Organizational Units.
   3. In the displayed Organizational Unit Manager, click Add.

   4. In the Add New Organizational Unit dialog window, define the unit properties. For example:

      • Name: EmployeeWage
      • Owner: Employee
   5. Click Ok.
   6. Click Repositories → New repository.

   7. In the New Repository dialog window, define the repository properties. For example:

      • Repository Name: EmployeeRepo
      • In Organizational Unit: EmployeeWage
   8. Click Finish.
   9. In the main menu, click Authoring → Project Authoring.
   10. In Project Explorer, navigate to the EmployeeWage organizational unit and the EmployeeRepo repository.
   11. Click New Item → Project.

   12. In the New Project dialog window, enter a name of the project, for example MyProject, and specify project’s Maven properties. For example:

       • Group ID: org.bpms
       • Artifact ID: MyProject
       • Version: 1.0.0
   13. Click Finish.

3. Create a fact model.

   1. Click New Item → Data Object.

   2. In the Create new Data Object dialog window, enter the object’s name and specify a package. For example:

      • Data Object: Person
      • Package: org.bpms.myproject
   3. Click Ok.

   4. In the Editor than opens, click Add field and create four fields with the following values by clicking Create and continue:

      • Id: firstName, Type: String
      • Id: lastName, Type: String
      • Id: hourlyRate, Type: Integer
      • Id: wage, Type: Integer
   5. Save the project.

4. Create a rule.

   1. Click New Item → DRL file.

   2. In the Create new DRL file dialog window, enter a name of the rule and specify a package. For example:

      • DRL file: MyRule
      • Package: org.bpms.myproject
   3. Click Ok.

   4. Paste the definition of a rule shown below into the DRL Editor or create your own rule.

      package org.bpms.myproject;
      
      rule "MyRule"
      ruleflow-group "MyProjectGroup"
        when
          Person(hourlyRate * wage > 100)
          Person(name : firstName, surname : lastName)
        then
          System.out.println("Hello" + " " + name + " " + surname + "!");
          System.out.println("You are rich!");
      end

   5. Click Save.

5. Create a business process with a business rule task.

   1. Click New Item → Business Process.

   2. In the Create new Business Process dialog window, enter a name of the business process and specify a package. For example:

      • Business Process: MyProcess
      • Package: org.bpms.myproject
   3. Click Ok. The Business Process Editor opens with a Start Event element on the canvas.
   4. Expand the Object Library palette on the left and drag and drop a Business Rule task (Tasks → Business Rule) on the canvas.
   5. Click on an empty space on the canvas and open the Properties panel on the right. Click on the Value text field of the Variable Definitions property. Click on the arrow that appears on the right to open the Editor for Variable Definitions dialog window.

   6. Click Add Variable and define the following variable:

      • Name: person
      • Defined Types: Person [org.bpms.myproject]
   7. Click Ok.
   8. Click on the Business Rule task on the canvas and in the Properties panel on the right, set the Name of the task, for example My_Rule.
   9. Click on the Value text field of the Ruleflow Group property. Click on the arrow that appears on the right to open the Editor for RuleFlow Groups dialog window. Select MyProjectGroup and click Save.

   10. Click on the Value text field of the Assignments property. Click on the arrow that appears on the right to open the My_Rule Data I/O dialog window and click Add next to the Data Inputs and Assignments option to add the following:

       • Name: Person
       • Data Type: Person [org.bpms.myproject]
       • Source: person

   11. Click Save.

       You have now successfully created an object that maps to the variables you set before in your fact model. Your business process passes this object as an input to the rule.

   12. Add an End Event and connect all events on the canvas to complete the process.
   13. Click and select Generate all Forms.
   14. Save the process.

6. Build and deploy the rule.

   1. Click Open Project Editor on the left, change the version of the project and click Build → Build & Deploy.

      A notification appears in the upper part of the screen informing you that the project has been built successfully.

   2. Click Process Management → Process Definitions.
   3. Click Start next to the newly built process.

   4. In the opened MyProcess dialog window, provide the following values of the variables defined in your fact model and click Submit:

      • firstName: Tom
      • lastName: Summers
      • hourlyRate: 12
      • wage: 10

      As these values satisfy the rule condition, the expected output looks similar to the following:

      16:19:58,479 INFO  [org.jbpm.kie.services.impl.store.DeploymentSynchronizer] (http-/127.0.0.1:8080-1) Deployment unit org.bpms:MyProject:1.0 stored successfully
      16:26:56,119 INFO  [stdout] (http-/127.0.0.1:8080-5) Hello Tom Summers!
      16:26:56,119 INFO  [stdout] (http-/127.0.0.1:8080-5) You are rich!

1. Working Memory Actions. This is where most of the work takes place, either in the Consequence (the RHS itself) or the main Java application process. Once the Consequence has finished or the main Java application process calls fireAllRules() the engine switches to the Agenda Evaluation phase.
2. Agenda Evaluation. This attempts to select a rule to fire. If no rule is found it exits, otherwise it fires the found rule, switching the phase back to Working Memory Actions.

Procedure: Task

1. Generate a sample spreadsheet that you can use as the base.
2. If the Red Hat JBoss BRMS plug-in is being used, use the wizard to generate a spreadsheet from a template.
3. Use an XSL-compatible spreadsheet editor to modify the XSL.