This how-to outlines the necessary steps to get jBPM 3.2 working with Tomcat and MySQL.

It has been tested with the following environments:

Tomcat 5.0.28 / 5.5.26 / 6.0.10 / 7.0.22 (see the notes at the bottom of this page)

MySQL 5.0.15

jBPM 3.2.GA and also with jBPM 3.2.1/3.2.2/3.2.3 (just some minor changes highlighted in the text below!)

1. Create schema and tables in MySQL

1.1 In this example a schema 'jbpm32' with a user 'jbossjbpm' is used.

1.2 Generate all jBPM tables using the script from the downloaded jBPM 3.2 suite, which has to be modified a bit to suite the MySQL syntax. Attached to this page is a script (jbpm.jpdl.mysql.sql) with these modifications already done - just for your convenience! If you want your users/roles information (the identity components) also from the MySQL db, use the second sql script attached here (mysql.identity.script.sql for jBPM 3.2.GA and mysql.identity.script.jbpm321.sql for jBPM 3.2.1) to set up the necessary tables and fill them with the demo values.

2. Prepare your jBPM archive

2.1 In jbpm-jpdl-3.2.GA/deploy (or jbpm-jpdl-3.2.1/deploy) run

  ant customize.console.for.tomcat

2.2 This builds a jbpm-console.war in jbpm-jpdl-3.2.GA/deploy/customized (almost) ready for deployment in TC

2.3 Change the jbpm-console.war/WEB-INF/classes/hibernate.cfg.xml to reflect the following changes:

<hibernate-configuration>
  <session-factory>

    <!-- hibernate dialect -->
    <property name="hibernate.dialect">org.hibernate.dialect.MySQLInnoDBDialect</property>

    <!-- JDBC connection properties (begin) -->
    <property name="hibernate.connection.driver_class">com.mysql.jdbc.Driver</property>
    <property name="hibernate.connection.url">jdbc:mysql://localhost:3306/jbpm32</property>
    <property name="hibernate.connection.username">jbossjbpm</property>
    <property name="hibernate.connection.password">jbossjbpm</property>
     <!-- JDBC connection properties (end) -->
    
    <property name="hibernate.cache.provider_class">org.hibernate.cache.HashtableCacheProvider</property>
    
    <!-- DataSource properties (begin) ==
    <property name="hibernate.connection.datasource">java:/JbpmDS</property>
    == DataSource properties (end) -->
    <property name="hibernate.transaction.factory_class">org.hibernate.transaction.JDBCTransactionFactory</property>
...     

(Make sure to use the hibernate.connection.driver/url attributes to connect to the db and not the hibernate.connection.datasource property. Also set hibernate.transaction.factory_class to JDBCTransactionFactory instead of the JTATransactionFactory or CMTTransactionFactory which are already in this file.)

2.4 Copy jboss-j2ee.jar (or maybe as well any jar that contains the default javax.transaction package) to jbpm-console.war/WEB-INF/lib. (Note: jboss-j2ee.jar can be found in a standard JBoss AS distribution eg. jboss-4.0.5.GA/client or in the repo)

2.4.1 For jBPM 3.2.1 and higher: Copy commons-collections.jar to jbpm-console.war/WEB-INF/lib. (Note: commons-collections.jar can be found in a standard JBoss AS distribution eg. jboss-4.0.5.GA/server/default/lib or in the repo)

2.5 Copy the jar containing the mysql jdbc driver to /$CATALINA_HOME/common/lib

2.6 Copy the adapted jbpm-console.war to /$CATALINA_HOME/webapps

+You can now give it a try and start Tomcat. You should be able to start the jbpm web application, but for now you cannot successfully log in. +

Next thing to do would be to properly configure your security realm. You could either go for the standard file based MemoryRealm and just add the jBPM specific users and roles to /$CATALINA_HOME/conf/tomcat-users.xml, OR...

3. Setup a JDBC Realm in Tomcat

3.1 Create a file jbpm-console.xml in /$CATALINA_HOME/conf/Catalina/localhost similar to

<Context>
<Realm  className="org.apache.catalina.realm.JDBCRealm" 
     driverName="com.mysql.jdbc.Driver"
     connectionURL="jdbc:mysql://localhost:3306/jbpm32"
     connectionName="jbossjbpm" 
     connectionPassword="jbossjbpm"
     userTable="JBPM_ID_USER u, JBPM_ID_MEMBERSHIP m, JBPM_ID_GROUP g" 
     userNameCol="g.TYPE_ = 'security-role' AND m.GROUP_ = g.ID_ AND m.USER_ = u.ID_ AND u.NAME_" 
     userCredCol="DISTINCT u.PASSWORD_"
     userRoleTable="JBPM_ID_USER u, JBPM_ID_MEMBERSHIP m, JBPM_ID_GROUP g" 
     roleNameCol="g.NAME_" ></Realm>
</Context>     

Now you should be able to run jBPM default web app in Tomcat and login with the username/password (eg. ernie/ernie for jBPM 3.2.GA or manager/manager for jBPM 3.2.1) from the db.

(Note: This how-to first found its way in this post, so you might find some more discussion about this there.)

4. Notes for users of Tomcat 7.x

The Sun jsf libs 1.2 (jsf-api.jar and jsf-impl.jar) need to be included in the jbpm-console.war/WEB-INF/lib directory.

5. Notes for users of Tomcat versions older than Tomcat 6.x

Notes for users of Tomcat versions older than Tomcat 6.x, such as Tomcat 5.0.28 or Tomcat 5.5.26: Tomcat 5.0.28/5.5.26 doesn't include the el.jars by default as the TC 6.0 series does, you will have to repackage el-api.jar and el-ri.jar back into jbpm-console.war/WEB-INF/lib (these files get deleted by the ant call described in step 2.1 above and can be found in the original web app jbpm-jpdl-3.2.1/deploy/jbpm-console.war/WEB-INF/lib). In addition, the included xml parses make problems as well, so you will also have to replace/delete the content in common/endorsed.

Notes for users of Tomcat 5.x and jBPM 3.2.2: The Sun jsf libs (jsf-api.jar and jsf-impl.jar) need to be included in the jbpm-console.war/WEB-INF/lib directory as well.