Chapter 3. Project deployment without Business Central

Procedure

1. In the ~/resources/META-INF directory of your project, create a kmodule.xml metadata file with at least the following content:

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

   This empty kmodule.xml file is sufficient to produce a single default KIE base that includes all files found under your project resources path. The default KIE base also includes a single default KIE session that is triggered when you create a KIE container in your application at build time.

   The following example is a more advanced kmodule.xml file:

   <?xml version="1.0" encoding="UTF-8"?>
   <kmodule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.drools.org/xsd/kmodule">
     <configuration>
         <property key="drools.evaluator.supersetOf" value="org.mycompany.SupersetOfEvaluatorDefinition"/>
     </configuration>
     <kbase name="KBase1" default="true" eventProcessingMode="cloud" equalsBehavior="equality" declarativeAgenda="enabled" packages="org.domain.pkg1">
       <ksession name="KSession1_1" type="stateful" default="true" />
       <ksession name="KSession1_2" type="stateful" default="true" beliefSystem="jtms" />
     </kbase>
     <kbase name="KBase2" default="false" eventProcessingMode="stream" equalsBehavior="equality" declarativeAgenda="enabled" packages="org.domain.pkg2, org.domain.pkg3" includes="KBase1">
       <ksession name="KSession2_1" type="stateless" default="true" clockType="realtime">
         <fileLogger file="debugInfo" threaded="true" interval="10" />
         <workItemHandlers>
           <workItemHandler name="name" type="new org.domain.WorkItemHandler()" />
         </workItemHandlers>
         <listeners>
           <ruleRuntimeEventListener type="org.domain.RuleRuntimeListener" />
           <agendaEventListener type="org.domain.FirstAgendaListener" />
           <agendaEventListener type="org.domain.SecondAgendaListener" />
           <processEventListener type="org.domain.ProcessListener" />
         </listeners>
       </ksession>
     </kbase>
   </kmodule>

   This example defines two KIE bases. Specific packages of rule assets are included with both KIE bases. When you specify packages in this way, you must organize your rule files in a folder structure that reflects the specified packages. Two KIE sessions are instantiated from the KBase1 KIE base, and one KIE session from KBase2. The KIE session from KBase2 is a stateless KIE session, which means that data from a previous invocation of the KIE session (the previous session state) is discarded between session invocations. That KIE session also specifies a file (or a console) logger, a WorkItemHandler, and listeners of the three supported types shown: ruleRuntimeEventListener, agendaEventListener and processEventListener. The <configuration> element defines optional properties that you can use to further customize your kmodule.xml file.

   As an alternative to manually appending a kmodule.xml file to your project, you can use a KieModuleModel instance within your Java application to programmatically create a kmodule.xml file that defines the KIE base and a KIE session, and then add all resources in your project to the KIE virtual file system KieFileSystem.

   Creating kmodule.xml programmatically and adding it to KieFileSystem

   import org.kie.api.KieServices;
   import org.kie.api.builder.model.KieModuleModel;
   import org.kie.api.builder.model.KieBaseModel;
   import org.kie.api.builder.model.KieSessionModel;
   import org.kie.api.builder.KieFileSystem;
   
   KieServices kieServices = KieServices.Factory.get();
   KieModuleModel kieModuleModel = kieServices.newKieModuleModel();
   
   KieBaseModel kieBaseModel1 = kieModuleModel.newKieBaseModel("KBase1")
     .setDefault(true)
     .setEqualsBehavior(EqualityBehaviorOption.EQUALITY)
     .setEventProcessingMode(EventProcessingOption.STREAM);
   
   KieSessionModel ksessionModel1 = kieBaseModel1.newKieSessionModel("KSession1_1")
     .setDefault(true)
     .setType(KieSessionModel.KieSessionType.STATEFUL)
     .setClockType(ClockTypeOption.get("realtime"));
   
   KieFileSystem kfs = kieServices.newKieFileSystem();
   kfs.writeKModuleXML(kieModuleModel.toXML());

