E-mail support in jBPM 4

Today I would like to talk about one of the many automatic activities that jBPM 4 provides out of the box: sending emails.

For those of you who have been using jBPM for a while, you may remember that jBPM 3 offered you e-mail support in the following incarnations.

• node step visible in the process diagram
• action handler event not shown in the diagram
• task notification when an actor is assigned a task
• task reminder at specific intervals after task creation

The above functions were all implemented on top of a common infrastructure. Not all of them exposed the underlying capabilities consistently, tough. Moreover, the infrastructure was not modular. The template (entity), producer (control) and session (boundary) components were mixed together. Critically, more advanced capabilities were missing.

In the latest iteration, the email feature received input from a larger and more heterogeneous group of people, consisting of the core jBPM team, one consultant from a sister company and two community members. It took some time and many a compromise to come up with a solution that everyone liked. Nonetheless, the end result was much better than any of the participants would have achieved separately, in a true open source fashion.

The design criteria were:

• Clean, concise syntax
• Customizable mail composition
• Dynamic content templates
• Composite payload: HTML and attachments
• Multiple SMTP servers with address filtering
  

The diagram below depicts the design that realizes the above requirements. Immediately following is a description of the interaction.

1. The client of the mail subsystem requests its associated mail producer to produce email messages, reading variables from the given execution. The producer contains or references a template (not shown) which specifies the recipients and the content of the message.
2. The client retrieves the (shared) mail session from the environment and hands it the produced email messages. At this point, work from the perspective of the client is done. The rest is handled by the mail session.
   
3. The mail server is configured with one or more SMTP servers, each with separate filter and transport settings.
4. A mail server only sends messages to the addresses accepted by its filter.
5. Each mail server encapsulates the mail properties required to create a javax.mail.Session and retrieve the corresponding transport.
6. The transport is responsible for ultimately delivering the messages to their recipients.
   

Both MailProducer and MailSession are interfaces, allowing for customizable mail composition and delivery. The mail subsystem provides facilities for a client to read an arbitrary mail producer from a DOM element. In turn, the mail session implementation can be changed through the existing configuration binding mechanism provided by jBPM.

For more details on the mail features, please refer to the jBPM developers guide. In a future post I will focus on the mail usage model. Talk to you soon!

jBPM 3.2.6 is out!

Delivering on our two-month timeboxed releases, I am pleased to announce jBPM 3.2.6, available for download at the usual place. This new version delivers many bug fixes (27) and updates (22) back to the community that took the time to report them.

Here is a scoop of the issues resolved over this cycle.

• Continous integration with PostgreSQL
  
• Serializable values in process variables
  
• Prevention and handling of optimistic locking exceptions
  
• API to query failed jobs
• Basic performance evaluation
• Compatibility with database schema from version 3.2.2

Bernd Ruecker of Camunda GmbH deserves a special mention for his contributions to this release. Thanks!

I hope you enjoy using this release as much as our team did producing it. Either that, or at least not spend any night on stabilization, as I did :-)

Data source configuration in jBPM 3.2

Starting from version 3.2.4, jBPM is distributed as a Java-based installer for easy product setup. The installer lets you fill in the following parameters.

1. Installation directory
2. Components to be installed (see screenshot)

• Standalone
• JBoss integration
• Optional Eclipse / JBoss AS downloads

3. Target database
4. JBoss AS directory, if you already have one


The target database selection currently includes HSQLDB, MySQL and Sybase, with PostgreSQL, Oracle and MS SQL underway. Selecting a database is as simple as clicking your choice in the appropriate screen. Configuring jBPM with the appropriate parameters for your database is slightly trickier. This post will guide you though it.

The installer will put the jBPM enterprise components in the deploy/jbpm directory of your server profile. You will find a jbpm-database-ds.xml file there, where database corresponds to your selection in the installer, of course. Let us take MySQL as example. The contents of the installed file are listed below.

<xa-datasource>
<jndi-name>JbpmDS</jndi-name>

<xa-datasource-class>
com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
</xa-datasource-class>
<xa-datasource-property name="ServerName">
localhost
</xa-datasource-property>
<xa-datasource-property name="PortNumber">
3306
</xa-datasource-property>
<xa-datasource-property name="DatabaseName">
jbpmtest
</xa-datasource-property>
<user-name>jbpmtest</user-name>
<password></password>
...
</xa-datasource>

You will probably want to edit the server name, database name, user name and password before launching JBoss AS, otherwise you will get database connectivity exceptions. The remaining settings have worked for us in our test environment and are our general recommendations. In case you want to further tune the data source, the available settings are documented in the JBoss AS configuration guide.

