3.3. 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-VERSION-deployable-generic.zip: contains the business-central.war, dashbuilder.war, and kie-server.war web applications.
  • jboss-bpmsuite-VERSION-engine.zip: supported execution engine libraries for embedding the engine into your application and other libraries needed for generic deployment.

3.3.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 Deployable for All Supported Containers row and then click Download.
  6. Also navigate to the Red Hat JBoss BPM Suite 6.3 Core Engine row and click Download to download the Red Hat JBoss BPM Suite Core Engine files.

3.3.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):


In a fresh Red Hat JBoss BPM Suite installation, you can encounter exceptions in the log similar to the following:

WARNING: Unable to instantiate EJB Asynchronous Bean. Falling back to Executors' CachedThreadPool.

The exceptions are caused by the code that failed to look up an Enterprise Java Beans object registered under a JNDI name that does not exist in Apache Tomcat. Therefore, a default implementation is used instead.

These messages are only warnings and do not have any impact on the overall functionality of the system. Setting up Transaction Manager for Red Hat JBoss Web Server 2.1 (Tomcat 7)

  1. Extract the generic deployable ZIP package you downloaded from the 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.


    $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 Core 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.


    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. These JARs are available in jboss-bpmsuite-VERSION-deployable-generic.zip and jboss-bpmsuite-VERSION-engine.zip.

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

    Additionally, download the following library and copy it into the $TOMCAT_DIR/lib/ folder: javax.security.jacc-api.jar. Add Valve configuration into TOMCAT_HOME/conf/server.xml inside the <host> element as last Valve definition:

    <Valve className="org.kie.integration.tomcat.JACCValve" />
  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

    • 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 3.1. H2 Data Source Definition


      Example 3.2. MySQL 5.5 Data Source Definition


      Example 3.3. DB2 Type 4 Data Source Definition


      Example 3.4. Oracle Data Source Definition


      Example 3.5. Microsoft SQL Server Data Source Definition

  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 -Dorg.jboss.logging.provider=jdk"

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


    The -XX:MaxPermSize=512m JVM property is valid only for JDK 6 and 7. It is not valid for JDK 8+.

    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 -Djava.security.auth.login.config=C:\apache-tomcat\webapps\business-central\WEB-INF\classes\login.config -Dbtm.root=C:\apache-tomcat -Dbitronix.tm.configuration=C:\apache-tomcat\conf\btm-config.properties -Djbpm.tsr.jndi.lookup=java:comp/env/TransactionSynchronizationRegistry" 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).


      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 the extracted jboss-bpmsuite-6.3.0.GA-engine.zip to $TOMCAT_DIR/lib/.
    3. Copy jboss-jaxb-api-VERSION.jar from $TOMCAT_DIR/webapps/business-central/WEB-INF/lib/ to $TOMCAT_DIR/lib/.
  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 property 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:

        <description>Console DS</description>
    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"/>

      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:


      Change this value to the data source defined earlier:

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

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

    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. Setting up Intelligent Process Server for Red Hat JBoss Web Server 2.0 (Tomcat 7)

After setting up Business Central, it is necessary to configure data sources for the Intelligent Process Server (kie-server) as well. Otherwise, Intelligent Process Server tries to find a data source under the JNDI jboss/datasources/ExampleDS, which is by default registered only in Red Hat JBoss EAP and not in Apache Tomcat.


Intelligent Process Server requires a data source only if the jBPM extension is enabled. This extension is enabled by default.

Intelligent Process Server needs a dedicated database, which is why it is not possible to reuse the data source registered for Business Central. To add a dedicated data source for kie-server, do the following:

  1. Copy the JAR file with the relevant database driver to $TOMCAT_DIR/lib/. If you are using an H2 database, this step has already been done during the Business Central installation.
  2. Add the data source into the resources.properties file. Note that the actual values may differ, based on the underlying database.

  3. Register a new resource in the kie-server/META-INF/context.xml:

    <Resource name="jdbc/kieserver"
              type="javax.sql.DataSource" />
  4. Update the $TOMCAT_DIR/bin/setenv.sh file. Add the following data source-related properties for kie-server:

    -Dorg.kie.server.persistence.tm=org.hibernate.service.jta.platform.internal.BitronixJtaPlatform Setting up Dashbuilder for Red Hat JBoss Web Server 2.0 (Tomcat 7)


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, “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 set up 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"/>

      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:

        <description>Dashboard Builder Datasource</description>
    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.