2. After you configure the kmodule.xml file either manually or programmatically in your project, retrieve the KIE bases and KIE sessions from the KIE container to verify the configurations:

   KieServices kieServices = KieServices.Factory.get();
   KieContainer kContainer = kieServices.getKieClasspathContainer();
   
   KieBase kBase1 = kContainer.getKieBase("KBase1");
   KieSession kieSession1 = kContainer.newKieSession("KSession1_1"),
       kieSession2 = kContainer.newKieSession("KSession1_2");
   
   KieBase kBase2 = kContainer.getKieBase("KBase2");
   StatelessKieSession kieSession3 = kContainer.newStatelessKieSession("KSession2_1");

   If KieBase or KieSession have been configured as default="true" in the kmodule.xml file, as in the previous kmodule.xml example, you can retrieve them from the KIE container without passing any names:

   KieContainer kContainer = ...
   
   KieBase kBase1 = kContainer.getKieBase();
   KieSession kieSession1 = kContainer.newKieSession(),
       kieSession2 = kContainer.newKieSession();
   
   KieBase kBase2 = kContainer.getKieBase();
   StatelessKieSession kieSession3 = kContainer.newStatelessKieSession();

   To increase or decrease the maximum number of KIE modules or artifact versions that are cached in the decision engine, you can modify the values of the following system properties in your Red Hat Process Automation Manager distribution:

   • kie.repository.project.cache.size: Maximum number of KIE modules that are cached in the decision engine. Default value: 100
   • kie.repository.project.versions.cache.size: Maximum number of versions of the same artifact that are cached in the decision engine. Default value: 10

   For the full list of KIE repository configurations, download the Red Hat Process Automation Manager 7.6.0 Source Distribution ZIP file from the Red Hat Customer Portal and navigate to ~/rhpam-7.6.0-sources/src/drools-$VERSION/drools-compiler/src/main/java/org/drools/compiler/kie/builder/impl/KieRepositoryImpl.java.

Procedure

1. In the pom.xml file of your Maven project, set the packaging type to kjar and add the kie-maven-plugin build component:

   <packaging>kjar</packaging>
   ...
   <build>
     <plugins>
       <plugin>
         <groupId>org.kie</groupId>
         <artifactId>kie-maven-plugin</artifactId>
         <version>${rhpam.version}</version>
         <extensions>true</extensions>
       </plugin>
     </plugins>
   </build>

   The kjar packaging type activates the kie-maven-plugin component to validate and pre-compile artifact resources. The <version> is the Maven artifact version for Red Hat Process Automation Manager currently used in your project (for example, 7.30.0.Final-redhat-00003). These settings are required to properly package the Maven project for deployment.

   Note

   Instead of specifying a Red Hat Process Automation 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.6.0.redhat-00004</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 Process Automation Manager and the Maven library version?.

2. Add the following dependencies to the pom.xml file to generate an executable rule model from your rule assets:

   • drools-canonical-model: Enables an executable canonical representation of a rule set model that is independent from Red Hat Process Automation Manager
   • drools-model-compiler: Compiles the executable model into Red Hat Process Automation Manager internal data structures so that it can be executed by the decision engine

   <dependency>
     <groupId>org.drools</groupId>
     <artifactId>drools-canonical-model</artifactId>
     <version>${rhpam.version}</version>
   </dependency>
   
   <dependency>
     <groupId>org.drools</groupId>
     <artifactId>drools-model-compiler</artifactId>
     <version>${rhpam.version}</version>
   </dependency>

   Executable rule models are embeddable models that provide a Java-based representation of a rule set for execution at build time. The executable model is a more efficient alternative to the standard asset packaging in Red Hat Process Automation Manager and enables KIE containers and KIE bases to be created more quickly, especially when you have large lists of DRL (Drools Rule Language) files and other Red Hat Process Automation Manager assets.

   For more information about executable rule models, see Designing a decision service using DRL rules.

   To enable Decision Model and Notation (DMN) executable models for DMN assets in your project (if applicable), also add the kie-dmn-core dependency in the pom.xml file:

   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-dmn-core</artifactId>
     <scope>provided</scope>
     <version>${rhpam.version}</version>
   </dependency>

