Designing a decision service using guided rule templates

Procedure

1. In Decision Central, go to Menu → Design → Projects and click the project name.
2. Click Add Asset → Guided Rule Template.
3. Enter an informative Guided Rule Template name and select the appropriate Package. The package that you specify must be the same package where the required data objects have been assigned or will be assigned.

4. Click Ok to create the rule template.

   The new guided rule template is now listed in the Guided Rule Templates panel of the Project Explorer.

5. Click the Data Objects tab and confirm that all data objects required for your rules are listed. If not, click New item to import data objects from other packages, or create data objects within your package.

6. After all data objects are in place, return to the Model tab and use the buttons on the right side of the window to add and define the WHEN (condition) and THEN (action) sections of the rule template, based on the available data objects. For the field values that vary per rule, use template keys in the format $key in the rule designer or in the format @{key} in free form DRL (if used).

   Figure 4.1. Sample guided rule template

   
   Note on template keys

   Template keys are fundamental in guided rule templates. Template keys are what enable field values in the templates to be interchanged with actual values that you define in the corresponding data table to generate different rules from the same template. You can use other value types, such as Literal or Formula, for values that are part of the rule structure of all rules based on that template. However, for any values that differ among the rules, use the Template key field type with a specified key. Without template keys in a guided rule template, the corresponding data table is not generated in the template designer and the template essentially functions as an individual guided rule.

   The WHEN part of the rule template is the condition that must be met to execute an action. For example, if a telecommunications company charges customers based on the services they subscribe to (Internet, phone, and TV), then one of the WHEN conditions would be internetService | equal to | $hasInternetService. The template key $hasInternetService is interchanged with an actual Boolean value (true or false) defined in the data table for the template.

   The THEN part of the rule template is the action to be performed when the conditional part of the rule has been met. For example, if a customer subscribes to only Internet service, a THEN action for RecurringPayment with a template key $amount would set the actual monthly amount to the integer value defined for Internet service charges in the data table.

7. After you define all components of the rule, click Save in the guided rule templates designer to save your work.

Procedure

1. In the guided rule templates designer, click the Data tab to view the data table. Each column in the data table corresponds to a template key that you added in the guided rule template.

   Note

   If you did not add any template keys to the rule template, then this data table does not appear and the template does not function as a genuine template but essentially as an individual guided rule. For this reason, template keys are fundamental in creating guided rule templates.

2. Click Add row and define the data values for each template key column to generate that rule (row).

3. Continue adding rows and defining data values for each rule that will be generated. You can click Add row for each new row, or click the plus icon ( ) or minus icon to add or remove rows.

   Figure 5.1. Sample data table for a guided rule template

   

   To view the DRL code, click the Source tab in the guided rule templates designer.

   Example:

   rule "PaymentRules_6"
   	dialect "mvel"
   	when
   		Customer( internetService == false ,
   			phoneService == false ,
   			TVService == true )
   	then
   		RecurringPayment fact0 = new RecurringPayment();
   		fact0.setAmount( 5 );
   		insertLogical( fact0 );
   end
   
   rule "PaymentRules_5"
   	dialect "mvel"
   	when
   		Customer( internetService == false ,
   			phoneService == true ,
   			TVService == false )
   	then
   		RecurringPayment fact0 = new RecurringPayment();
   		fact0.setAmount( 5 );
   		insertLogical( fact0 );
   end
   ...
   //Other rules omitted for brevity.

4. As a visual aid, click the grid icon in the upper-left corner of the data table to toggle cell merging on and off, if needed. Cells in the same column with identical values are merged into a single cell.

   Figure 5.2. Merge cells in a data table

   

   You can then use the expand/collapse icon [+/-] in the upper-left corner of each newly merged cell to collapse the rows corresponding to the merged cell, or to re-expand the collapsed rows.

   Figure 5.3. Collapse merged cells

   
5. After you define the template key data for all rules and adjust the table display as needed, click Validate in the upper-right toolbar of the guided rule templates designer to validate the guided rule template. If the rule template validation fails, address any problems described in the error message, review all components in the rule template and data defined in the data table, and try again to validate the rule template until the rule template passes.
6. Click Save in the guided rule templates designer to save your work.

