Procedure 2.1. Specify the Repository's Location

1. Shutdown the Application Server
2. Open the components.xml file which is located in the deploy/jboss-brms.war/WEB-INF/ directory, and uncomment the repository.root.directory Key-Value attributes.

   <property name="properties">
      <key>org.drools.repository.configurator</key>
      <value>org.drools.repository.jackrabbit.JackrabbitRepositoryConfigurator</value>
      <!--  the root directory for the repo storage the directory must exist. -->
      <!--  <key>repository.root.directory</key><value>/opt/yourpath</value>  -->
   </property>
   

3. Add the desired location of the repository to the repository.root.directory Key-Value Attribute. (This directory must already exist.)

   <property name="properties">
      <key>org.drools.repository.configurator</key>
      <value>org.drools.repository.jackrabbit.JackrabbitRepositoryConfigurator</value>
      <!--  the root directory for the repo storage the directory must exist. -->
      <key>repository.root.directory</key>
      <value>/BRMSRulesRepositoryLocation</value>
   </property>
   

4. The JBoss Enterprise BRMS Platform will create a new datastore at that location if there is not already one there. To keep an existing datastore, copy the existing files to the new location before restarting the application server.
5. Restart the application server. If an existing datastore was not moved to the new location, a new datastore will be created.

Procedure 2.2. Configure an External RDBMS with the Repository Configuration Tool

1. Log on to the JBoss Enterprise BRMS Platform User Interface.
2. From the navigation panel on the left select Administration → Repository Configuration.
3. Select the RDBMS type from the Select RDBMS type: drop-down menu.
4. If JNDI is configured, check USE JNDI and enter the JNDI Name.
5. If JNDI is not configured, enter the required database information:
   • Driver
   • URL
   • User
   • Password
6. Click Generate repository config to generate the repository.xml file.
7. Click Save Configuration to download the generated repository.xml file and replace the existing repository.xml in the location specified in the components.xml file.

Procedure 2.3. Configuring a datasource for JBoss Enterprise Web Server

1. Copy the MySQL driver to tomcat6/lib/
2. Configure the datasource resources in tomcat6/conf/context.xml:

   <Resource name="jdbc/jbpmDS" auth="Container" type="javax.sql.DataSource" factory="bitronix.tm.resource.ResourceObjectFactory" uniqueName="jdbc/jbpmDS"/>
   
   <Resource name="jdbc/jbpmTasksDS" auth="Container" type="javax.sql.DataSource" factory="bitronix.tm.resource.ResourceObjectFactory" uniqueName="jdbc/jbpmTasksDS"/>
   

3. Edit the tomcat6/webapps/business-central-server.war/WEB-INF/Classes/META-INF/persistence.xml file to include the unique name from context.xml:

   		<jta-data-source>java:/comp/env/jdbc/jbpmDS</jta-data-source>  
   ...
   <property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/> 
   <property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.BTMTransactionManagerLookup" />
   

4. Edit the tomcat6/webapps/jbpm-human-task.war/WEB-INF/classes/META-INF/persistence.xml file to include the unique name from context.xml:

   <jta-data-source>java:/comp/env/jdbc/jbpmTasksDS</jta-data-source>  
   ...
   <property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/> 
   <property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.BTMTransactionManagerLookup" />
   

5. JBoss Enterprise Web Server does not include a transaction manager. The following example shows the configuration for Bitronix, and it is provided for evaluation purposes only. Bitronix can be downloaded from http://docs.codehaus.org/display/BTM/Home.

   	#file resources.properties
   	resource.ds1.className=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
   	resource.ds1.uniqueName=jdbc/jbpmDS
   	resource.ds1.minPoolSize=0
   	resource.ds1.maxPoolSize=10
   	resource.ds1.driverProperties.user=guest
   	resource.ds1.driverProperties.password=guest
   	resource.ds1.driverProperties.URL=jdbc:mysql://localhost:3306/jbpmprocess
   	resource.ds1.allowLocalTransactions=true
   
   	resource.ds2.className=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
   	resource.ds2.uniqueName=jdbc/jbpmTasksDS
   	resource.ds2.minPoolSize=0
   	resource.ds2.maxPoolSize=10
   	resource.ds2.driverProperties.user=guest
   	resource.ds2.driverProperties.password=guest
   	resource.ds2.driverProperties.URL=jdbc:mysql://localhost:3306/jbpmtasks
   	resource.ds2.allowLocalTransactions=true
   