3. In the ~/resources directory of your Maven project, create a META-INF/kmodule.xml metadata file with at least the following content:

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

   This kmodule.xml file is a KIE module descriptor that is required for all Red Hat Process Automation Manager projects. You can use the KIE module to define one or more KIE bases and one or more KIE sessions from each KIE base.

   For more information about kmodule.xml configuration, see Section 3.1, “Configuring a KIE module descriptor file”.

4. In the relevant resource in your Maven project, configure a .java class to create a KIE container and a KIE session to load the KIE base:

   import org.kie.api.KieServices;
   import org.kie.api.runtime.KieContainer;
   import org.kie.api.runtime.KieSession;
   
   public void testApp() {
   
     // Load the KIE base:
     KieServices ks = KieServices.Factory.get();
     KieContainer kContainer = ks.getKieClasspathContainer();
     KieSession kSession = kContainer.newKieSession();
   
   }

   In this example, the KIE container reads the files to be built from the class path for a testApp project. The KieServices API enables you to access all KIE building and runtime configurations.

   You can also create the KIE container by passing the project ReleaseId to the KieServices API. The ReleaseId is generated from the GroupId, ArtifactId, and Version (GAV) values in the project pom.xml file.

   import org.kie.api.KieServices;
   import org.kie.api.builder.ReleaseId;
   import org.kie.api.runtime.KieContainer;
   import org.kie.api.runtime.KieSession;
   import org.drools.compiler.kproject.ReleaseIdImpl;
   
   public void testApp() {
   
     // Identify the project in the local repository:
     ReleaseId rid = new ReleaseIdImpl("com.sample", "my-app", "1.0.0");
   
     // Load the KIE base:
     KieServices ks = KieServices.Factory.get();
     KieContainer kContainer = ks.newKieContainer(rid);
     KieSession kSession = kContainer.newKieSession();
   
   }

5. In a command terminal, navigate to your Maven project directory and run the following command to build the project from an executable model:

   mvn clean install -DgenerateModel=<VALUE>

   The -DgenerateModel=<VALUE> property enables the project to be built as a model-based KJAR instead of a DRL-based KJAR, so that rule assets are built in an executable rule model.

   Replace <VALUE> with one of three values:

   • YES: Generates the executable model corresponding to the DRL files in the original project and excludes the DRL files from the generated KJAR.
   • WITHDRL: Generates the executable model corresponding to the DRL files in the original project and also adds the DRL files to the generated KJAR for documentation purposes (the KIE base is built from the executable model regardless).
   • NO: Does not generate the executable model.

   Example build command:

   mvn clean install -DgenerateModel=YES

   For DMN executable models, run the following command:

   mvn clean install -DgenerateDMNModel=YES

   If the build fails, address any problems described in the command line error messages and try again to validate the files until the build is successful.

6. After you successfully build and test the project locally, deploy the project to the remote Maven repository:

   mvn deploy

Procedure