Procedure

1. In Decision Central, go to Menu → Design → Projects and click the project name.

2. In the upper-right corner of the project Assets page, click Deploy to build the project and deploy it to Decision Server. If the build fails, address any problems described in the Alerts panel at the bottom of the screen.

   For more information about deploying projects, see Packaging and deploying a Red Hat Decision Manager project.

3. Create a Maven or Java project outside of Decision Central, if not created already, that you can use for executing rules locally or that you can use as a client application for executing rules on Decision Server. The project must contain a pom.xml file and any other required components for executing the project resources.

   For example test projects, see "Other methods for creating and executing DRL rules".

4. Open the pom.xml file of your test project or client application and add the following dependencies, if not added already:

   • kie-ci: Enables your client application to load Decision Central project data locally using ReleaseId
   • kie-server-client: Enables your client application to interact remotely with assets on Decision Server
   • slf4j: (Optional) Enables your client application to use Simple Logging Facade for Java (SLF4J) to return debug logging information after you interact with Decision Server

   Example dependencies for Red Hat Decision Manager 7.2 in a client application pom.xml file:

   <!-- For local execution -->
   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-ci</artifactId>
     <version>7.14.0.Final-redhat-00002</version>
   </dependency>
   
   <!-- For remote execution on Decision Server -->
   <dependency>
     <groupId>org.kie.server</groupId>
     <artifactId>kie-server-client</artifactId>
     <version>7.14.0.Final-redhat-00002</version>
   </dependency>
   
   <!-- For debug logging (optional) -->
   <dependency>
     <groupId>org.slf4j</groupId>
     <artifactId>slf4j-simple</artifactId>
     <version>1.7.25</version>
   </dependency>

   For available versions of these artifacts, search the group ID and artifact ID in the Nexus Repository Manager online.

   Note

   Instead of specifying a Red Hat Decision Manager <version> for individual dependencies, consider adding the Red Hat Business Automation bill of materials (BOM) dependency to your project pom.xml file. The Red Hat Business Automation BOM applies to both Red Hat Decision Manager and Red Hat Process Automation Manager. When you add the BOM files, the correct versions of transitive dependencies from the provided Maven repositories are included in the project.

   Example BOM dependency:

   <dependency>
     <groupId>com.redhat.ba</groupId>
     <artifactId>ba-platform-bom</artifactId>
     <version>7.2.0.GA-redhat-00002</version>
     <scope>import</scope>
     <type>pom</type>
   </dependency>

   For more information about the Red Hat Business Automation BOM, see What is the mapping between Red Hat Decision Manager and the Maven library version?.

5. Ensure that the dependencies for artifacts containing model classes are defined in the client application pom.xml file exactly as they appear in the pom.xml file of the deployed project. If dependencies for model classes differ between the client application and your projects, execution errors can occur.

   To access the project pom.xml file in Decision Central, select any existing asset in the project and then in the Project Explorer menu on the left side of the screen, click the Customize View gear icon and select Repository View → pom.xml.

   For example, the following Person class dependency appears in both the client and deployed project pom.xml files:

   <dependency>
     <groupId>com.sample</groupId>
     <artifactId>Person</artifactId>
     <version>1.0.0</version>
   </dependency>

6. If you added the slf4j dependency to the client application pom.xml file for debug logging, create a simplelogger.properties file on the relevant classpath (for example, in src/main/resources/META-INF in Maven) with the following content:

   org.slf4j.simpleLogger.defaultLogLevel=debug

