Red Hat JBoss BRMS 6.4

Getting Started Guide

The Getting Started Guide for Red Hat JBoss BRMS.

Red Hat Content Services

Gemma Sheldon

<gsheldon@redhat.com>

Klara Kufova

<kkufova@redhat.com>

Marek Czernek

<mczernek@redhat.com>

Tomas Radej

<tradej@redhat.com>

Vidya Iyengar

<viyengar@redhat.com>

Copyright © 2016 Red Hat, Inc.

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Abstract

This guide provides information for getting started with Red Hat JBoss BRMS.

Chapter 1. Quick Start with Red Hat JBoss BRMS

In this section we download, install and run Red Hat JBoss BRMS with the minimum number of instructions. For more detailed steps and alternate methods of installation, skip this section and continue reading the rest of this guide.

These instructions assume that you have the minimum supported Java version installed on your system. An existing Red Hat JBoss EAP server (version 6.4 or better) is also required as the installer does not install one.

Note

It may be necessary for you to update your Red Hat JBoss EAP server. If the installer informs you of such need, download the newest patch from the Customer Portal and follow the instructions for updating in the Red Hat JBoss EAP Installation Guide.

Procedure: Red Hat JBoss BRMS Quick Start

Download installer from the Customer Portal.

Run installer by executing the following command:

java -jar jboss-brms-VERSION-installer.jar

Step through the GUI installer steps making note of the username/password for accessing the Red Hat JBoss BRMS application after installation.

After successful installation, in a command prompt, navigate to the EAP home folder where you have installed Red Hat JBoss BRMS.

Start the server by issuing the following command:

bin/standalone.sh

Open a web browser and login to Business Central by navigating to http://localhost:8080/business-central/. Login using the username/password combination for accessing the Red Hat JBoss BRMS application that you created at installation time.

You have successfully installed and run Red Hat JBoss BRMS. You can now do the following:

Learn more about roles in the section called “Defining Roles”.

Create additional users (see the section called “Creating Users”).

Create a Hello World Rule (see Chapter 4, Hello World Rule Example).

Look up detailed installation instructions for using the installer in the Red Hat JBoss BRMS Installation Guide.

Chapter 2. Installation

Downloading Red Hat JBoss BRMS for Red Hat JBoss EAP

Go to the Red Hat Customer Portal and log in.

Click DOWNLOADS at the top of the page.

In the Product Downloads page that opens, click Red Hat JBoss BRMS.

From the Version drop-down menu, select version 6.4.

Select Red Hat JBoss BRMS 6.4.0 Deployable for EAP 6 and then click Download.

Installing Red Hat JBoss BRMS for Red Hat JBoss Enterprise Application Platform

Red Hat JBoss BRMS can be installed on Red Hat JBoss Enterprise Application Platform 6.4.

Installation on Fresh EAP Instance

To install the deployable package for a Red Hat JBoss Enterprise Application Platform that has yet to be configured, do the following:

Move the downloaded ZIP archive to the parent directory of the Red Hat JBoss Enterprise Application Platform home directory (EAP_HOME; the jboss-eap-6.4 directory).

Unzip the downloaded ZIP archive: make sure it is merged into the EAP_HOME directory (jboss-eap-6.4).

Warning

This step must be performed by the same user account that was used to install EAP. This account must not be a superuser account.

It is necessary to overwrite the files that already exist in the EAP_HOME directory with their versions from the downloaded ZIP archive. When prompted to do so, accept overwriting the original files.

Installation on Existing EAP Configuration

Warning

These instructions are for installing, and not for updating an existing Red Hat JBoss BRMS instance. Make sure that there is no existing Red Hat JBoss BRMS install in the target EAP.

To install the deployable package for a previously configured Red Hat JBoss Enterprise Application Platform, do the following:

Download the ZIP archive and prepare to manually merge files into the Red Hat JBoss Enterprise Application Platform home directory (EAP_HOME; the jboss-eap-6.4 directory).

Unzip the downloaded ZIP archive; however, do not overwrite all of the files. Manually merge the following files into the EAP_HOME directory (jboss-eap-6.4):

