Getting Started Guide
The Getting Started Guide for Red Hat JBoss BRMS
Abstract
Chapter 1. Introduction
1.1. About Red Hat JBoss BRMS
1.2. Use Case: Business Decision Management in the Insurance Industry with JBoss BRMS
Figure 1.1. BRMS Use Case: Insurance Industry Decision Making
Chapter 2. Quick start with Red Hat JBoss BRMS
Procedure 2.1. BRMS Quick Start
- Download BRMS installer from access.redhat.com.
- Run installer by executing the following command:
java -jar jboss-brms-installer-VERSION.GA-redhat-MINOR.jar
- Step through the GUI installer steps making note of the username/password for accessing the BRMS application after installation.
- After successful installation, in a command prompt, navigate to the EAP home folder where you have installed BRMS.
- Start the BRMS 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 BRMS application that you created at installation time.
Learn more about roles: Section 3.3, “Defining Roles” |
Create additional users: Section 3.4, “Creating users” |
Create a Hello World Rule: Chapter 5, Hello World rule example |
Look up detailed installation instructions for using the installer: Installation Guide |
Chapter 3. Installation
3.1. Downloading Red Hat JBoss BRMS for JBoss EAP
- Go to the Red Hat Customer Portal and log in.
- Click Downloads → Products Downloads.
- In the Product Downloads page that opens, click Red Hat JBoss BRMS.
- From the Version drop-down menu, select version 6.0.3.
- Select Red Hat JBoss BRMS 6.0.3 Deployable for EAP 6.1.1 and then click Download.
3.2. Installing Red Hat JBoss BRMS for Red Hat JBoss Enterprise Application Platform
Installation on a fresh EAP instance
- 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.1
directory). - Unzip the downloaded zip archive: make sure it is merged into the EAP_HOME directory (
jboss-eap-6.1
).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 an existing EAP configuration
- 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.1
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.1
):jboss-eap-6.1/domain/configuration/*
jboss-eap-6.1/standalone/configuration/*
jboss-eap-6.1/modules/layers.conf
jboss-eap-6.1/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. - Ensure the target EAP does not include a deployment with a colliding name. Copy the folder
jboss-eap-6.1/standalone/deployments
into the EAP_HOME directory from the BRMS distribution. - Make sure no EAP module layer is already called BRMS and copy the folder
jboss-eap-6.1/modules/system/layers/brms
into the EAP 6.1.1 folder.
3.3. Defining Roles
- 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.
Note
3.4. Creating users
- Run ./add-user.sh on a Unix system or add-user.bat on a Windows system from the bin directory.
- Enter b to select an Application User at the type of user prompt and press Enter.
- Accept the default Realm (ApplicationRealm): by pressing Enter.
- At the username prompt, enter a user name and confirm. For example:
helloworlduser
. - Create the user's 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 (e.g. A-Z, a-z), at least one numerical character (e.g. 0-9) and at least one special character (e.g. ~ ! @ # $ % ^ * ( ) - _ + =). - Enter a comma separate list of roles the user will need at the roles prompt (refer to Section 3.3, “Defining Roles”).Business Central users need to have the
analyst
or theadmin
role. - Confirm you want to add the user.
- Enter yes at the next prompt (this is to enable clustering in the future if required).
3.5. Installing Red Hat JBoss BRMS on Red Hat JBoss Web Server
Procedure 3.1. Installing the 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 → Products Downloads.
- In the Product Downloads page that opens, click Red Hat JBoss BRMS.
- From the Version drop-down menu, select version 6.0.3
- Select Red Hat JBoss BRMS 6.0.3 Deployable for All Supported Containers package and then click Download.
- Extracting the downloaded archive creates the following zip archives:
jboss-brms-engine.zip
jboss-brms-manager.zip
- Extract
business-central.war
from thejboss-brms-manager.zip
archive and copy totomcat7/webapps/
. - Remove the
.war
extension from thebusiness-central.war
so that directory is now calledbusiness-central
. - Define the users and the roles in
tomcat7/conf/tomcat-users.xml
as shown below:<role rolename="admin"/> <role rolename="analyst"/> <user username="user" password="password" roles="admin,analyst"/>
- Edit the
web.xml
file in thetomcat7/webapps/business-central/WEB-INF
directory by uncommenting all entries that are marked withTOMCAT-JEE-SECURITY
. For example:<!-- TOMCAT-JEE-SECURITY --> <!-- <init-param> <param-name>org.uberfire.auth.scheme</param-name> <param-value>org.uberfire.security.server.auth.JACCAuthenticationScheme</param-value> </init-param> -->
Should be uncommented like the following:<!-- TOMCAT-JEE-SECURITY --> <init-param> <param-name>org.uberfire.auth.scheme</param-name> <param-value>org.uberfire.security.server.auth.JACCAuthenticationScheme</param-value> </init-param>
- Copy the
kie-tomcat-integration-VERSION.jar
file frombusiness-central/WEB-INF/lib
in BRMS distribution totomcat7/lib
. - Copy the
slf4j-api-VERSION.jar
file and theslf4j-ext-VERSION.jar
file frombusiness-central/WEB-INF/lib
in BRMS distribution totomcat7/lib
. - Download the file below and place it in the
tomcat7/lib
directory. - Add the below Tomcat Valve declaration into
tomcat7/conf/server.xml
(inside the relevant <host> element):<Valve className="org.kie.integration.tomcat.JACCValve"/>
- Rename
org.uberfire.security.auth.AuthenticationSource
toorg.uberfire.security.auth.AuthenticationSource-ORIGIN
andorg.uberfire.security.auth.AuthenticationSource-TOMCAT-JEE-SECURITY
toorg.uberfire.security.auth.AuthenticationSource
inside thebusiness-central/WEB-INF/classes/META-INF/services
- Start JBoss Web Server by running
startup.sh
in thetomcat7/bin
directory../startup.sh
- Navigate to http://localhost:8080/business-central in a web browser.
- Login with the correct username/password as given in the
tomcat-users.xml
file where you defined user roles.
3.6. Starting the server
Note
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
standalone-secure.sh
that is optimized for security. This script applies a security policy by default that protects against a known security vulnerability.
Note
standalone-secure.sh
script.
Warning
- 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
3.7. Java Security Manager and performance management
- 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.
Chapter 4. Logging on to Business Central
- 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 5. Hello World rule example
Hello World
project with a Hello World
business rule.
- Create a Hello World repository in the Artifact repository.
- Create the Hello World Project.
- Create the Hello World rule.
- Build and deploy the project.
5.1. Creating repository structure
- Open Business Central in your web browser (if running locally http://localhost:8080/business-central) and log in as a user with the
admin
role (helloworlduser
). - Create an organizational unit in the Artifact repository:
- Go to Authoring → Administration.
- On the perspective menu, click Organizational Units → Manage Organizational Units.
- In the displayed Organizational Unit Manager view, click Add.In the displayed Add New Organizational Unit dialog box, define the unit properties and click OK:
- Name:
helloworld
- Owner:
helloworlduser
- Create a new repository in the helloworld organizational unit:
- Go to Authoring → Administration.
- On the perspective menu, click Repositories → New repository.
- In the displayed Create Repository dialog box, define the repository properties:
- Repository Name:
helloworldrepo
- Organizational Unit:
helloworld
- Go to Authoring → Project Authoring.
- In the Project Explorer in the organizational unit drop-down box, select
helloworld
, and in the repository drop-down box selecthelloworldrepo
.Figure 5.1. Selecting the
helloworldrepo
repository in thehelloworld
organizational unit in Project Explorer - Create a project in the
helloworld
repository:- On the perspective menu, go to New Item → Project
- In the displayed Create new dialog box, define your Project properties:
- Resource Name (project name):
HelloWorld
- Path:
default://master@helloworldrepo/
- In the New Project Wizard dialog, define the maven properties of the Project. Press Enter after making each entry:
- Group ID:
org.brms
- Artifact ID:
HelloWorld
- Version ID:
1.0
- Click Finish.
5.2. Creating the business rule
helloworldrule
business rule in the HelloWorld
project, do the following:
- In Project Explorer, select the
helloworld
organizational unit, thehelloworldrepo
repository, theHelloWorld
project, and the default package.Note
Make sure to select the default package. Selection of an incorrect package causes the deployment to fail. - Create the DRL file:
- On the perspective menu, click New Item → DRL file.
- In the Create new dialog box, define the resource name as
helloworldrule
and check that the destination path isdefault://master@helloworldrepo/HelloWorld/src/main/resources
. - Click OK.
- In the displayed DRL editor with the
helloworldrule.drl
file, define the rule:rule "helloworldrule" ruleflow-group "helloworldgroup" when then System.out.println("Hello World!"); end
This rule does not define any when condition, that is, it will always be true when fired (called to execute) and theHello World!
phrase will be printed. - Click Save.
- A Save this item prompt is displayed. Enter the Check-in comment and click Save.
Note
The check-in comment would be a short description of the kind of change you made and has to be entered every time an asset is saved.
5.3. Building and deploying
- On the main menu of Business Central, go to Authoring → Project Authoring.
- In the Project Explorer, locate the Hello World project.
- Open the Project in the Project editor: on the perspective menu, click Tools → Project Editor.
- Check that the correct Project details are displayed on the Project Screen and click the Build & Deploy button in the upper right hand corner of the Project Screen view.
Figure 5.2. Project editor with the helloWorld project properties
helloWorld
deployment is substituted with the new version with the Business Rule Task. To keep both deployments, change the version number of the Project in the Project editor.
Chapter 6. Red Hat JBoss Developer Studio
6.1. Installing the JBoss Developer Studio Plug-ins
Procedure 6.1. Install the Drools JBoss Developer Studio Plug-in
- Start JBoss Developer Studio.
- Select 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/updates/7.0/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 JBoss Developer Studio.
6.2. Setting the Drools runtime
Procedure 6.2. Configure BRMS Runtime
- From the 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 the runtime is located. 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 JBoss Developer Studio to update the Runtime.
6.3. Configuring the JBoss BRMS Server
Procedure 6.3. Configure the Server
- Open the Drools view by selecting Window → Open Perspective → Other and select Drools and click OK.
- Add the server view by selecting Window → Show View → Other... and select 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 the Browse button. Navigate to and select the installation directory for JBoss EAP 6.1.1 which has JBoss BRMS installed.
- Provide a name for the server in the Name field, make sure that the configuration file is set, and click Finish.
6.4. Importing Projects from a Git Repository into JBoss Developer Studio
Procedure 6.4. Cloning a Remote Git Repository
- Start the Red Hat JBoss BRMS server (if not already running) by selecting the server from the server tab and click 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 will fail and you may safely ignore this step.
/sbin/service sshd start
- In 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 6.1. Git Repository Details
- Select which branch you want to import in the following window and click Next.
- You will be presented with the option 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 6.5. Importing a Local Git Repository
- Start the Red Hat JBoss BRMS server (if not already running) by selecting the server from the server tab and click the start icon.
- In 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 6.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 6.3. Wizard for Project Import
6.5. Creating a Drools Project
Procedure 6.6. Creating a 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
JBoss Developer Studio provides the option to add a sample HelloWorld 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 7. Business Resource Planner
- 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.
7.1. Installing Business Resource Planner
- Navigate to the Red Hat Customer Portal and log in with your user credentials.
- Select Downloads → Red Hat JBoss Middleware → Download Software.
- From the Products drop-down menu, select BPM Suite.
- From the Version drop-down menu, select the product version 6.0.2.
- Select Red Hat JBoss BPM Suite 6.0.2 Business Resource Planner and then click Download.
7.2. Running the 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
Revision History | |||
---|---|---|---|
Revision 1.0.0-21 | Mon Sep 22 2014 | Vikram Goyal | |
|