BRMS Getting Started Guide

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 Downloads → Download your software → BRMS 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

   Copy to Clipboard Toggle word wrap
   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

   Copy to Clipboard Toggle word wrap
   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.

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 Downloads → Download your software → BRMS 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>
   

   Copy to Clipboard Toggle word wrap
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.

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 Downloads → Download your software → BRMS Platform → JBoss 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>
   

   Copy to Clipboard Toggle word wrap
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>

   Copy to Clipboard Toggle word wrap

   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.

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"

   Copy to Clipboard Toggle word wrap
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

   Copy to Clipboard Toggle word wrap

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.

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 Downloads → Download your software → BRMS 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>

    Copy to Clipboard Toggle word wrap
    Remove the following line from persistence.xml in both directories:

    <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>

    Copy to Clipboard Toggle word wrap
    Edit the following line to include the value update:

    <property name="hibernate.hbm2ddl.auto" value="update" />

    Copy to Clipboard Toggle word wrap
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

    Copy to Clipboard Toggle word wrap

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.

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 Administration → User 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>
   

   Copy to Clipboard Toggle word wrap

   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"/<
   

   Copy to Clipboard Toggle word wrap
5. Restart the application server.
6. Log back into the BRMS web user interface. From the navigation panel, select Administration → User 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.

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.
   

   View larger image

   

   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.

Procedure 4.2.  Configure Drools Runtime

1. From the JBoss Developer Studio menu, select Preferences.
2. Select Drools → installed 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 jBPM → installed 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.

Procedure 4.4. Configure the Server

1. Open the Drools view by selecting Window → Open Perspective → Other and select Drools and click OK.
2. Add the server view by selecting Window → Show View → Other... and select Server → Servers.
3. Open the server menu by right clicking the Servers panel and select New → Server.
4. Define the server by selecting JBoss Enterprise Middleware → JBoss 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.

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 Window → Show View → Other.
   Select Guvnor → Guvnor 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.

Procedure 5.1. Creating a New Package

1. Start the server if it is not already running.
2. Log on to the user interface at http://localhost:8080/jboss-brms/org.drools.guvnor.Guvnor/Guvnor.html
3. From the navigation panel, select Knowledge Bases and then select Create New → New Package.
4. Enter a name and a description for the new package and click Create Package.

Procedure 5.2. Creating a New JBDS Project

1. From the main menu select File → New → Project.
   Select jBPM → jBPM 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 Run → run as → Java 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 Guvnor → Add 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.

Procedure 5.4. Creating a New JBDS Project

1. From the main menu, select File → New → Project.
   Select Drools → Drools 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 Run → run as → Java 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 Guvnor → Add 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.