2.2. Generic Deployable Bundle Installation

To install Red Hat JBoss BPM Suite on Red Hat JBoss Web Server (EWS), you need to use the generic deployable package of the product.

For installation on EWS, the generic deployable package contains additional transaction manager and security libraries that are not part of Red Hat JBoss EWS.

Note that to install the generic deployable package, you need the following ZIP files:

  • jboss-bpmsuite-6.3.0.GA-deployable-generic.zip: contains the business-central.war, dashbuilder.war, and kie-server.war web applications.
  • jboss-bpmsuite-6.3.0.GA-engine.zip: supported execution engine libraries for embedding the engine into your application and other libraries needed for generic deployment.

2.2.1. Downloading Generic Deployable Package

To download the generic deployable Red Hat JBoss BPM Suite package for JBoss Web Server, do the following:

  1. Go to the Red Hat Customer Portal and log in.
  2. Click DOWNLOADS at the top of the page.
  3. From the list of products, choose Red Hat JBoss BPM Suite.
  4. From the Version drop-down menu, select version 6.3 (if not already selected).
  5. In the Software Downloads section that comes up, navigate to the Red Hat JBoss BPM Suite 6.3.0 Deployable for All Supported Containers row and then click Download.
  6. Also navigate to the Red Hat JBoss BPM Suite 6.3.0 Core Engine files row and click Download to download the Red Hat JBoss BPM Suite Core Engine files.

2.2.2. Installing Generic Deployable Package

To install the generic deployable package, you need to set up the following after you have installed the underlying platform (Red Hat JBoss WS):

2.2.2.1. Setting up Transaction Manager for Red Hat JBoss Web Server 2.1 (Tomcat 7)

  1. Extract the generic deployable ZIP package you downloaded from Red Hat Customer Portal to a temporary location. This ZIP package contains the following three web application archives: business-central.war, dashbuilder.war, and kie-server.war in an exploded format. Rename these folders to remove the .war extension.

  2. Copy these folders directly under the $TOMCAT_DIR/webapps folder.

    You should end up with three folders in an exploded format: $TOMCAT_DIR/webapps/business-central, $TOMCAT_DIR/webapps/dashbuilder, and $TOMCAT_DIR/webapps/kie-server.

    Note

    $TOMCAT_DIR stands for the home directory where your web server is located. Replace it with the actual path to your web server home directory, for example: /home/john/jboss-ews-2.1/tomcat7/.

  3. Extract the contents of the Red Hat JBoss BPM Suite Engine files archive to a temporary location from where you can copy the required libraries. This folder now contains all the core Red Hat JBoss BPM Suite libraries under the extracted folder and a lib folder.

  4. Install the transaction manager.

    Warning

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

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

    • btm-VERSION.jar
    • btm-tomcat55-lifecycle-VERSION.jar
    • jta-VERSION.jar
    • slf4j-api-VERSION.jar
    • slf4j-jdk14-VERSION.jar

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

  5. Install the driver to your database.

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

    Driver to the Embedded H2 Database

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

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

    • btm-config.properties 

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

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

      Make sure to change the values in the following definitions to match your environment.

      Example 2.2. H2 Data Source Definition

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

      Example 2.3. MySQL 5.5 Data Source Definition

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

      Example 2.4. DB2 Type 4 Data Source Definition

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

      Example 2.5. Oracle Data Source Definition

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

      Example 2.6. Microsoft SQL Server Data Source Definition

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

  7. Set up the transaction manager listener in $TOMCAT_DIR/conf/server.xml to start and stop Bitronix on container startup and shutdown:

    Add the following element as the last <Listener> element into the <Server> element: 

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

  8. Define the btm.root system property and location where Bitronix configuration file is placed:

    In $TOMCAT_DIR/bin/, create a readable setenv.sh file with the following content: 

    CATALINA_OPTS="-Xmx512M -XX:MaxPermSize=512m -Djava.security.auth.login.config=$CATALINA_HOME/webapps/business-central/WEB-INF/classes/login.config -Dbtm.root=$CATALINA_HOME -Dbitronix.tm.configuration=$CATALINA_HOME/conf/btm-config.properties -Dorg.jbpm.designer.perspective=RuleFlow -Djbpm.tsr.jndi.lookup=java:comp/env/TransactionSynchronizationRegistry"

    The property org.jbpm.designer.perspective is set to RuleFlow to allow the default perspective for the designer to be RuleFlow rather than Full. Grant the file execute permissions if applicable.

    The java.security.auth.login.config property must be set in order for the ssh clone of the Git repository to work.

    Tomcat on Microsoft Windows Systems

    On Microsoft Windows systems, replace the $CATALINA_HOME value in the content of the file with the equivalent environment variable name or use the absolute path and add the values in setenv.bat file as shown here in the following example: 

    set "CATALINA_OPTS=-Xmx512M -XX:MaxPermSize=512m -Dbtm.root=C:/Tomcat -Dbitronix.tm.configuration=C:/Tomcat/conf/btm-config.properties -Dorg.jbpm.designer.perspective=RuleFlow"