6. To configure the Bitronix transaction manager, create a tomcat6/conf/btm-config.properties file:

   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

   Add the following line to tomcat6/conf/context.xml:

   <Transaction factory="bitronix.tm.BitronixUserTransactionObjectFactory"/>

   Add the following line to tomcat6/conf/server.xml

   <Listener className="bitronix.tm.integration.tomcat55.BTMLifecycleListener"/>

   Create a configuration properties file. On unix based systems the file should be tomcat6/setenv.sh, and on Windows systems the file should be tomcat6/setenv.bat.

   CATALINA_OPTS="-Dbtm.root=$CATALINA_HOME -Dbitronix.tm.configuration=$CATALINA_HOME/conf/btm-config.properties"

Procedure 2.4. Configuring a Datasource for JBoss Enterprise Platform 6

1. Add a directory for the database to the JBoss Enterprise Application Platform 6 directory structure. The directory should be named for the database that will be used. For instance, for a PostgreSQL database create the following structure:
   jboss-eap-6.0/modules/org/postgresql/
   For a MySQL database, create the following structure:
   jboss-eap-6.0/modules/com/mysql/
2. Download the corresponding JBDC driver for the database.
3. Create a main directory in the directory created for the database:
   jboss-eap-6.0/modules/org/postgresql/main/
   Copy the JBDC driver into the jboss-eap-6.0/modules/org/postgresql/main/ directory.
4. Create a module.xml file and save it to jboss-eap-6.0/modules/org/postgresql/main/ with the following content:

   <?xml version="1.0" encoding="UTF-8"?>
   <module xmlns="urn:jboss:module:1.0" name="org.postgresql">
   	<resources>
   		<resource-root path="postgresql-8.4-xxx.jdbc4.jar"/>
   	</resources>
   	<dependencies><module name="javax.api"/></dependencies>
   </module>

5. Edit the profile configuration file, for instance, jboss-eap-6.0/standalone/configuration/standalone.xml configured for a PostgreSQL database called jbpmDS, and a user called sa with a password sa:

   <subsystem xmlns="urn:jboss:domain:datasources:1.1">
      <datasources>
         <datasource jta="true" jndi-name="java:jboss/datasources/jbpmDS" pool-name="java:jboss/datasources/jbpmDS_Pool" enabled="true" use-java-context="true" use-ccm="true">
            <connection-url>jdbc:postgresql:mem:test;DB_CLOSE_DELAY=-1</connection-url>
            <driver-class>org.postgresql.Driver</driver-class>
            <driver>postgresql-jdbc4</driver>
            <pool>
               <min-pool-size>2</min-pool-size>
               <max-pool-size>20</max-pool-size>
               <prefill>true</prefill>
            </pool>
            <security>
               <user-name>sa</user-name>
               <password>sa</password>
            </security>
            <validation>
               <check-valid-connection-sql>SELECT 1</check-valid-connection-sql>
               <validate-on-match>false</validate-on-match>
               <background-validation>false</background-validation>
               <use-fast-fail>false</use-fast-fail>
            </validation>
         </datasource>
         <drivers>
            <driver name="postgresql-jdbc4" module="org.postgresql"/>
         </drivers>
      </datasources>
   </subsystem>

6. Edit the jboss-eap-6.0/standalone/deployments/business-central-server.war/WEB-INF/classes/META-INF/persistence.xml file and change the hibernate dialect to PostgreSQL:

   <jta-data-source>java:jboss/datasources/jbpmDS</jta-data-source>
   .
   .
   <property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect"/>

7. Edit the jboss-eap-6.0/standalone/deployments/jbpm-human-task.war/WEB-INF/classes/META-INF/persistence.xml file and change the hibernate dialect to PostgreSQL:

   <non-jta-data-source>java:jboss/datasources/jbpmDS</non-jta-data-source>
   .
   .				
   <property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect"/>
   

