JBoss Enterprise BRMS Platform 5

BRMS Getting Started Guide

For JBoss Administrators

Edition 5.3.1

Red Hat Content Services

Legal Notice

Copyright © 2013 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
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, MetaMatrix, 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 the steps necessary for administrators to install JBoss Enterprise Business Rules Management System Platform, the plug-ins for JBoss Developer Studio, and provides instructions for running example projects.

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later include the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example:
To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to a virtual terminal.
The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:
File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose SystemPreferencesMouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose ApplicationsAccessoriesCharacter Map from the main menu bar. Next, choose SearchFind… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose EditPaste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
Publican is a DocBook publishing system.

1.2. Pull-quote Conventions

Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in mono-spaced roman and presented thus:
books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs
Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:
package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.

Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. Getting Help and Giving Feedback

2.1. Do You Need Help?

If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at http://access.redhat.com. Through the customer portal, you can:
  • search or browse through a knowledgebase of technical support articles about Red Hat products.
  • submit a support case to Red Hat Global Support Services (GSS).
  • access other product documentation.
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at https://www.redhat.com/mailman/listinfo. Click on the name of any mailing list to subscribe to that list or to access the list archives.

2.2. Give us Feedback

If you find a typographical error, or know how this guide can be improved, we would love to hear from you. Submit a report in Bugzilla against the product JBoss Enterprise BRMS Platform 5 and the component Documentation. The following link will take you to a pre-filled bug report for this product: https://bugzilla.redhat.com/.
Fill out the following template in Bugzilla's Description field. Be as specific as possible when describing the issue; this will help ensure that we can fix it quickly.
Document URL:


Section Number and Name:


Describe the issue:


Suggestions for improvement:


Additional information:


Be sure to give us your name so that you can receive full credit for reporting the issue.

Chapter 1. Introduction

1.1. JBoss Enterprise Business Rules Management System Platform

JBoss Enterprise BRMS Platform is a business rules management system for the management, storage, creation, modification, and deployment of business rules . Web-based user interfaces and plug-ins for JBoss Developer Studio provide users with different roles the environment suited to their needs. JBoss Enterprise BRMS provides specialized environments for business analysts, rules experts, developers, and rule administrators.
JBoss Enterprise BRMS Platform is supported on a variety of operating systems, Java Virtual Machines (JVMs), and database configurations. A full list of certified and compatible configurations can be found at http://www.redhat.com/resourcelibrary/articles/jboss-enterprise-brms-supported-configurations.

Chapter 2. Installation

2.1. Installation Options

The JBoss Enterprise BRMS Platform can be installed as a standalone server with BRMS already deployed to an application server (BRMS 5.3.1 comes already deployed to JBoss Enterprise Application Platform 5.2) or as a web archive that can be deployed to an existing application server

2.2. Installing the Standalone Package

The JBoss Enterprise BRMS Platform 5.3.1 standalone package will be based on JBoss Enterprise Application Platform 5.2, and will be available at a later date when JBoss Enterprise Application Platform 5.2 becomes available.
The following procedure details how to install the JBoss Enterprise BRMS Platform 5.3 standalone package.