2.2.2.2. Setting up Business Central for Red Hat JBoss Web Server 2.1 (Tomcat 7)

To set up Business Central, do the following:

  1. Set up a Valve so that the Business Central web application can load the users set up in Tomcat:

    1. Define users and roles in $TOMCAT_DIR/conf/tomcat-users.xml. Note that Business Central requires users to have the roles specified as admin and/or analyst (for more information about user and role definitions, see the Tomcat 7 documentation).

      Important

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

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

      The program listing below shows an example of how these two roles would be added and how a user named bpmsadmin will be assigned these roles. 

      <role rolename="admin"/>
<role rolename="analyst" />
<user username="bpmsadmin" password="P@ssw0rd" roles="admin,analyst"/>
    2. Move (not copy) kie-tomcat-integration-VERSION.jar from $TOMCAT_DIR/webapps/business-central/WEB-INF/lib/ to $TOMCAT_DIR/lib/.
    3. Copy jboss-jaxb-api-VERSION.jar from $TOMCAT_DIR/webapps/business-central/WEB-INF/lib/ to $TOMCAT_DIR/lib/.

    4. In $TOMCAT_DIR/conf/server.xml, add the Tomcat Valve declaration in the relevant <host> element: 

      <Valve className="org.kie.integration.tomcat.JACCValve" />

  2. If you are using a data source other than the default provided by the underlying H2 database, you will need to set up persistence. If you are using the default H2 database, then you can ignore the rest of the steps in this procedure.

    In this procedure, you configure a data source with the JNDI name jdbc/myDatasource as defined in uniqueName=jdbc/jbpm in the Bitronix resources.properties file earlier (for the MySQL option).

    1. In business-central/META-INF/context.xml, replace the data source JNDI name in the <Resource> element. The uniqueName attribute refers to the resource.ds1.uniqueName property set in resources.properties: 

      <Resource name="jdbc/myDatasource" uniqueName="jdbc/jbpm" auth="Container" removeAbandoned="true" factory="bitronix.tm.resource.ResourceObjectFactory" type="javax.sql.DataSource"/>

    2. In business-central/WEB-INF/web.xml, replace the data source JNDI name in the <res-ref-name> element with your data source name: 

      <resource-ref>
  <description>Console DS</description>
  <res-ref-name>jdbc/myDatasource</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <res-auth>Container</res-auth>