jboss-eap-6.4/domain/configuration/*

jboss-eap-6.4/standalone/configuration/*

jboss-eap-6.4/bin/product.conf

Warning

Make sure this step is performed by the same user account that was used to install EAP. This account must not be a superuser account.

Copy the folder jboss-eap-6.4/standalone/deployments into the EAP_HOME directory from the Red Hat JBoss BRMS distribution.

Note

If you already have deployments on your Red Hat JBoss EAP, ensure that your current deployments do not have colliding names with Red Hat JBoss BRMS deployments.

Installing Red Hat JBoss BRMS on Red Hat JBoss Web Server

The generic deployable package is provided for customers to install Red Hat JBoss BRMS 6.4 to an existing application server. The following procedure provides instructions for installation on an existing Red Hat JBoss Web Server instance.

Note

In case you have already installed Red Hat JBoss BRMS on Red Hat JBoss Enterprise Application Platform, skip to the section called “Defining Roles”.

Procedure: Installing Generic Deployable Package

To download the generic deployable package ZIP file from the Red Hat Customer Support Portal, go to https://access.redhat.com and log in.

Click DOWNLOADS at the top of the page.

In the Product Downloads page that opens, click Red Hat JBoss BRMS.

From the Version drop-down menu, select 6.4.

Select Red Hat JBoss BRMS 6.4.0 Deployable for All Supported Containers package and click Download.

Also select and download the Red Hat JBoss BRMS 6.4.0 Core Engine files.

Extract business-central.war and kie-server.war from the generic deployable archive and copy to tomcat7/webapps/ folder.

Remove the .war extensions from the business-central.war and kie-server.war folders.

Move the kie-tomcat-integration-VERSION.jar file from business-central/WEB-INF/lib in Red Hat JBoss BRMS distribution to tomcat7/lib.

Define the users and the roles in tomcat7/conf/tomcat-users.xml as shown below.

Important

Make sure that the selected user name does not conflict with any known title of a role or a group. See the section called “Defining Roles” for a list of defined roles.

For example, if there is a role called admin, you should not create a user with the user name admin.

<role rolename="admin"/>
<role rolename="analyst"/>
<user username="user" password="password" roles="admin,analyst"/>

Install the transaction manager.

Warning

Please note that the following section describes the setup of a transaction manager Bitronix that is not officially supported by Red Hat.

Copy the following transaction manager JAR libraries from the lib folder to $TOMCAT_DIR/lib/ directory:

btm-VERSION.jar

btm-tomcat55-lifecycle-VERSION.jar

jta-VERSION.jar

slf4j-api-VERSION.jar

slf4j-jdk14-VERSION.jar

In addition, download the following library and copy it into the $TOMCAT_DIR/lib/ folder as well: javax.security.jacc-api.jar.

Create the transaction manager configuration files in $TOMCAT_DIR/conf/:

btm-config.properties

bitronix.tm.serverId=tomcat-btm-node0
bitronix.tm.journal.disk.logPart1Filename=${btm.root}/work/btm1.tlog
bitronix.tm.journal.disk.logPart2Filename=${btm.root}/work/btm2.tlog
bitronix.tm.resource.configuration=${btm.root}/conf/resources.properties

resources.properties (the resource.ds1.uniqueName defines the data source name used in Tomcat resource definition later — make a note of this value).

Example 2.1. H2 Data Source Definition

resource.ds1.className=bitronix.tm.resource.jdbc.lrc.LrcXADataSource
resource.ds1.uniqueName=jdbc/jbpm
resource.ds1.minPoolSize=10
resource.ds1.maxPoolSize=20
resource.ds1.driverProperties.driverClassName=org.h2.Driver
resource.ds1.driverProperties.url=jdbc:h2:file:~/jbpm
resource.ds1.driverProperties.user=sa
resource.ds1.driverProperties.password=
resource.ds1.allowLocalTransactions=true

Example 2.2. MySQL 5.5 Data Source Definition

resource.ds1.className=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
resource.ds1.uniqueName=jdbc/jbpm
resource.ds1.minPoolSize=0
resource.ds1.maxPoolSize=10
resource.ds1.driverProperties.URL=jdbc:mysql://localhost:3306/sampledb
resource.ds1.driverProperties.user=dbuser
resource.ds1.driverProperties.password=dbpassword
resource.ds1.allowLocalTransactions=true

Example 2.3. DB2 Type 4 Data Source Definition

resource.ds1.className=com.ibm.db2.jcc.DB2Driver
resource.ds1.uniqueName=jdbc/jbpm
resource.ds1.minPoolSize=0
resource.ds1.maxPoolSize=10
resource.ds1.driverProperties.URL=jdbc:db2://localhost:50000/sampledb
resource.ds1.driverProperties.user=dbuser
resource.ds1.driverProperties.password=dbpassword
resource.ds1.allowLocalTransactions=true

Example 2.4. Oracle Data Source Definition

resource.ds1.className=oracle.jdbc.xa.client.OracleXADataSource
resource.ds1.uniqueName=jdbc/jbpm
resource.ds1.minPoolSize=0
resource.ds1.maxPoolSize=10
resource.ds1.driverProperties.URL=jdbc:oracle:thin:@//localhost:1521/bpms
resource.ds1.driverProperties.user=dbuser
resource.ds1.driverProperties.password=dbpassword
resource.ds1.allowLocalTransactions=true

Example 2.5. Microsoft SQL Server Data Source Definition

resource.ds1.className=com.microsoft.sqlserver.jdbc.SQLServerDriver
resource.ds1.uniqueName=jdbc/jbpm
resource.ds1.minPoolSize=0
resource.ds1.maxPoolSize=10
resource.ds1.driverProperties.URL=jdbc:sqlserver://localhost:1433;databaseName=bpms;
resource.ds1.driverProperties.user=dbuser
resource.ds1.driverProperties.password=dbpassword
resource.ds1.allowLocalTransactions=true

Install the driver to your database.

Copy the JAR file with the relevant database driver to $TOMCAT_DIR/lib/.

Driver to the Embedded H2 Database

If using the embedded H2 database, the driver is available in business-central/WEB-INF/lib/.

Start JBoss Web Server by running startup.sh in the tomcat7/bin directory.

./startup.sh

Wait a few minutes and check the server log ($TOMCAT_DIR/tomcat7/logs) for any errors. If there are no errors, proceed to the next step.

Navigate to http://localhost:8080/business-central in a web browser.

Login with the user name and password defined in the tomcat-users.xml file.

Defining Roles

Before starting the server and logging onto Business Central, you will need to create some user accounts. This section describes the different user roles that are used in Red Hat JBoss BRMS:

admin: The users with admin role are the administrators of the application. Administrators can manage users, manage the repositories (create and clone) and have full access to make the required changes in the application. Admins have access to all areas within the system.

analyst: An analyst role has access to all high-level features to model projects. However, Authoring → Administration access is unavailable to users with the analyst role. Certain lower-level features targeted towards developers, like the Deployment → Artifact Repository view are not accessible for this role. However, the Build & Deploy button is available for the analyst role while using the Project Editor.

Other roles you can encounter:

REST API access control roles. For further information, see section Control of REST API of the Red Hat JBoss BPM Suite Development Guide.

The Realtime Decision Server kie-server role. For further information, see chapter Intelligent Process Server and Realtime Decision Server of the Red Hat JBoss BPM Suite Development Guide.

The kiemgmt role for the managed repository feature. See section Managing Assets of the Red Hat JBoss BRMS Administration and Configuration Guide.

Note

Enter the above mentioned roles during the user creation process.

Creating Users

To start adding new users, you will need to run the add-user.sh script on a Unix system or the add-user.bat file on a Windows system from the EAP bin directory.

Procedure: Creating New Users

Go to the EAP bin directory.

On a Unix system, run the following command:

./add-user.sh

On a Windows system, run:

./add-user.bat

Enter b to select the application user and press Enter.

Accept the default realm (ApplicationRealm) by pressing Enter.

At the user name prompt, enter the user name and confirm. For example helloworlduser.

Important

Make sure that the selected user name does not conflict with any known title of a role or a group.

For example, if there is a role called admin, you should not create a user with the user name admin.

Create the user password at the password prompt and reenter the password. For example Helloworld@123.

Note

The password should be at least 8 characters in length and should contain upper and lower case alphabetic characters (A-Z, a-z), at least one numerical character (0-9) and at least one special character (for example ~ ! @ # $ % ^ * ( ) - _ + =).

Enter a comma-separated list of roles the user will need at the roles prompt (see the section called “Defining Roles”).

Note that Business Central users need to have the analyst or the admin role assigned.

Confirm that you want to add the user.

Enter yes at the next prompt to enable clustering in the future.

Starting Server

If you have installed Red Hat JBoss BRMS using the Red Hat JBoss EAP 6 bundle install, you can now start your server in one of two modes.

Note

If you installed Red Hat JBoss BRMS using the generic deployable version on Red Hat Java Web Server, the instructions for download and install also contain the instructions for starting the server. You can ignore the following discussion.

The default startup script, standalone.sh that Red Hat JBoss BRMS ships with is optimized for performance. To run your server in the performance mode, do the following:

On the command line, move into the $SERVER_HOME/bin/ directory.

In a Unix environment run:

./standalone.sh

In a Windows environment run:

./standalone.bat

Red Hat JBoss BRMS also ships with a separate script, standalone-secure.sh that is optimized for security. This script applies a security policy by default that protects against a known security vulnerability.

Note

It is recommended that production environments use standalone-secure.sh script.

Warning

The use of a security manager imposes a significant performance penalty that you should be aware of. The tradeoff between security and performance must be made by taking into consideration individual circumstances. See the section called “Java Security Manager and Performance Management”.

To run your server in the secure mode with this script, do the following:

On the command line, move into the $SERVER_HOME/bin/ directory.

In a Unix environment run:

./standalone-secure.sh

In a Windows environment run:

./standalone-secure.bat

Note

If you installed Red Hat JBoss BRMS using the installer, an option to apply the security policy is given to you at the time of install. The installer does not provide a separate standalone-secure.sh script.

Note

If you are starting the server in the domain mode, the corresponding scripts are domain.sh and domain-secure.sh respectively.

Java Security Manager and Performance Management

As noted earlier, enabling the Java Security Manager (JSM) to sandbox the evaluation of MVEL scripts in Red Hat JBoss BRMS introduces a performance hit in high load environments. Environments and performance markers must be kept in mind when deploying a Red Hat JBoss BRMS application. Use the following guidelines to deploy secure and high performance Red Hat JBoss BRMS applications.

In high load environments where performance is critical it is recommended to only deploy applications that have been developed on other systems and properly reviewed. It is also recommended not to create any users with analyst role on such systems. If these safeguards are followed, it is safe to leave JSM disabled on these systems so it does not introduce any performance degradation.

In testing and development environments without high loads, or in environments where rule and process authoring is exposed to external networks, it is recommended to have JSM enabled in order to achieve security benefits of properly sandboxed evaluation of MVEL.

Allowing users with analyst role to log in to the Business Central console with JSM disabled is not secure and not recommended.

Chapter 3. Logging on to Business Central

Log into Business Central after the server has successfully started.

Navigate to http://localhost:8080/business-central in a web browser. If the user interface has been configured to run from a domain name, substitute localhost for the domain name. For example http://www.example.com:8080/business-central.

Log in with the user credentials that were created during installation. For example, user: helloworlduser and password: Helloworld@123.

Chapter 4. Hello World Rule Example

This example demonstrates basic features of Red Hat JBoss BRMS by setting up a Hello World project with a simple business rule.

In this project, you will:

Create a repository in the artifact repository.

Create a project.

Create a rule.

Create a knowledgebase.

Build and deploy the project.

Create a Maven project to fire the rule.

Create Your First Rule Using Business Central

Prerequisite

Ensure that you have successfully installed Red Hat JBoss BRMS and Maven before you run this simple rule example using Business Central interface.

Procedure: Create and Execute Your First Rule Using Business Central

On the command line, change into $SERVER_HOME/bin/ directory and execute the following command:

for Unix environment:

./standalone.sh

for Windows environment:

./standalone.bat

Once your server is up and running, open the following address in a web browser:

http://localhost:8080/business-central

This opens the Business Central login page.

Log into the Business Central with the user credentials created during installation.

On the main menu of Business Central, go to Authoring → Administration and then Organizational Unit → Manage Organizational Units. Click Add.

In the displayed Add New Organizational Unit dialog box, define the unit properties. For example:

Name: EmployeeWage

Owner: Employee

Click OK.

On the perspective menu, click Repositories → New repository.

In the displayed New Repository dialog box, define the repository properties. For example:

Repository Name: EmployeeRepo

In the In Organizational Unit drop-down menu, select EmployeeWage.

Click Finish.

Go to Authoring → Project Authoring.

In the Project Explorer, under the organizational unit drop-down box, select EmployeeWage, and in the repository drop-down box select EmployeeRepo.

On the perspective menu, go to New Item → Project.

In the displayed New Project wizard, provide a name (for example MyProject) for your project. In the Group Artifact Version part of the wizard, define the Maven properties of the project. For example:

Group ID: org.brms

Artifact ID: MyProject

Version ID: 1.0.0

Click Finish.

On the perspective menu, go to New Item → Data Object.

In the displayed Create new Data Object dialog box, provide the values for object name and package. For example:

Data Object: Person

Package: org.brms.myproject

Click Ok.

In the displayed Person window of the newly created Person data object, click add field to open the New field dialogue. Add a variable name in the Id field, select data type for the variable in the Type field, and click Create and continue until you have defined all the necessary variables. For example:

Id: firstName

Type: String

Id: lastName

Type: String

Id: hourlyRate

Type: Integer

Id: wage

Type: Integer

Click Create for the last variable and then Save.

On the perspective menu, click New Item → DRL File.

In the Create new dialog box, provide the name and package name of your rule file. For example:

DRL file name: MyRule

Package: org.brms.myproject

Click Ok.

In the displayed DRL editor with MyRule.drl, write your rule as shown below:

package org.brms.myproject;
rule "MyRule"
when

  Person(hourlyRate*wage > 100)
  Person(name : firstName, surname : lastName)

then
  System.out.println( "Hello" + " " + name + " " + surname + "!" );
  System.out.println( "You are rich!" );

end

Click Save.

Rules are simple when-then statements stored in DRL files. This example has two conditions:

Person(hourlyRate*wage > 100)

Person(name : firstName, surname : lastName)

The first line evaluates a logical condition. The second line searches for an instance of the data object Person and saves its attributes, that is, the firstName and lastName into variables used in the second part of the rule.

If the conditions are met, the then part of the rule executes. In this example, two lines will be printed out in the Red Hat JBoss BRMS command line.

Following steps demonstrate how to create your own knowledge base. For more information about KieSession, see the KIE Sessions chapter from the Red Hat JBoss BPM Suite Development Guide.

Click Open Project Editor.

Go to Project Settings: Project General Settings → Knowledge Base Settings: Knowledge bases and sessions.

Click Add and enter the name of your knowledge base.

Enter myBase for this example.

Click Make Default

Click Add under Packages.

In this step, you are specifying which packages should your knowledge base include. Enter * (an asterisk) to include all packages.

Click Add under Knowledge Sessions.

Enter the name of your session. For example mySession. Check Default and select the stateless state.

Click Save in the top right corner.

Click Open Project Editor and then Build & Deploy.

A green notification appears in the upper part of the screen informing you that the project has been built and deployed successfully to the Execution Server.

Note

In case a red notification appears, informing you that the build has failed, you will be presented with information about the build failure in the Red Hat JBoss BRMS console. This is crucial information in case of troubleshooting your application. Make sure you have saved all assets before attempting to build your project.

Setting Up Realtime Decision Server

To fire all the rules through the REST API, you must register a Realtime Decision Server instance. This section illustrates:

How to register the Realtime Decision Server.

How to add a new container to the Realtime Decision Server.

Procedure: Registering Realtime Decision Server

You need to register a new user with the role kieserver:

On the command line, change into $SERVER_HOME/bin/ and execute the following command:

~]$ ./add-user.sh -a --user kieserver --password kieserver1! --role kie-server,rest-all

On the command line, change into $SERVER_HOME/standalone/configuration. In standalone.xml, add the following properties into the system-properties tag:

<property name="org.kie.server.user"
          value="kieserver"></property>
<property name="org.kie.server.pwd"
          value="kieserver1!"></property>
<property name="org.kie.server.location"
          value="http://localhost:8080/kie-server/services/rest/server"></property>
<property name="org.kie.server.controller"
          value="http://localhost:8080/business-central/rest/controller"></property>
<property name="org.kie.server.controller.user"
          value="kieserver"></property>
<property name="org.kie.server.controller.pwd"
          value="kieserver1!"></property>
<property name="org.kie.server.id"
          value="local-server-123"></property>

On the command line, change into $SERVER_HOME/bin/ and execute the following command:

~]$ ./standalone.sh

In the Business Central, click Deploy → Execution Servers.

In the displayed window, you will see local-server-123. Click Add Container under KIE CONTAINERS.

The New Container dialog opens. Enter the following:

Name: myContainer

Click Search and click Select next to MyProject-1.0.0.jar.

Click Finish to create the container.

Select myContainer and click Start to start the container.

Firing Rules Using KIE Server Java Client API

To fire the rules, you need to sent a request to the Realtime Decision Server. In this guide, you will use the KIE Server Java Client API to send requests using REST API. You can use any client to send XML requests to the server.

Note

Make sure you have configured your Maven installation to use Red Hat JBoss BRMS online repositories. For more information about Maven configuration, see the Configuring Maven to Use Online Repositories section from the Red Hat JBoss BPM Suite Installation Guide.

Navigate to a directory of your choice in your system and execute the following command:

~]$ mvn archetype:generate -DgroupId=com.MyProject.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

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

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

You must declare the libraries your Maven project will use. Edit my-app/pom.xml to set the Red Hat JBoss BRMS dependencies. For the current version, see chapter Supported Component Versions of the Red Hat JBoss BRMS Installation Guide.

<dependencies>

  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>3.8.1</version>
    <scope>test</scope>
  </dependency>

  <dependency>
    <groupId>org.drools</groupId>
    <artifactId>drools-compiler</artifactId>
    <version>6.5.0.Final-redhat-2</version>
  </dependency>

  <dependency>
    <groupId>org.drools</groupId>
    <artifactId>drools-core</artifactId>
    <version>6.5.0.Final-redhat-2</version>
  </dependency>

  <dependency>
    <groupId>org.kie.server</groupId>
    <artifactId>kie-server-api</artifactId>
    <version>6.5.0.Final-redhat-2</version>
  </dependency>

  <dependency>
    <groupId>org.kie.server</groupId>
    <artifactId>kie-server-client</artifactId>
    <version>6.5.0.Final-redhat-2</version>
  </dependency>

  <dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>1.7.13</version>
  </dependency>

  <dependency>
    <groupId>org.brms</groupId>
    <artifactId>MyProject</artifactId>
    <version>1.0.0</version>
  </dependency>

</dependencies>

Note

The last dependency is the project you have built in Red Hat JBoss BRMS. The model class (org.brms.myproject.Person in this example) in the client code, that is your Maven application, needs to match your server side, that is the Red Hat JBoss BRMS. Otherwise, the rules will not match when sending a request. The easiest way to achieve this is to share the model class between both sides. You achieve this by adding it as a Maven dependency.

Therefore, make sure that the following attributes match what you had entered while creating a new project in the Business Central:

groupId

artifactId

version

Locate the testApp method in my-app/src/test/java/com/MyProject/app/AppTest.java (which is created by default by Maven).

Edit the AppTest.java. Add the following imports:

import org.kie.api.command.BatchExecutionCommand;
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 org.kie.api.KieServices;
import org.kie.api.command.Command;

import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

import org.brms.myproject.Person;
import org.drools.core.command.impl.GenericCommand;

Locate the testApp() method, load the knowledge base and fire your rule by adding the following code:

Person p1 = new Person();
p1.setFirstName("Anton");
p1.setLastName("RedHat");
p1.setHourlyRate(11);
p1.setWage(20);

String url = "http://localhost:8080/kie-server/services/rest/server";
String username = "kieserver";
String password = "kieserver1!";
String container = "myContainer";
String session = "mySession";

KieServicesConfiguration config = KieServicesFactory
  .newRestConfiguration(url, username, password);
Set<Class<?>> allClasses = new HashSet<Class<?>>();
allClasses.add(Person.class);
config.addJaxbClasses(allClasses);

KieServicesClient client  = KieServicesFactory.newKieServicesClient(config);
RuleServicesClient ruleClient = client.getServicesClient(RuleServicesClient.class);
List<GenericCommand<?>> commands = new ArrayList<GenericCommand<?>>();

commands.add((GenericCommand<?>) KieServices.Factory
  .get().getCommands().newInsert(p1,"Person Insert ID"));
commands.add((GenericCommand<?>) KieServices.Factory
  .get().getCommands().newFireAllRules("fire-identifier"));

BatchExecutionCommand batchCommand = KieServices.Factory
  .get().getCommands().newBatchExecution(commands,session);
ServiceResponse<String> response = ruleClient.executeCommands(container, batchCommand);
System.out.println(response.getResult());

Note that the default marshaller on the server side is JAXB, unless set differently. That means you must set its context with any custom classes you plan to use. In this example, that is Person.class. Since the example uses a stateless session, the marshaller is disposed of once a single command is executed. That is why you need to wrap multiple commands in the BatchCommand object.

To change the marshaller type, enter one of the following commands:

config.setMarshallingFormat(MarshallingFormat.JSON);

config.setMarshallingFormat(MarshallingFormat.XSTREAM);

And add the following import:

import org.kie.server.api.marshalling.MarshallingFormat;

Navigate to my-app and execute the following command from the command line:

~]$ mvn clean install

Note that there is the Maven output and the Red Hat JBoss BRMS output. The expected output in the Red Hat JBoss BRMS console is:

16:26:56,119 INFO  [stdout] (http-/127.0.0.1:8080-5) Hello Anton RedHat!
16:26:56,119 INFO  [stdout] (http-/127.0.0.1:8080-5) You are rich!

Chapter 5. Red Hat JBoss Developer Studio

Red Hat JBoss Developer Studio is the JBoss Integrated Development Environment (IDE) based on Eclipse. Get the latest Red Hat JBoss Developer Studio from the Red Hat Customer Portal. Red Hat JBoss Developer Studio provides plug-ins with tools and interfaces for Red Hat JBoss BRMS and Red Hat JBoss BPM Suite. These plugins are based on the community version of these products. So, the Red Hat JBoss BRMS plug-in is called the Drools plug-in and the Red Hat JBoss BPM Suite plug-in is called the jBPM plug-in.

See the Red Hat JBoss Developer Studio documentation for installation and setup instructions.

Warning

Due to an issue in the way multi-byte rule names are handled, you must ensure that the instance of Red Hat JBoss Developer Studio is started with the file encoding set to UTF-8. You can do this by editing the $JBDS_HOME/studio/jbdevstudio.ini file and adding the following property: "-Dfile.encoding=UTF-8".

Installing Red Hat JBoss Developer Studio Plug-ins

The Drools plug-ins for Red Hat JBoss Developer Studio are available through the update site.

Procedure: Installing Drools Red Hat JBoss Developer Studio Plug-in

Start Red Hat JBoss Developer Studio.

Go to Help → Install New Software.

Click Add to enter the Add Repository menu.

Give the software site a name next to Name field and add the following URL in the Location field: https://devstudio.jboss.com/10.0/stable/updates/integration-stack/.

Click OK.

Select the JBoss Business Process and Rule Development feature from the available options and click Next and then Next again.

Read the license and accept it by selecting the appropriate radio button, and click Finish.

After installation of the plug-ins has completed, restart Red Hat JBoss Developer Studio.

Setting Drools Runtime

In order to use the Red Hat JBoss BRMS plug-in with Red Hat JBoss Developer Studio, it is necessary to set up the runtime.

A runtime is a collection of JAR files that represent a specific release of the software and provides libraries needed for compilation and running of your business assets.

Procedure: Configuring Red Hat JBoss BRMS Runtime

Extract the runtime JAR files located in the jboss-brms-VERSION-engine.zip archive that you can download from Red Hat Customer Portal.

From the Red Hat JBoss Developer Studio menu, select Window and click Preferences.

Select Drools → Installed Drools Runtimes.

Click Add…​; provide a name for the new runtime, and click Browse to navigate to the directory where you extracted the runtime files in the first step. Click OK to register the selected runtime in JBDS.

Mark the runtime you have created as the default Drools runtime by clicking on the check box next to it.

Click OK. If you have existing projects, a dialog box will indicate that you have to restart Red Hat JBoss Developer Studio to update the Runtime.

Configuring Red Hat JBoss BRMS Server

Red Hat JBoss Developer Studio can be configured to run the Red Hat JBoss BRMS Server.

Procedure: Configuring Server

Open the Drools view by selecting Window → Perspective → Open Perspective → Other, then Drools, and click OK.

Add the Server view by selecting Window → Show View → Other…​ and then Server → Servers.

Open the server menu by right clicking the Servers panel and select New → Server.

Define the server by selecting JBoss Enterprise Middleware → JBoss Enterprise Application Platform 6.1+ and clicking Next.

Set the home directory by clicking Browse. Navigate to and select the installation directory for Red Hat JBoss EAP 6.4 which has Red Hat JBoss BRMS installed.

Provide a name for the server in the Name field, make sure that the configuration file is set, and click Finish.

Importing Projects from Git Repository into Red Hat JBoss Developer Studio

Note

This is an additional feature not required for working with Red Hat JBoss Developer Studio.

You can configure Red Hat JBoss Developer Studio to connect to a central Git asset repository. The repository stores rules, models, functions, and processes.

You can either clone a remote Git repository or import a local Git repository.

Procedure: Cloning Remote Git Repository

Start the Red Hat JBoss BRMS server by selecting the server from the Server tab and clicking the start icon.

Simultaneously, start the Secure Shell server, if not running already, by using the following command. The command is Linux and Mac specific only. On these platforms, if sshd has already been started, this command fails. In that case, you may safely ignore this step.

/sbin/service sshd start

In Red Hat JBoss Developer Studio , select File → Import…​ and navigate to the Git folder. Open the Git folder to select Projects from Git and click Next.

Select the repository source as Clone URI and click Next.

Enter the details of the Git repository in the next window and click Next.

Figure 5.1. Git Repository Details

Select the branch you wish to import in the following window and click Next.

To define the local storage for this project, enter (or select) a non-empty directory, make any configuration changes and click Next.

Import the project as a general project in the following window and click Next. Name the project and click Finish.

Procedure: Importing Local Git Repository

Start the Red Hat JBoss BRMS server by selecting the server from the Server tab and click the start icon.

In Red Hat JBoss Developer Studio, select File → Import…​ and navigate to the Git folder. Open the Git folder to select Projects from Git and click Next.

Select the repository source as Existing local repository and click Next.

Figure 5.2. Git Repository Details

Select the repository that is to be configured from the list of available repositories and click Next.

In the dialog that opens, select the radio button Import as general project from the Wizard for project import group and click Next. Name the project and click Finish.

Figure 5.3. Wizard for Project Import

Creating Drools Project

Procedure: Creating New Red Hat JBoss Developer Studio Project

From the main menu, select File → New → Project.

Select Drools → Drools Project and click Next.

Enter a name for the project into the Project name: text box and click Next.

Note

Red Hat JBoss Developer Studio provides the option to add a sample Hello World rule file to the project. Accept this default by clicking Next to test the sample project in the following steps.

Select the Drools runtime (or use the default).

Select code compatible with Drools 6.0.x. Enter a GroupID, an ArtifactID, and Version, and click Finish.

To test the project, right click the Java file that contains the main method and select Run → run as → Java Application.

The output will be displayed on the console tab.

Chapter 6. Business Resource Planner

Business Resource Planner is a lightweight, embeddable planning engine that optimizes planning problems. It helps normal Java™ programmers solve planning problems efficiently, and it combines optimization heuristics and metaheuristics with very efficient score calculations.

Planner helps solve various use cases like the following:

Employee/Patient Rosters: planner helps create timetables for nurses and keeps track of patient bed management.

Educational Timetables: planner helps schedule lessons, courses, exams, and conference presentations.

Shop Schedules: planner tracks car assembly lines, machine queue planning, and workforce task planning.

Cutting Stock: planner minimizes waste by reducing the consumption of resources such as paper and steel.

Installing Business Resource Planner

Navigate to the Red Hat Customer Portal and log in with your user credentials.

Click DOWNLOADS at the top of the page.

In the Product Downloads page that opens, click Red Hat JBoss BRMS.

From the Version drop-down menu, select version 6.4.0.

Select Red Hat JBoss BRMS 6.4 Business Resource Planner and click Download.

Running Business Resource Planner Examples

On the command line, move into the examples/ directory.

In a Unix environment, run the following command:

./runExamples.sh

In a Windows environment, run the following command:

./runExamples.bat

Pick an example from the Examples GUI application that opens and run it in your favorite IDE.

Appendix A. Revision History

Note that revision numbers relate to the edition of this manual, not to version numbers of Red Hat JBoss BRMS.

Table A.1. Revision History

Revision
Date
Author

6.4.0-2

Fri Dec 23 2016

Tomas Radej

Rebuilt with updates.

6.4.0-1

Mon Nov 28 2016

Tomas Radej

Initial build for release 6.4.0 of Red Hat JBoss BRMS.