7. In your client application, create a .java main class containing the necessary imports and a main() method to load the KIE base, insert facts, and execute the rules.

   For example, a Person object in a project contains getter and setter methods to set and retrieve the first name, last name, hourly rate, and the wage of a person. The following Wage rule in a project calculates the wage and hourly rate values and displays a message based on the result:

   package com.sample;
   
   import com.sample.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

   To test this rule locally outside of Decision Server (if desired), configure the .java class to import KIE services, a KIE container, and a KIE session, and then use the main() method to fire all rules against a defined fact model:

   Executing rules locally

   import org.kie.api.KieServices;
   import org.kie.api.runtime.KieContainer;
   import org.kie.api.runtime.KieSession;
   
   public class RulesTest {
   
     public static final void main(String[] args) {
       try {
         // Identify the project in the local repository:
         ReleaseId rid = new ReleaseId();
         rid.setGroupId("com.myspace");
         rid.setArtifactId("MyProject");
         rid.setVersion("1.0.0");
   
         // Load the KIE base:
         KieServices ks = KieServices.Factory.get();
         KieContainer kContainer = ks.newKieContainer(rid);
         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();
         kSession.dispose();
       }
   
       catch (Throwable t) {
         t.printStackTrace();
       }
     }
   }

   To test this rule on Decision Server, configure the .java class with the imports and rule execution information similarly to the local example, and additionally specify KIE services configuration and KIE services client details:

   Executing rules on Decision Server

   package com.sample;
   
   import java.util.ArrayList;
   import java.util.HashSet;
   import java.util.List;
   import java.util.Set;
   
   import org.kie.api.command.BatchExecutionCommand;
   import org.kie.api.command.Command;
   import org.kie.api.KieServices;
   import org.kie.api.runtime.ExecutionResults;
   import org.kie.api.runtime.KieContainer;
   import org.kie.api.runtime.KieSession;
   import org.kie.server.api.marshalling.MarshallingFormat;
   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;
   import org.kie.server.client.RuleServicesClient;
   
   import com.sample.Person;
   
   public class RulesTest {
   
     private static final String containerName = "testProject";
     private static final String sessionName = "myStatelessSession";
   
     public static final void main(String[] args) {
       try {
         // Define KIE services configuration and client:
         Set<Class<?>> allClasses = new HashSet<Class<?>>();
         allClasses.add(Person.class);
         String serverUrl = "http://$HOST:$PORT/kie-server/services/rest/server";
         String username = "$USERNAME";
         String password = "$PASSWORD";
         KieServicesConfiguration config =
           KieServicesFactory.newRestConfiguration(serverUrl,
                                                   username,
                                                   password);
         config.setMarshallingFormat(MarshallingFormat.JAXB);
         config.addExtraClasses(allClasses);
         KieServicesClient kieServicesClient =
           KieServicesFactory.newKieServicesClient(config);
   
         // Set up the fact model:
         Person p = new Person();
         p.setWage(12);
         p.setFirstName("Tom");
         p.setLastName("Summers");
         p.setHourlyRate(10);
   
         // Insert Person into the session:
         KieCommands kieCommands = KieServices.Factory.get().getCommands();
         List<Command> commandList = new ArrayList<Command>();
         commandList.add(kieCommands.newInsert(p, "personReturnId"));
   
         // Fire all rules:
         commandList.add(kieCommands.newFireAllRules("numberOfFiredRules"));
         BatchExecutionCommand batch = kieCommands.newBatchExecution(commandList, sessionName);
   
         // Use rule services client to send request:
         RuleServicesClient ruleClient = kieServicesClient.getServicesClient(RuleServicesClient.class);
         ServiceResponse<ExecutionResults> executeResponse = ruleClient.executeCommandsWithResults(containerName, batch);
         System.out.println("number of fired rules:" + executeResponse.getResult().getValue("numberOfFiredRules"));
       }
   
       catch (Throwable t) {
         t.printStackTrace();
       }
     }
   }

8. Run the configured .java class from your project directory. You can run the file in your development platform (such as Red Hat JBoss Developer Studio) or in the command line.

   Example Maven execution (within project directory):

   mvn clean install exec:java -Dexec.mainClass="com.sample.app.RulesTest"

   Example Java execution (within project directory)

   javac -classpath "./$DEPENDENCIES/*:." RulesTest.java
   java -classpath "./$DEPENDENCIES/*:." RulesTest

9. Review the rule execution status in the command line and in the server log. If any rules do not execute as expected, review the configured rules in the project and the main class configuration to validate the data provided.