</resource-ref>

    3. Change business-central/WEB-INF/classes/META-INF/persistence.xml.

      In this file, change the name of the hibernate dialect used for your database, if using a different database other than H2. The code below demonstrates the original database information for persistence.xml: 

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

      This information can be updated in the following manner (as demonstrated with MySQL database below): 

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

      The dialect for DB2 is org.hibernate.dialect.DB2Dialect, for DB2 on AS/400 is org.hibernate.dialect.DB2400Dialect, for Oracle is org.hibernate.dialect.Oracle10gDialect, and for Microsoft SQL Server is org.hibernate.dialect.SQLServerDialect.

    4. Change business-central/WEB-INF/classes/META-INF/persistence.xml file so that Red Hat JBoss BPM Suite process engine can use the new database.

      The code below demonstrates the original data source information for persistence.xml: 

      <jta-data-source>java:comp/env/jdbc/jbpm</jta-data-source>

      Change this value to the data source defined earlier: 

      <jta-data-source>java:comp/env/jdbc/myDatasource</jta-data-source>

  3. You can now start the JBoss Web Server to login to Business Central.

    1. Run startup.sh in the $TOMCAT_HOME/bin directory. 

      ./startup.sh
    2. Navigate to http://localhost:8080/business-central in a web browser.
    3. Login with the user name/password you defined earlier in tomcat-users.xml file.

2.2.2.3. Setting up Dashbuilder for Red Hat JBoss Web Server 2.0 (Tomcat 7)

Note

Before setting up Dashbuilder on Red Hat JBoss Web Server, you must ensure that you have correctly installed and started Business Central as described in Section 2.2.2.2, “Setting up Business Central for Red Hat JBoss Web Server 2.1 (Tomcat 7)”. Dashbuilder requires the history log database tables to exist, which are only provided by Business Central. If these tables are not present in the database before attempting the steps below, you may get initialization errors.

To set up Dashbuilder on Red Hat JBoss Web Server, do the following:

  1. Define users and roles in $TOMCAT_DIR/conf/tomcat-users.xml. Note that Dashbuilder requires users to have the role specified as admin and/or analyst. If you have already defined these users earlier for Business Central, you do not need to define them again.

  2. Enable single sign-on between Dashbuilder and Business Central by uncommenting the following lines in $TOMCAT_DIR/conf/server.xml file: 

    <Valve className="org.apache.catalina.authenticator.SingleSignOn" />

  3. As with Business Central setup, if you are using a database other than the default and integrated H2 database, you will need to setup persistence.

    In this procedure, you configure a data source with the JNDI name jdbc/dashbuilderDS as defined in uniqueName=jdbc/jbpm in the Bitronix resources.properties file:

    1. In dashbuilder/META-INF/context.xml, replace the data source JNDI name in the <Resource> element. The uniqueName attribute refers to the resource.ds1.uniqueName property set in resources.properties: 

      <Resource name="jdbc/dashbuilderDS" uniqueName="jdbc/jbpm" auth="Container" removeAbandoned="true" factory="bitronix.tm.resource.ResourceObjectFactory" type="javax.sql.DataSource"/>
      Note

      Depending upon your database, you may need to define some other properties here as well. For example, in an Oracle environment, this entry may look like the following listing. 

      <Resource name="jdbc/jbpm" uniqueName="jdbc/jbpm" auth="Container"  removeAbandoned="true" factory="bitronix.tm.resource.ResourceObjectFactory" type="javax.sql.DataSource" username="username" password="password"  driverClassName="oracle.jdbc.xa.client.OracleXADataSource" url="jdbc:oracle:thin:YOUR-URL:1521:YOUR-DB" maxActive="8" />

    2. In dashbuilder/WEB-INF/web.xml, add the data source JNDI name in the <res-ref-name> element with your data source name: 

      <resource-ref>
  <description>Dashboard Builder Datasource</description>
  <res-ref-name>jdbc/dashbuilderDS</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <res-auth>Container</res-auth>
</resource-ref>

    3. In dashbuilder/META-INF/context.xml, define the transaction factory: 

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

    4. Update the data source JNDI name in dashbuilder/WEB-INF/etc/hibernate.cfg.xml in the <session-factory> element: 

      <property name="connection.datasource">java:/comp/env/jdbc/dashbuilderDS</property>
  4. Restart Java Web server for these changes to take effect. Once restarted, you can navigate to Dashbuilder from within Business Central or directly at http://localhost:8080/dashbuilder.