At work we have a running blob of code that was built by a predecessor on jBPM 3.1. It’s basically concrete and unmaintainable, but I decided to give it a good effort. First port of call was to see about upgrading to the latest, so that I could use the latest tooling for designing or editing the processes, and also to get the jbpm-console operational.

First, simply trying to drop the 3.2 jbpm-console war into the running tomcat fails wonderfully.

So, rather than outline each and every fix I had to make along the way, here’s a list of the notes I took while doing this. It was having to wade through this pile of shit that motivated me to get this blog up, something I’d meant to do for a while, as a way of returning the favour for some of the more useful tech blogs I’ve seen out there.

My Goals

Just so you know what I was trying to achieve, I wanted to upgrade a running 3.1 jbpm app to 3.2, then try and add the jbpm-console web app alongside for some better management.

Database upgrade

The documentation here is terrible. The section of the userguide on database upgrades (for 3.2) still refers to how to upgrade from 3.0 to 3.1. This is bug JBPM-1689 over in the jboss jira. But at least I found out what I was meant to do. (oh, and the script in the release notes doesn’t have ; characters at line ends, so you’ll need to edit it before trying to run it)

Compilation breakages

Where’d my code go? We were using timers extensively, though looking at some of the examples now, I don’t actually know why. Still.

• scheduler.exe.Timer -> job.Timer
• SchedulerSession -> JobSession
• saveTimer -> saveJob
• deleteTimer ->deleteJob
• timer.isDue() -> timer.getDueDate().before(new Date()))
• timer.execute() -> timer.execute(jbpmContext)

Spring and other XML config

We were using spring-modules, and had the jbpm config loaded up at runtime. So, our hibernate context, which included the links to all the jbpm hbm.xml files needed to be updated with the new Job.hbm.xml file, the new locations of the Timer, and remove some of the dead ones.

your web.xml that may have referred to the DeployServlet and UploadServlet need to use the ProcessUploadServlet now.

Your jbpm.cfg.xml needs to be updated to include the tx service (Line 5)

1
2
3
4
5
6
7
8

  <jbpm-context>
    <service name="persistence" factory="org.jbpm.persistence.db.DbPersistenceServiceFactory" />
    <service name="message" factory="org.jbpm.msg.db.DbMessageServiceFactory" />
    <service name="scheduler" factory="org.jbpm.scheduler.db.DbSchedulerServiceFactory" />
    <service name="tx" factory="org.jbpm.tx.TxServiceFactory" />
    <service name="logging" factory="org.jbpm.logging.db.DbLoggingServiceFactory" />
    <service name="authentication" factory="org.jbpm.security.authentication.DefaultAuthenticationServiceFactory" />
  </jbpm-context>

At this point you should have your existing jBPM app running with the 3.2 jars, against a 3.2 db. yay.

Making jbpm-console play with others

At this point you can actually deploy the jbpm-console.war into your container (I’m using tomcat) and it will load up, and give you a login and everything. (Once you sort out jar hell. I had to copy plenty of jars from my webapp to the jbpm-console lib folder, and then add the extra ones that jbpm needed. This is a straightforward, if tedious game of adding jars until you don’t get ClassNotFoundException anymore. (antlr, commons-logging, commons-collections, hibernate, jsf, asm, cglib, bsh, dom4j, jta, and a jdbc driver)

Once it’s unpacked, you need to edit the WEB-INF\classes\hibernate.cfg.xml file to match the connection used in your main webapp.

And now, even more importantly, you need to turn off the job runner that’s included (for god knows what reason) in the console. Edit the web.xml file to remove/comment out the following…

    <!-- Job executor launcher (begin) ==>
Turn this off so that your app doesn't clash with this one picking up Jobs/Timers
    <listener>
        <description>
            Starts the job executor on servlet context initialization and stops it on 
            servlet context destruction.
        </description>
        <listener-class>org.jbpm.web.JobExecutorLauncher</listener-class>
    </listener>
    == Job executor launcher (end) -->

Note: You can still use the console to signal tokens and so forth, this doesn’t stop that, it just stops it from picking up jobs.

Usernames and login

Running on tomcat there were some issues where I couldn’t actually login to the console. http://wiki.jboss.org/wiki/JbpmOnTomcat has some words on this, but what I found was simplest was to edit the jbpm-console.war::web.xml some more. My tomcat app was already using a couple of usernames and passwords, so I just told jbpm-console to use them. The <security-constraint> section needs to use a role (<role-name>) that’s already in your tomcat-users.xml file, and the roles listed in <security-roles> need to match as well. You can also take the approach they recommend and set up the ID tables, and add all sorts of other users and stuff, but some of that seems to be just so that the _examples_ run, whereas I was trying to retrofit the jbpm-console and the 3.2 code to an existing app.

I’m almost certain that this will _still_ not cover all the pain _you_ will go through, but hopefully it helps a bit.

I’ve still not got to actually using the 3.2 designer to make changes to this chunk of legacy yet, but hey, running the latest version sure seems like it should help. And now we have the jbpm-console giving us a bit more control of things when processes go astray.