1. In your client application, add the following dependencies to the relevant classpath of your Java project to generate an executable rule model from your rule assets:

   • drools-canonical-model: Enables an executable canonical representation of a rule set model that is independent from Red Hat Process Automation Manager
   • drools-model-compiler: Compiles the executable model into Red Hat Process Automation Manager internal data structures so that it can be executed by the decision engine

   <dependency>
     <groupId>org.drools</groupId>
     <artifactId>drools-canonical-model</artifactId>
     <version>${rhpam.version}</version>
   </dependency>
   
   <dependency>
     <groupId>org.drools</groupId>
     <artifactId>drools-model-compiler</artifactId>
     <version>${rhpam.version}</version>
   </dependency>

   Executable rule models are embeddable models that provide a Java-based representation of a rule set for execution at build time. The executable model is a more efficient alternative to the standard asset packaging in Red Hat Process Automation Manager and enables KIE containers and KIE bases to be created more quickly, especially when you have large lists of DRL (Drools Rule Language) files and other Red Hat Process Automation Manager assets.

   For more information about executable rule models, see Designing a decision service using DRL rules.

   To enable Decision Model and Notation (DMN) executable models for DMN assets in your project (if applicable), also add the kie-dmn-core dependency in the pom.xml file:

   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-dmn-core</artifactId>
     <scope>provided</scope>
     <version>${rhpam.version}</version>
   </dependency>

   The <version> is the Maven artifact version for Red Hat Process Automation Manager currently used in your project (for example, 7.30.0.Final-redhat-00003).

   Note

   Instead of specifying a Red Hat Process Automation 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.6.0.redhat-00004</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 Process Automation Manager and the Maven library version?.

2. Use the KieServices API to create a KieModuleModel instance with the desired KIE base and KIE session. The KieServices API enables you to access all KIE building and runtime configurations. The KieModuleModel instance generates the kmodule.xml file for your project.

   For more information about kmodule.xml configuration, see Section 3.1, “Configuring a KIE module descriptor file”.

3. Convert your KieModuleModel instance into XML and add the XML to KieFileSystem.

   Creating kmodule.xml programmatically and adding it to KieFileSystem

   import org.kie.api.KieServices;
   import org.kie.api.builder.model.KieModuleModel;
   import org.kie.api.builder.model.KieBaseModel;
   import org.kie.api.builder.model.KieSessionModel;
   import org.kie.api.builder.KieFileSystem;
   
     KieServices kieServices = KieServices.Factory.get();
     KieModuleModel kieModuleModel = kieServices.newKieModuleModel();
   
     KieBaseModel kieBaseModel1 = kieModuleModel.newKieBaseModel("KBase1")
       .setDefault(true)
       .setEqualsBehavior(EqualityBehaviorOption.EQUALITY)
       .setEventProcessingMode(EventProcessingOption.STREAM);
   
     KieSessionModel ksessionModel1 = kieBaseModel1.newKieSessionModel("KSession1")
       .setDefault(true)
       .setType(KieSessionModel.KieSessionType.STATEFUL)
       .setClockType(ClockTypeOption.get("realtime"));
   
     KieFileSystem kfs = kieServices.newKieFileSystem();
     kfs.writeKModuleXML(kieModuleModel.toXML());

4. Add any remaining Red Hat Process Automation Manager assets that you use in your project to your KieFileSystem instance. The artifacts must be in a Maven project file structure.

   import org.kie.api.builder.KieFileSystem;
   
     KieFileSystem kfs = ...
     kfs.write("src/main/resources/KBase1/ruleSet1.drl", stringContainingAValidDRL)
       .write("src/main/resources/dtable.xls",
         kieServices.getResources().newInputStreamResource(dtableFileStream));

   In this example, the project assets are added both as a String variable and as a Resource instance. You can create the Resource instance using the KieResources factory, also provided by the KieServices instance. The KieResources class provides factory methods to convert InputStream, URL, and File objects, or a String representing a path of your file system to a Resource instance that the KieFileSystem can manage.

   You can also explicitly assign a ResourceType property to a Resource object when you add project artifacts to KieFileSystem:

   import org.kie.api.builder.KieFileSystem;
   
     KieFileSystem kfs = ...
     kfs.write("src/main/resources/myDrl.txt",
       kieServices.getResources().newInputStreamResource(drlStream)
         .setResourceType(ResourceType.DRL));