Procedure 2.1. Installing the Standalone Package

  1. Download the standalone package zip file from the Red Hat Customer Support Portal at https://access.redhat.com. Select DownloadsDownload your softwareBRMS Platform, then select the version. The current version is 5.3.0, these instructions use the package names for 5.3.0 but also apply to earlier versions except where noted.
  2. Extract the contents of the standalone zip archive to install the server. This creates the brms-standalone-5.3.0 directory which includes an installation of JBoss Enterprise Application Platform with JBoss Enterprise BRMS Platform deployed.

    Note

    JBoss Enterprise BRMS Platform 5.3.0 is deployed to either the default or production profiles. This guide uses the default profile.
  3. Enable Users. The default configuration uses the BRMS JAAS application profile. This profile stores user names and passwords in the brms-standalone-5.3.0/jboss-as/server/default/conf/props/brms-users.properties file.
    Users are added by adding entries to this file in the format username=password. Entries can be commented out by adding a hash character (#) to the beginning of the line.
    #admin=password
    jsmith=s@r@hSm1th
    tandrews=pp3rrss0nn3ll
    Refer to the BRMS Administration Guide for information about changing the JAAS profile to one that supports a different authentication system, such as LDAP.
  4. The default configurations use embedded databases that are not suitable or supported for production environments. Before deploying into a production environment this configuration must be changed to a supported database. Please refer to the BRMS Administration Guide for database configuration instructions.
  5. Start the server from the command line with the run.sh command on a UNIX or Linux system, or run.bat on a Microsoft Windows system.
    [localhost ]$ ./run.sh -c default
    The run.sh and run.bat scripts are located in the bin directory.
    For example, the full path to the bin directory for the BRMS 5.3.0 standalone server is brms-standalone-5.3.0/jboss-as/bin/.
    After successfully starting a message is displayed on the command line reporting how long it took the server to start.

2.3. Installing the Deployable Package

The deployable package is provided for customers to install JBoss Enterprise BRMS Platform 5.3.1 to an existing application server. JBoss Enterprise BRMS 5.3.1 is supported on the following containers:
  • JBoss Enterprise Application Platform 5.1.2, 5.2.0, and 6.0.0
  • JBoss Enterprise SOA Platform 5.3.0
  • JBoss Enterprise Web Server 1.0.2 and 2.0.0

Procedure 2.2. Installing the Deployable Package

  1. Download the deployable package zip file from the Red Hat Customer Support Portal at https://access.redhat.com.
    Select DownloadsDownload your softwareBRMS Platform, and then select the version and choose the deployable package.
    Users installing to JBoss Enterprise Application Platform 6 should download the package that includes EE6 as part of the filename. All other users should download the package that does not include EE6 as part of the filename.
  2. Extracting the downloaded archive creates the following zip archives:
    • jboss-brms-engine.zip
    • jboss-brms-manager.zip
    • jboss-jbpm-console.zip
    • jboss-jbpm-engine.zip
    • modeshape.zip
    Modeshape is a Java Content Repository (JCR) that is included in JBoss Enterprise BRMS 5.3.1 as a technical preview; see the BRMS Administration Guide for further details.
  3. Extract jboss-brms.war from the jboss-brms-manager.zip archive and copy to the application server's deploy directory.
    The deploy directories are as follow:
    • JBoss Enterprise Application Platform 5.x:
      jboss-as/server/profile/deploy/
    • JBoss Enterprise Application Platform 6.0:
      jboss-eap-6.0/standalone/deployments/
    • JBoss Enterprise SOA Platform:
      jboss-esb/server/profile/deploy/
    • JBoss Enterprise Web Server 1:
      tomcat6/webapps/
    • JBoss Enterprise Web Server 2:
      tomcat7/webapps/
  4. Extract business-central.war, business-central-server.war, designer.war, and jbpm-human-task.war from the jboss-jbpm-console.zip archive and copy to the application server's deploy directory as above.
  5. JBoss Enterprise Web Server users must remove the .war extension from the name of the war archives. After the archives have been renamed the webapps/ directory should contains the following subdirectories:
    • jboss-brms
    • business-central
    • business-central-server
    • designer
    • jbpm-human-task
  6. JBoss Enterprise Application Platform 6 users must create the following empty files in the jboss-eap-6.0/standalone/deployments/ directory:
    • jboss-brms.war.dodeploy
    • business-central.war.dodeploy
    • business-central-server.war.dodeploy
    • designer.war.dodeploy
    • jbpm-human-task.war.dodeploy
  7. Extract the jboss-jbpm-engine.zip directory and copy the netty.jar file from jboss-jbpm-engine/lib/ into a directory that will be on the classpath.
    • JBoss Enterprise Application Platform 5:
      common/lib/
    • JBoss Enterprise SOA Platform 5.x:
      common/lib/
    • JBoss Enterprise Web Server 1:
      tomcat6/lib/
    • JBoss Enterprise Web Server 2:
      tomcat7/lib/

    Note

    Both JBoss Enterprise Application Platform 5.x and JBoss Enterprise SOA Platform include a netty.jar file; however, JBoss Enterprise BRMS requires the specific version of netty.jar that is included with the JBoss Enterprise BRMS download.
    JBoss Enterprise Application Platform 6 users do not need to extract netty.jar from the jboss-jbpm-engine.zip directory. Instead, edit the jboss-eap-6.0/standalone/configuration/standalone.xml file so that the application server will load the required netty library.
    Update the "urn:jboss:domain:ee:1.1" subsystem property to match the following code snippet:
    <subsystem xmlns="urn:jboss:domain:ee:1.1">
       <global-modules>
    	  <module name="org.jboss.netty" slot="main"/>
       </global-modules>
       <spec-descriptor-property-replacement>false</spec-descriptor-property-replacement>
       <jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement>
    </subsystem>
    
  8. When deploying to JBoss Enterprise Web Server, copy the antlr, common-collections, dom4j, javassist, jta, hibernate, log4j, and slf4j jar files from the jboss-jbpm-engine/lib/ directory to the application server's lib directory.
    • JBoss Enterprise Web Server 1:
      tomcat6/lib/
    • JBoss Enterprise Web Server 2:
      tomcat7/lib/
  9. The default configurations use embedded databases that are not suitable or supported for production environments. Before deploying into a production environment, this configuration must be changed to a supported database. Please refer to the BRMS Administration Guide for database configuration instructions.

2.4. Installing on JBoss Enterprise Application Platform 6

Procedure 2.3. Installing the Deployable Package

  1. Download the deployable package zip file from the Red Hat Customer Support Portal at https://access.redhat.com.
    Select DownloadsDownload your softwareBRMS PlatformJBoss BRMS 5.3.1 Deployable for EAP 6.
  2. Extracting the downloaded archive creates the following zip archives:
    • jboss-brms-engine.zip
    • jboss-brms-manager-ee6.zip
    • jboss-jbpm-console-ee6.zip
    • jboss-jbpm-engine.zip
    • modeshape.zip
    Modeshape is a Java Content Repository (JCR) that is included in JBoss BRMS 5.3 as a technical preview, see the BRMS Administration Guide for further details.
  3. Extract jboss-brms.war from the jboss-brms-manager.zip archive and copy to the jboss-eap-6.0/standalone/deployments/ directory.
  4. Extract business-central.war, business-central-server.war, desginer.war, and jbpm-human-task.war from the jboss-jbpm-console-ee6.zip archive and copy to the jboss-eap-6.0/standalone/deployments/ directory.
  5. Create the following empty files in the jboss-eap-6.0/standalone/deployments/ directory:
    • jboss-brms.war.dodeploy
    • business-central.war.dodeploy
    • business-central-server.war.dodeploy
    • desginer.war.dodeploy
    • jbpm-human-task.war.dodeploy
  6. Edit the jboss-eap-6.0/standalone/configuration/standalone.xml file so that the application server will load the required netty library.
    Update the "urn:jboss:domain:ee:1.1" subsystem property to match the following code snippet:
    <subsystem xmlns="urn:jboss:domain:ee:1.1">
       <global-modules>
    	   <module name="org.jboss.netty" slot="main"/>
       </global-modules>
    	<spec-descriptor-property-replacement>false</spec-descriptor-property-replacement>
    	<jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement>
    </subsystem>
    
  7. Edit the name of the datebase in jboss-eap-6.0/standalone/configuration/standalone.xml changing it to jbpmDS:
    <subsystem xmlns="urn:jboss:domain:datasources:1.1">
       <datasources>
          <datasource jndi-name="java:jboss/datasources/jbpmDS" pool-name="jbpmDS" enabled="true" use-java-context="true">
             <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
             <driver>h2</driver>
             <security>
                <user-name>sa</user-name>
                <password>sa</password>
             </security>
          </datasource>
          <drivers>
             <driver name="h2" module="com.h2database.h2"/>
          </drivers>
       </datasources>
    </subsystem>

    Note

    The included H2 database is not supported. It is provided for demonstration purposes only and must be changed to a supported database. Please refer to the JBoss BRMS 5 Administration Guide for database configuration instructions.

2.5. Configuring Authentication

The default authentication configuration uses the jmx-console JAAS application profile. If deploying to an existing application server, it is possible that this profile has already been modified. In that case, refer to the application server documentation for instructions on adding new users. To change the default authentication, or add additional users, refer to the JBoss Enterprise BRMS Administrator Guide.
JBoss Enterprise Application Platform 5.x and JBoss Enterprise SOA Platform
When deploying to JBoss Enterprise Application Platform 5.x or JBoss Enterprise SOA Platform, add the login module policy to server/profile/login-config.xml. The org.jboss.security.auth.spi.UsersRolesLoginModule in the example below is provided as an example only.
<application-policy name="brms">
   <authentication>
      <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
         <module-option name="usersProperties">props/brms-users.properties</module-option>
         <module-option name="rolesProperties">props/brms-roles.properties</module-option>
      </login-module>
   </authentication>
</application-policy>
JBoss Enterprise Application Platform 6
When deploying to JBoss Enterprise Application Platform 6, edit the jaas-config-name property in jboss-eap-6.0/standalone/deployments/jboss-brms.war/WEB-INF/components.xml to brms:
<security:identity authenticate-method="#{authenticator.authenticate}" jaas-config-name="brms"/>
JBoss Enterprise Web Server
When deploying to JBoss Enterprise Web Server, create a jaas.config file, and add the login module policy. The org.jboss.security.auth.spi.UsersRolesLoginModule in the example below is provided as an example only.
brms {
org.jboss.security.auth.spi.UsersRolesLoginModule required debug=true;
};
Save the file to the following location:
  • JBoss Enterprise Web Server 1:
    tomcat6/conf/
  • JBoss Enterprise Web Server 2:
    tomcat7/conf

Note

When using the above example for evaluation purposes, it is necessary to copy the jbosssx.jar from the JBoss Enterprise standalone download. Copy the jbosssx.jar file from the standalone download jboss-as/lib/ to the tomcat6/lib/ directory.
Open the tomcat/6/bin/catalina.sh file and search for the following line:
# ----- Execute The Requested Command ------
Add the following line directly after the above line:
JAVA_OPTS="$JAVA_OPTS -Xms1303m -Xmx1303m -XX:MaxPermSize=512m -Djava.security.auth.login.config=$CATALINA_BASE/conf/jaas.config"

2.6. Adding Users

Usernames, passwords, and roles are added to properties files.
Usernames and passwords are defined as follows:
username=password
Roles are defined as follows:
username=JBossAdmin,httpInvoker,user,admin
JBoss Enterprise Application Platform and JBoss Enterprise SOA Platform use the brms-users.properties file for usernames and passwords and brms-roles.properties to define roles.
Jboss Enterprise Web Server uses the users.properties file for usernames and passwords and roles.properties to define roles. JBoss Enterprise Web Server users must also add the username, passwords, and roles to the tomcat6/conf/tomcat-users.xml file:
<role rolename="manager-gui"/>
<role rolename="manager-script"/>
<role rolename="manager-jmx"/>


<role rolename="user"/>

<user username="admin" password="admin" roles="manager-gui,manager-script,manager-jmx,user"/>

Note

Users who are given permission to access the business central console must have one of the following roles: administrator, manager, or user.
Create the properties files in the following directory or on the classpath:
  • JBoss Enterprise Application Platform 5.x:
    jboss-as/server/profile/conf/props/
  • JBoss Enterprise SOA Platform:
    jboss-esb/server/profile/conf/props/
  • JBoss Enterprise Web Server 1:
    tomcat6/lib/
  • JBoss Enterprise Web Server 2
    tomcat7/lib/
  • JBoss Enterprise Application Platform 6:
    jboss-eap-6.0/standalone/configuration/
JBoss Enterprise Application Platform 6 users must update the security domain to include references to brms-users.properties and brms-roles.properties by editing the jboss-eap-6.0/standalone/configuration/standalone.xml by adding the following XML:
<security-domain name="brms" cache-type="default">
   <authentication>
      <login-module code="UsersRoles" flag="required">
         <module-option name="usersProperties" value="${jboss.server.config.dir}/brms-users.properties"/>
         <module-option name="rolesProperties" value="${jboss.server.config.dir}/brms-roles.properties"/>
      </login-module>
   </authentication>
</security-domain>

2.7. Password Configuration for JAAS

When using the default JAAS authentication system, usernames and passwords need to be synchronized between JBoss Enterprise BRMS, the Process Designer, and the Business Central console. If the same usernames and passwords are not used, the different components will not function together.
If the additional users are added to the brms-users.properties file, they also need to be synchronized for the Process Designer and Business Central Console.

Procedure 2.4. Synchronizing Usernames and Passwords

  1. Process Designer: To edit the usernames and passwords for the Process Designer, which is a separate application integrated with JBoss Enterprise BRMS, open the designer.war/profiles/jbpm.xml file and edit the usr and pwd properties:
    usr="admin" pwd="admin"
  2. Business Central Console. To edit the usernames and passwords for the Business Central Console, open the business-central-server.war/WEB-INF/classes/jbpm.console.properties file and edit the guvnor.usr and guvnor.pwd properties:
    guvnor.usr=admin
    guvnor.pwd=admin

2.8. Configuring Business Process Management

Procedure 2.5. Configuring Business Process Management

  1. Configure the human task server by editing web.xml, which is located in jbpm-human-task.war/WEB-INF/. The human task server defaults to HornetQ. web.xml is annotated with instructions. If further information is required, please refer to the Human Tasks chapter of the JBoss BRMS Business Process Management Guide.
  2. Configure the Business Central Console by editing the jbpm.console.properties file, which is located in the business-central-server.war/WEB-INF/classes/ directory. This jbpm.console.properties file allows users to configure the console host and port number, task server connectivity, and repository connectivity. Refer to the Business Central Console chapter of the JBoss BRMS Business Process Management Guide for further details.
  3. Configure the process designer by editing the jbpm.xml file, which is located in the designer.war/profiles/ directory. The jbpm.xml file allows users to set the host and port number, username and password. Refer to the Process Designer chapter of the JBoss BRMS Business Process Management Guide for further details.

2.9. Starting the Server

When installing to JBoss Enterprise Application Platform 5.x or JBoss Enterprise SOA Platform, start the server by running the run.sh command on a Unix or Linux system, or run.bat command on a Microsoft Windows system.
When installing to JBoss Enterprise Application Platform 6, start the server by running the standalone.sh command.
When installing to JBoss Enterprise Web server or Apache Tomcat, start the server by running the startup.sh command on a UNIX or Linux system or startup.bat command on a Microsoft Windows system.
Use the -c switch to specify which profile to use. i.e.,
[localhost ]$ ./run.sh -c default
After successfully starting, a message is displayed on the command line reporting how long it took the server to start.

2.10. Clustering the Business Central Console

The Business Central Console can be clustered so that multiple instances of the console and the process engine attached to the console can share the same data in a persisted database. Clustering the console makes it possible to spread the available processes across the cluster, and it also ensures failover if a node in the cluster fails.
The JBoss BRMS rule engine, repository, user interface, and process designer are installed on one host, and instances of the business central console and the process engine are installed on one or more other hosts.

Procedure 2.6.  Installing the Business Central Console as a Cluster

  1. Download the JBoss BRMS standalone package file from the Red Hat Customer Support Portal at https://access.redhat.com. Select DownloadsDownload your softwareBRMS Platform and then select the version.
  2. Copy the downloaded archive onto the host where the JBoss BRMS engine, user interface, repository, and process designer will be installed. Extract the contents of the standalone zip archive to install the server. This creates the brms-standalone-5.3.1 directory which includes an installation of JBoss Enterprise Application Platform with JBoss Enterprise BRMS Platform deployed.
  3. Remove the following directories: jbpm-console.war, business-central-server.war, and jbpm-human-task.war from jboss-as/server/default/deploy/ as they will be deployed on other hosts. If the production profile is being used, remove the directories from jboss-as/server/production/deploy/.
  4. Edit the preferences.properties file located in jboss-brms.war/WEB-INF/classes/ by replacing the word localhost with the host's IP address for both the designer.url and guvnor.url properties.
  5. Edit the jbpm.xml file located in designer.war/profiles by replacing the word localhost with the host's IP address for the externalloadurl property.
  6. Copy the downloaded JBoss BRMS standalone archive onto the hosts where the Business Central Console and engine will be installed. Extract the contents of the standalone zip archive.
  7. Remove the following directories jboss-brms.war and designer.war from jboss-as/server/default/deploy/ as they have already been installed on the first host and are not required. If the production profile is being used, remove the directories from jboss-as/server/production/deploy/.
  8. Edit the jbpm.console.properties file, located in business-central-server.war/WEB-INF/classes/, by replacing the word localhost from the guvnor.host property with the IP address of the first host created in this procedure. This tells the current host where to locate the BRMS repository which is shared across the cluster.
  9. Add the current host's IP address to the jbpm.console.server.host property. This should be done for each node in the cluster where the Business Central Console will be installed.
  10. Update the persistence.xml file located in both business-central-server/WEB-INF/classes/META-INF/ and jbpm-human-task.war/WEB-INF/classes/META-INF/ to include the data source.
    <jta-data-source>java:/myDataSource</jta-data-source>
    Remove the following line from persistence.xml in both directories:
    <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
    Edit the following line to include the value update:
    <property name="hibernate.hbm2ddl.auto" value="update" />
  11. Start each of the nodes in the cluster with the following command, remembering to provide the partition name, UDP multicast address address, and host IP address:
    ./run.sh -c node1 -g partitionName -Djboss.messaging.ServerPeerID=1 -u UDPMulticastAddress -b hostIPAddress

2.11. Logging On

Log into the JBoss BRMS web user interface and Business Central Console after the server has successfully started.

Procedure 2.7. Logging on

  1. Log on to the BRMS user interface by pointing a web browser to http://localhost:8080/jboss-brms and entering the user credentials created when enabling users.
    If this is the first log on, a prompt will ask if a sample repository should be installed. The sample rules are useful for training, testing and demonstrative proposes.
  2. Log on to Business Central Console by pointing a web browser to http://localhost:8080/business-central and entering the user credentials created when enabling users. The Business Central Console allows users to manage business processes.

Chapter 3. User Authorization

3.1. Enabling Role-Based Authorization

JBoss BRMS uses role-based authorization to assign user permissions. Role-based authorization is disabled by default and all users have full administrative permissions.

Procedure 3.1.  Enable Role-Based Authorization

  1. Before enabling role-based authorization, it is necessary to assign one trusted user the admin role.
    1. From the JBoss Enterprise BRMS web user interface navigation panel, select AdministrationUser Permissions.
    2. Click Create new user mapping and enter the name of the user to be granted Admin permissions. Note, this user must already exist in the brms-users.properties file.
    3. Click Open next to the username whose permissions are being changed.
    4. Click the plus icon to add permissions, and select admin, click OK, and click Save changes.
      After the system has saved the changes Yes will be displayed under Administrator.
  2. Shut down the application server before making these changes.
  3. Open the jboss-as/server/production/deploy/jboss-brms.war/WEB-INF/components.xml file in a text editor.
  4. In the default components.xml file, locate the following code and replace false with true:
    <component name="org.jboss.seam.security.roleBasedPermissionResolver">
       <property name="enableRoleBasedAuthorization">false</property>
    </component>
    

    NOTE

    In versions 5.1 and earlier, locate and edit the following XML replacing false with true:
    <security:role-based-permission-resolver enable-role-based-authorization="false"/<
    
  5. Restart the application server.
  6. Log back into the BRMS web user interface. From the navigation panel, select AdministrationUser Permissions and assign users roles as required.
  7. Click Open next to the username whose permissions are being changed. Select the required role for the user, click OK, and click Save changes.

    NOTE

    Users can be assigned more than one role.
    Users assigned the admin role can modify the roles and permissions of other users.

Chapter 4. JBoss Developer Studio

4.1. JBoss Developer Studio

JBoss Developer Studio is the JBoss Integrated Development Environment available from the Red Hat customer support portal at https://access.redhat.com. JBoss Developer Studio provides tools and interfaces for developers working with JBoss Enterprise BRMS.
Please refer to the JBoss Developer Studio 5.0 Getting Started Guide for installation instructions.

4.2. Installing the JBoss Developer Studio Plug-ins

The Drools and jBPM plug-ins for JBoss Developer Studio are available via the update site and can be installed from JBoss Central.

Procedure 4.1. Install the Drools and jBPM JBoss Developer Studio Plug-in

  1. Start JBoss Developer Studio.
  2. From the welcome page, select Get started with JBoss Central.
  3. Select Software/Update from JBoss Central.
    JBoss Central Software/Update

    Figure 4.1.  JBoss Central Software/Update


  4. Select Business Rules Tooling and click Install.
  5. Review the installation details and click Next and then Next again.
  6. Read the license and accept it by selecting the appropriate radio button, and click Finished.
  7. After installation of the plug-ins has completed, restart JBoss Developer Studio.

4.3. Setting the Drools and jBPM Runtimes

In order to use the Drools and jBPM plug-ins with JBoss Developer Studio, it is necessary to set up the Drools and jBPM runtimes.
A runtime is a collection of jar files that represent a specific release of the software.

Procedure 4.2.  Configure Drools Runtime

  1. From the JBoss Developer Studio menu, select Preferences.
  2. Select Droolsinstalled Drools Runtimes.
  3. Click Add...; provide a name for the new runtime, and click Browse to navigate to the directory where the drools runtime is located. For instance, in the BRMS 5.3.1 standalone installation, the drools runtime is located brms-standalone-5.3.1/jboss-as/client/drools/.
  4. Click OK and select the new runtime. A dialogue box will indicate JBDS must be restarted to update the Runtime.

Procedure 4.3. Configure jBPM Runtime

  1. From the JBoss Developer Studio menu, select Preferences.
  2. Select jBPMinstalled jBPM Runtimes.
  3. Click Add..., provide a name for the new runtime, and click Browse to navigate to the directory where the jBPM runtime is located. For instance, in the BRMS 5.3 standalone installation the jBPM runtime is located brms-standalone-5.3.1/jboss-as/client/jbpm/.
  4. Click OK and select the new runtime. A dialogue box will indicate JBDS must be restarted to update the Runtime.

4.4. Configuring the JBoss BRMS Server

JBoss Developer Studio can be configured to run the JBoss Enterprise BRMS server.

Procedure 4.4. Configure the Server

  1. Open the Drools view by selecting WindowOpen PerspectiveOther and select Drools and click OK.
  2. Add the server view by selecting WindowShow ViewOther... and select ServerServers.
  3. Open the server menu by right clicking the Servers panel and select NewServer.
  4. Define the server by selecting JBoss Enterprise MiddlewareJBoss Enterprise Application Platform 5.x.
  5. Set the home directory by clicking the Add... link next to Server runtime environment.
    Provide a name for the server in the Name field.
    Click Browse to set the Home Directory; navigate to the BRMS installation and select the jboss-as directory.
    Select the server profile Production from the configuration options and click Finish and then Finish again.

4.5. JBoss Developer Studio Perspectives

JBoss Developer Studio provides perspectives designed for working on different kinds of projects. A perspective populates the workbench with the windows and palettes typically needed for that type of project.
The perspectives of interest to JBoss Enterprise BRMS users are the following:
  • Drools
  • Guvnor Repository Exploring
  • jBPM
To open a perspective select WindowOpen PerspectiveOther and select the required perspective.

4.6. Connecting JBoss Developer Studio to the Asset Repository

Procedure 4.5. Connect JBDS to the Asset Repository

  1. Start the JBoss BRMS server by selecting the server from the server tab and click the start icon.
  2. Open the Guvnor repository by selecting WindowShow ViewOther.
    Select GuvnorGuvnor Repository and click OK.
  3. Add the Guvnor connection by selecting Add a Guvnor repository connection icon from the Guvnor Repository view.
  4. Confirm the repository details displayed are correct.
    Enter the Guvnor username and password and click Finish.
Guvnor Preferences
The JBoss Developer Studio preferences for the Guvnor plug-ins allows user to choose whether or not to save authentication information when connecting to a Guvnor repository, and it allows users to define a Guvnor URL template for creating new connections.
The Guvnor preferences are set by accessing the preferences menu. Select WindowPreferencesGuvnor to access the preferences.

4.7. Working with Guvnor Files Locally

Resources stored in the Guvnor repository can be copied to JBoss Developer Studio allowing developers to work with files locally.
Use the Resources from Guvnor wizard to copy files from the Guvnor repository to the local workspace.

Importing Guvnor Repository Resources

  • Select FileImportGuvnorResources from Guvnor.
  • Select the repository connection.
  • Select the resources to be copied.
  • Select the target location in the local workspace.
When local copies of Guvnor repository files are created, JBoss Developer Studio sets an association between the local copy and the master file in the repository. This information is kept in the (normally) hidden .guvnorinfo folder in the local project and, like all metadata, should not be changed by end users.
The association allows for operations such as update and commit in synchronization with the master copy held in the Guvnor repository.
The following actions can be performed though the Guvnor context menus in JBoss Developer Studio:
Update Action:
The Update action is available for one or more Guvnor resources that are not synchronized with the Guvnor repository master copies. These files would be out of synchronization due to one or both of the following conditions:
  • There are local changes to the resources.
  • The master copies have been changed in the Guvnor repository.
Performing the Update action replaces the contents of the local file with the contents of the associated master copies in the Guvnor repository.
Add Action:
The Add action adds a local file that is not associated with a Guvnor repository master copy to the Guvnor repository.
Commit Action:
The Commit action is enabled for one or more Guvnor repository associated files that have local changes. The Commit action will write the local changes back to the associated Guvnor repository files and update the association for the new revision.
If a local change is based on an older revision of a file than is currently in the Guvnor repository (for example, someone else changed the same file), then the Commit action will ask whether you wish to overwrite the current version in the Guvnor repository with the local content. When such conflicts occur, you should use the Eclipse Guvnor version tools, along with Eclipse standard tools, to determine the differences and merge content based on the current version in the Guvnor repository.
Show History Action:
The Show History action shows a file's revision history.
Compare with Version Action:
The Compare With Version action opens a wizard that allows versions of a file to be compared for changes.
Switch to Version Action:
The Switch to Version action replaces the current version of a file with the selected version from the revision history.
Delete Action:
The Delete action removes the files in the Guvnor repository and deletes local metadata for the Guvnor repository association.
Disconnect Action:
The Disconnect action is enabled for one or more Guvnor repository associated files, and it removes local metadata for the Guvnor repository association.
Guvnor Preferences
The JBoss Developer Studio preferences for the Guvnor plug-ins allows user to set decoration preferences for local Guvnor resources to identify changes to local files.
The Guvnor preferences are set by accessing the preferences menu. Select WindowPreferencesGuvnor to access the preferences.

Chapter 5. JBoss Developer Studio and JBoss BRMS Examples

5.1. Creating a New Package

Knowledge bases are used as a central repository for knowledge packages. Knowledge packages contain the rules, facts, and process definitions that provide applications with the business logic.

Procedure 5.1. Creating a New Package

  1. Start the server if it is not already running.
  2. From the navigation panel, select Knowledge Bases and then select Create NewNew Package.
  3. Enter a name and a description for the new package and click Create Package.
The new package can be seen under Knowledge Bases by expanding the packages menu.

5.2. JBoss Central

When JBoss Developer Studio 5.0 is first started, JBoss Central is displayed in the main window of the workbench. From JBoss Central it is possible to create new projects by selecting the menu options under Create Projects. Example projects can be started by selecting the links under JBoss Quickstarts.
JBoss Central

Figure 5.1. JBoss Central


5.3. Creating a jBPM Project

Procedure 5.2. Creating a New JBDS Project

  1. From the main menu select FileNewProject.
    Select jBPMjBPM project.
  2. Enter a name for the project into the Project name: text box and click Next.

    NOTE

    JBDS provides the option to add a sample HelloWorld Process to the project. Accept this default to test the sample project in the next step.
  3. To test the project, right click the Java file that contains the main method and select Runrun asJava Application.
    The output will be displayed in the console tab.

Procedure 5.3. Add the jBPM Project to JBoss BRMS

  1. From the navigation panel, locate the sample.bpmn file.
    The sample.bpmn file is located by opening the test jBPM projectv and navigating to src/main/resources/.
  2. Right click the file and select GuvnorAdd and click Next; expand the repository displayed to locate the package the file should be added to and click Finish.
  3. View the process or rule in BRMS by logging onto the BRMS user interface.
    From the navigation panel, select Knowledge Bases and expand the package explorer to locate the package.
    Select Processes and click Open from the list of processes.

5.4. Creating a Drools Project

Procedure 5.4. Creating a New JBDS Project

  1. From the main menu, select FileNewProject.
    Select DroolsDrools Project.
  2. Enter a name for the project into the Project name: text box and click Next.

    NOTE

    JBDS provides the option to add a sample HelloWorld Rule file to the project. Accept this default to test the sample project in the next step.
  3. To test the project, right click the Java file that contains the main method and select Runrun asJava Application.
    The output will be displayed in the console tab.
  1. From the navigation panel locate the sample.bpmn or sample.drl file.
    The sample.drl file is located by opening the test drools project and navigating to src/main/rules/.
  2. Right click the file and select GuvnorAdd and click Next; expand the repository displayed to locate the package the file should be added to and click Finish.
  3. View the process or rule by logging onto the BRMS user interface.
    From the navigation panel, select Knowledge Bases and expand the package explorer to locate the package.
    Select Technical rule assets and click Open from the list of rules.

Revision History

Revision History
Revision 5.3.1-24.4002013-10-31Rüdiger Landmann
Rebuild with publican 4.0.0
Revision 5.3.1-24Tue Jun 11 2013CS Builder Robot
Built from Content Specification: 11104, Revision: 458753