JBPM : how to manage mail delivery from your processes

This tutorial has been written for an old version of jBPM which is now deprecated.

If you want to get started quickly with jBPM, we recommend the following quickstarts:

Almost every workflow needs a notification of the process activity. Sending a mail from JBoss jbpm is not at all complicated. The first thing to do is telling jbpm which mail server will be used to send mail.

Pickup the jbpm.cfg.xml file and add a line with the proper smtp configuration:

  <string name="jbpm.mail.smtp.host" value="localhost" />

Remember that if you want jbpm to read this file – and override the basic jbpm configuration – you have to put it in the classpath : for example in a web application the simplest way is putting this file (along with processDefinition.xml) in the WEB-INF/classes folder.

Ok. Basically there are 3 ways to send a mail from Jbpm:

1) Quick way: add Mail Action to your process definition:

If for some reasons you don’t want to show in your process graph the mail action
this is your bet.This is the simplest form of mail:

<mail to=’admin@acme.com’ subject=’mail subject’ text=’this is the body of the mail’ />

You can as well use JSF expressions

<mail to=’#{initiator}’ subject=’information’ text=’The following product #{product} was requested’ />

In this case the value of the JSF expression is matched against ContextInstance’s variables

In the next tutorials we’ll see how to unleash the power of jbpm with JBoss SEAM environment.
Because of the integration between jBPM and JBoss SEAM, all of your backed beans, EJB’s and other one-kind-of-stuff becomes available right inside of your process definition! For the moment : stay tuned !

2) Show the node to the world: Use a Mail Node

If you want that the Mail process is visible in your process graph then you can model it as a mail node. Simply drag a Mail Node from your JBPM eclipse plugin and configure the appropriate variables:
jboss jbpm

   <mail-node name="SendMail"
         subject='Ticket Opened N.#  {TicketId}             
Priority : #{priority}'>
              Refer to: #{manager} 
              Text: #{textCR}
    <transition to="TaskToBeDone"></transition>

Again here, the value of the JSF expression is searched from the ContextInstance’s variables

3) The lazy way: sending a mail automatically when a Task is assigned

Another choice is letting jbpm send a mail wherever a task is assigned. This is the typical scenario when you’re designing a trouble ticket system. In this case all you have to do is adding the “notify=’yes'” attribute to your task

  <task-node name=”Assigned”>
<task name=”TaskAssigned” notify=’yes’>

I said the lazy way, as a matter of fact it’s quite simple to send mail this way..but…there’s a little price to pay, that is you have to instruct jbpm to use templates.
Recall your jbpm.cfg.xml file and add a line which describe where is the email template:

 <string name="jbpm.mail.smtp.host" value="mysmtp-host" />
 <string name="resource.mail.templates" 
         value="jbpm.mail.templates.xml" /> 

A mail template file is simply a file which contains templates for all kind of events, in our case we need to define a mail template for the “task-assign” event:

  <variable name="BaseTaskListURL" 


=" />
  <mail-template name='task-assign'>
    <subject>Task '#{taskInstance.name}'</subject>
    Task '#{taskInstance.name}' has been assigned to you.
    Go for it: #{BaseTaskListURL}#{taskInstance.id}

---powered by JBoss jBPM---]]></text>

The JSF expressions in the template are built-in variables from your process, so you don’t need to worry about adding to the Context instance anything.

Yes but actorId is not an email address !

That’s right: actorId is a string that jbpm usese as the identifier of the process participant.
In order to translate the actor id into an email address you need an Address Resolver.

Don’t be scared we’re almost done: take again the jbpm.cfg.xml

Add a last line:

<bean name='jbpm.mail.address.resolver' 
      singleton='true' />

Now add into your project a class which translate the actorId into the email address

public class CustomAddressResolver implements AddressResolver {

    public Object resolveAddress(String actorId) {
      return actorId+"@acme.com";

So actorId is injected in the method and actorId+”@acme.com” is the mail address.