5. Use KieBuilder with buildAll( ExecutableModelProject.class ) specified to build the content of KieFileSystem from an executable model, and create a KIE container to deploy it:

   import org.kie.api.KieServices;
   import org.kie.api.KieServices.Factory;
   import org.kie.api.builder.KieFileSystem;
   import org.kie.api.builder.KieBuilder;
   import org.kie.api.runtime.KieContainer;
   
     KieServices kieServices = KieServices.Factory.get();
     KieFileSystem kfs = ...
   
     KieBuilder kieBuilder = ks.newKieBuilder( kfs );
     // Build from an executable model
     kieBuilder.buildAll( ExecutableModelProject.class )
     assertEquals(0, kieBuilder.getResults().getMessages(Message.Level.ERROR).size());
   
     KieContainer kieContainer = kieServices
       .newKieContainer(kieServices.getRepository().getDefaultReleaseId());

   After KieFileSystem is built from the executable model, the resulting KieSession uses constraints based on lambda expressions instead of less-efficient mvel expressions. To build the project in the standard method without an executable model, do not specify any argument in buildAll().

   A build ERROR indicates that the project compilation failed, no KieModule was produced, and nothing was added to the KieRepository singleton. A WARNING or an INFO result indicates that the compilation of the project was successful, with information about the build process.

Procedure

1. In the relevant .java class in your project, register and start the KIE scanner as shown in the following example code:

   Registering and starting a KIE scanner for a KIE container

   import org.kie.api.KieServices;
   import org.kie.api.builder.ReleaseId;
   import org.kie.api.runtime.KieContainer;
   import org.kie.api.builder.KieScanner;
   
   ...
   
   KieServices kieServices = KieServices.Factory.get();
   ReleaseId releaseId = kieServices
     .newReleaseId("com.sample", "my-app", "1.0-SNAPSHOT");
   KieContainer kContainer = kieServices.newKieContainer(releaseId);
   KieScanner kScanner = kieServices.newKieScanner(kContainer);
   
   // Start KIE scanner for polling the Maven repository every 10 seconds (10000 ms)
   kScanner.start(10000L);

   In this example, the KIE scanner is configured to run with a fixed time interval. The minimum KIE scanner polling interval is 1 millisecond (ms) and the maximum polling interval is the maximum value of the data type long. A polling interval of 0 or less results in a java.lang.IllegalArgumentException: pollingInterval must be positive error. You can also configure the KIE scanner to run on demand by invoking the scanNow() method.

   The project group ID, artifact ID, and version (GAV) settings in the example are defined as com.sample:my-app:1.0-SNAPSHOT. The project version must contain the -SNAPSHOT suffix to enable the KIE scanner to retrieve the latest build of the specified artifact version. If you change the snapshot project version number, such as increasing to 1.0.1-SNAPSHOT, then you must also update the version in the GAV definition in your KIE scanner configuration. The KIE scanner does not retrieve updates for projects with static versions, such as com.sample:my-app:1.0.

2. In the settings.xml file of your Maven repository, set the updatePolicy configuration to always to enable the KIE scanner to function properly:

   <profile>
     <id>guvnor-m2-repo</id>
     <repositories>
       <repository>
         <id>guvnor-m2-repo</id>
         <name>BA Repository</name>
         <url>http://localhost:8080/business-central/maven2/</url>
         <layout>default</layout>
         <releases>
           <enabled>true</enabled>
           <updatePolicy>always</updatePolicy>
         </releases>
         <snapshots>
           <enabled>true</enabled>
           <updatePolicy>always</updatePolicy>
         </snapshots>
       </repository>
     </repositories>
   </profile>

   After the KIE scanner starts polling, if the KIE scanner detects an updated version of the SNAPSHOT project in the specified KIE container, the KIE scanner automatically downloads the new project version and triggers an incremental build of the new project. From that moment, all of the new KieBase and KieSession objects that were created from the KIE container use the new project version.

   For information about starting or stopping a KIE scanner using Process Server APIs, see Interacting with Red Hat Process Automation Manager using KIE APIs.