Procedure 2.5.  Setting up Clustering with Jackrabbit

1. Set up a JBoss Enterprise Application Platform cluster, refer to the JBoss Enterprise Application Platform 5 Clustering Guide which is located in the Administration and Configuration Guide.
2. Set up a load balancer, refer to the JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide.
3. Deploy a copy of jboss-brms.war to each node of the application server cluster $JBOSS_HOME/server/nodeX/deploy/
4. The Default configuration uses 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 other sections in this chapter for configuration instructions.
5. Each node in the cluster must have an individual workspace, version, and search index configured in the repository.xml file. Generate the repository.xml for the required database by logging in to the JBoss Enterprise BRMS user interface and selecting Administration → Repository Configuration.
6. Copy the repository.xml file to the repository location specified in the jboss-brms.war/WEB-INF/components.xml in each node of the cluster.
7. Each node in the cluster must have a unique ID, which is set in each node's copy of the repository.xml file. For instance:

   <Cluster id="01" syncDelay="2000">
      <Journal class="org.apache.jackrabbit.core.journal.DatabaseJournal">
         <param name="revision" value="${rep.home}/revision.log" />
         <param name="driver" value="javax.naming.InitialContext" />
      	<param name="url" value="brms-jdbc-ds" />
      	<param name="schema" value="mysql"/>
      </Journal>
   </Cluster>
   

8. Add the <distributable/> element as a child element of the web-app element to the jboss-brms.war/WEB-INF/web.xml file.
9. Verify the Cluster Nodes are working by logging into the JBoss Enterprise BRMS user interface. Examine the terminal output to confirm which node is handling the session. Shut down that node, after a short interval another node in the cluster should take over the session.

Procedure 2.6. Configure ModeShape

1. Run the ant installer from the ModeShape directory and specify the server profile ModeShape will be installed to.

   [localhost modeshape]$ ant
   Buildfile: /opt/BRMS/5.3.1/brms-standalone-5.3.1/modeshape/build.xml
   determine_home:
   set-web-home:
   set-as-home:
   set-soa-home:
   init:
        [echo] JBoss Home is ../jboss-as-web
   prompt:
       [input] Enter profile to install ModeShape to:  [default]
   

2. Add the user accounts admin and mailman, and assign the roles specified below. The default configuration uses text files to store the usernames, passwords, and assigned roles. The directions here assume that the authorization configuration has not been changed. If it has been changed, then add the users according to that configuration.
   1. Open the file PROFILE/conf/props/brms-users.properties in a text editor and add the users admin and mailman to this file as a new line with the syntax: username=password.

      admin=s3kr3t5
      mailman=53cur3m@1l

   2. Assign the roles specified below to the two users by opening the PROFILE/conf/props/brms-roles.properties file in a text editor and adding a new line for each user with the syntax username=role1, role2, role3.
      The admin user must be assigned the roles of JBossAdmin, HttpInvoker, user, and admin.
      The mailman user must be assigned the roles of JBossAdmin, readwrite.

      admin=JBossAdmin, HttpInvoker, user, admin
      mailman=JBossAdmin, readwrite

   3. Optionally, the passwords can be stored in encoded form instead of plain text. To do this run the following command in the application server directory (jboss-as or jboss-as-web) to create the encoded form of the password, replacing PASSWORD with the chosen password.

      [localhost]$ java -cp client/jboss-logging-spi.jar:lib/jbosssx.jar org.jboss.resource.security.SecureIdentityLoginModule PASSWORD
      Encoded password: 5f78dc15b9a559cbdf8592078de921bc

      Then replace the passwords stored in PROFILE/conf/props/brms-users.properties with the encoded versions.
3. The default configuration for Modeshape uses a database that is not suitable or supported in production environments. Before deploying into a production environment, this configuration must be changed to a supported database server.
   The default Modeshape repository configuration uses a JNDI data source — ModeShapeBRMSRepo — for data storage which is configured in the PROFILE/deploy/modeshape-brms-store-ds.xml file. Edit this file to change the data source configuration from Hypersonic to the database of your choice. This file is a standard JBoss data source configuration file.
   Refer to the Datasource Configuration chapter of the Application server documentation for details to configure JBoss data sources.