Apart from the data source, the installer places the JDBC driver of the target database in the deploy/jbpm/jbpm-service.sar directory, provided that the driver is freely distributable. Otherwise, you will need to obtain and install the driver yourself, according to the instructions provided in Appendix B of the aforementioned guide. Free open source database users have it easiest, which is only fair :-)

A new LAMP: Linux, Apache, (Java) Middleware and PostgreSQL

If you work in the software industry, particularly if you consume and/or provide free and open source software, you will undoubtedly have come across the LAMP acronym (otherwise, you just did). LAMP is an emblem of free software. Indeed, many web sites out there rely on this versatile software stack.

Nonetheless, for us Java devs, the P is excluding, be it PHP, Python or Perl, whereas the M generates mixed feelings. Of course, the Java platform was freed only recently, which accounts for its absence from the free software stage. Anyhow, Java is free nowadays. Wikipedia states the following about LAMP.

the combination has become popular because of its low acquisition cost and the ubiquity of its components, which come bundled with most current Linux distributions.

OpenJDK is available from the package repositories of Fedora 9 and Ubuntu 8.04. I have confirmed it can be installed as easily as Apache, MySQL or PostgreSQL in those Linux distributions and undoubtely in others as well.

What about the database? Like I said, mixed feelings there. MySQL claims to be the world's most popular open source database, whereas PostgreSQL is allegedly the world's most advanced open source database. 'Nuf said. No, really.

In recent experiences with jBPM testing, the easy setup and low maintenance requirements of MySQL have been a pleasant surprise. No doubt it is more popular. Conversely, the PostgreSQL community's ability to roll out new features (foreign keys, views, subselects, transactions and, more recently, two-phase commit) well in advance of its open source competence, makes it a distinctly compelling product.

Free software is about choice. Time for a new LAMP?

XA data sources and jBPM

One handy and often overlooked feature of jBPM 3.3 is the ability to customize the services provided by the jBPM context, and even add your own. The user guide documents the feature in Chapter 6: Configuration. Services are an abstraction layer from the operational environment and allow jBPM to run standalone or inside an EJB container.

When running inside an EJB container, the message service is bound to JMS and the scheduler service to EJB timers. Some supporting enterprise beans need to be deployed for the services to work. In the Hibernate configuration the JDBC connection properties are replaced by a server-provided data source.

When your process definition makes use of the message or the scheduler service, the JMS connection factory or the EJB timer service are enlisted as resource manager in the container-managed transaction, in addition to the jBPM data source. When more than one resource manager is enlisted in the same transaction, all resource managers are conceptually required to support XA (two-phase commit) unless the last resource commit optimization is in effect.

In JBoss AS, the JMS connection factory is XA capable and poses no problems. However, the EJB timer service relies on a data source to persist timer data. The data source is by default bound to DefaultDS, a local (as opposed to XA) data source. If the jBPM data source was also local, the transaction manager would reject the second local resource and roll back the transaction. There are at least three approaches to a solution to this problem.

1. Enable multiple resource manager enlistement
2. Associate both the EJB timer service and the jBPM persistence to a single data source
3. Make jBPM use an XA data source
   

The first two solutions require end users to modify their JBoss AS configuration. However, the aim of jBPM is to provide a seamless out-of-the-box experience. End users should not be required to alter their configuration just to get the product to work. Providing an XA data source is therefore the only viable option.

Whereas most databases provide working XA data sources, most are not as proven as the standalone JDBC driver is. All of them work in the absence of errors, but some of them do not recover properly in exceptional scenarios. The currently supported databases/drivers along with their known XA support are listed below.

HSQLDB
XA data source: no
EJB container integration not available.

MySQL
XA data source: yes
Backend does not support XA - coming in 6.0 with the Falcon storage engine.

PostgreSQL
XA data source: yes
Backend and driver support.

Sybase
XA data source: yes
Backend and driver support. Distributed transactions must be enabled in the backend.

Conclusion. EJB container integration is at the mercy of the target database. Choose carefully!

New year, new blog

After a long time of putting off blogging for next year (where next is always current plus one), I have finally came around to sit down and do it.

Rather than throwing subjective comments about technology, the software industry and everything, I want this blog to offer objective information about BPM, enterprise Java and related technologies. Of course, JBoss jBPM will be at the center.

Having the goal concisely phrased, I wish anyone reading this entry a succesful 2009.

* Xihumolpilli *