4. Edit the jboss-brms.war/WEB-INF/components.xml file to remove the Apache Jackrabbit configuration and add the ModeShape configuration.
   To remove the Apache Jackrabbit configuration, comment out the following section:

   <property name="properties">
   <key>org.drools.repository.configurator</key>
   <value>org.drools.repository.jackrabbit.JackrabbitRepositoryConfigurator</value>
   <!--  the root directory for the repo storage the directory must exist. -->
   <!--  <key>repository.root.directory</key><value>/opt/yourpath</value>  -->
   </property>

   The ModeShape configuration is commented out in the default configuration. Uncomment the configuration as shown below:

   <property name="properties">
   <key>org.drools.repository.configurator</key>
   <value>org.drools.repository.modeshape.ModeShapeRepositoryConfigurator</value>
   <key>org.modeshape.jcr.URL</key><value>jndi:jcr/local?repositoryName=jcrrepo</value>
   <key>org.drools.repository.secure.passwords</key><value>false</value>
   <key>org.drools.repository.admin.password</key><value>admin</value>
   <key>org.drools.repository.mailman.password</key><value>mailman</value>
   </property>
   

5. ModeShape requires two user accounts to exist, admin and mailman. The passwords for these accounts must be specified in the ModeShape configuration from the previous step.

   <key>org.drools.repository.secure.passwords</key><value>false</value>
   <key>org.drools.repository.admin.password</key><value>password</value>
   <key>org.drools.repository.mailman.password</key><value>password</value>

6. Restart the server.

Procedure 6.1. Change the User Interface Language

1. Edit the index.jsp file, which is located in the jboss-brms.war directory, to specify an alternative locale. The default index.jsp file uses United States English as the language.

   Example 6.1. The default index.jsp

   <%
    String redirectURL = "org.drools.guvnor.Guvnor/Guvnor.html";
    response.sendRedirect(redirectURL);
   %>
   

   To specify Japanese as the default language, edit the file as follows:

   Example 6.2. index.jsp with Japanese as the default language

   <%
    String redirectURL = "org.drools.guvnor.Guvnor/Guvnor.html?locale=ja_JP";
    response.sendRedirect(redirectURL);
   %>
   

   To specify Simplified Chinese as the default language, edit the file as follows:

   Example 6.3. index.jsp with Simplified Chinese as the default language

   <%
    String redirectURL = "org.drools.guvnor.Guvnor/Guvnor.html?locale=zh_CN";
    response.sendRedirect(redirectURL);
   %>
   

2. Edit preferences.properties

   Edit the preferences.properties file to specify the required default country and default language codes. The preferences.properties file is located in the jboss-brms.war/WEB-INF/classes/ directory. The default preferences.properties file uses United States English as the language and the United States as the default country.

   Example 6.4. preferences.properties with US defaults

   drools.defaultlanguage=en
   drools.defaultcountry=US

   To specify Japanese as the default language, edit the file as follows:

   Example 6.5. preferences.properties with Japanese defaults

   drools.defaultlanguage=ja
   drools.defaultcountry=JP

   To specify Simplified Chinese as the default language, edit the file as follows:

   Example 6.6. preferences.properties with Simplified Chinese Defaults

   drools.defaultlanguage=zh
   drools.defaultcountry=CH

3. Change the Date Format

   If multiple instances of the JBoss BRMS user interface are deployed with different languages specified, the format of the date must be changed so that each instance can correctly interpret the date. The following procedure can only be performed on new installations of JBoss Enterprise BRMS that do not include existing rules or test scenarios that include date values, as changing the format will corrupt existing date values.
   Specify the date format in preferences.properties.
   Change the date format from:

   drools.dateformat=dd-MMM-yyyy

   To:

   drools.dateformat=yyyy-MM-dd

   Note

   The change in format is only effective after the JBoss Enterprise BRMS server has been restarted.