Chapter 16. Email support

This chapter describes the out-of-the-box email support in jBPM jPDL.

16.1. Mail in jPDL

There are four ways of specifying when emails should be sent from a process.

16.1.1. Mail action

A mail action can be used when the sending of this email should not be shown as a node in the process graph.

Anywhere you are allowed to specify actions in the process, you can specify a mail action like this:

<mail actors="#{president}" subject="readmylips" text="nomoretaxes" />

The subject and text attributes can also be specified as an element like this:

<mail actors="#{president}" >
  <subject>readmylips</subject>
  <text>nomoretaxes</text>
</mail>
      

Each of the fields can contain JSF like expressions. For example:

<mail to='#{initiator}' subject='websale' text='your websale of #{quantity} #{item} was approved' />

For more information about expressions, see Section 18.3, “Expressions”.

There are two attribute to specify recipients: actors and to. The to attribute should resolve to a semicolon separated list of email addresses. The actors attribute should resolve to a semicolon separated list of actorIds. Those actorIds will be resolved to email addresses with by means of address resolving.

<mail to='admin@mycompany.com' subject='urgent' text='the mailserver is down :-)' />

For more about how to specify recipients, see Section 16.3, “Specifying mail recipients”

Mails can be defined in templates and in the process you can overwrite properties of the templates like this:

<mail template='sillystatement' actors="#{president}" />

More about templates can be found in Section 16.4, “Mail templates”

16.1.2. Mail node

Just the same as with mail actions, sending of an email can also be modelled as a node. In that case, the runtime behaviour is just the same, but the email will show up as a node in the process graph.

The attributes and elements supported by mail nodes are exactly the same as with the mail actions.

<mail-node name="send email" to="#{president}" subject="readmylips" text="nomoretaxes">
  <transition to="the next node" />
</mail-node>

Mail nodes should have exactly one leaving transition.

16.1.3. Task assign mails

A notification email can be send when a task gets assigned to an actor. Just use the notify="yes" attribute on a task like this:

<task-node name='a'>
  <task name='laundry' swimlane="grandma" notify='yes' />
  <transition to='b' />
</task-node>

Setting notify to yes, true or on will cause jBPM to send an email to the actor that will be assigned to this task. The email is based on a template (see Section 16.4, “Mail templates”) and contains a link to the task page of the web application.

16.1.4. Task reminder mails

Similarly as with assignments, emails can be send as a task reminder. The reminder element in jPDL is based upon the timer. The most common attributes will be the duedate and the repeat. The only difference is that no action has to be specified.

<task-node name='a'>
  <task name='laundry' swimlane="grandma" notify='yes'>
    <reminder duedate="2 business days" repeat="2 business hours"/>
  </task>
  <transition to='b' />
</task-node>

16.2. Expressions in mails

The fields to, recipients, subject and text can contain JSF-like expressions. For more information about expressions, see Section 18.3, “Expressions”

The variables in the expressions can be : swimlanes, process variables, transient variables beans configured in the jbpm.cfg.xml, ...

These expressions can be combined with the address resolving that is explained later in this chapter. For example, suppose that you have a swimlane called president in your process, then look at the following mail specification:

<mail actors="#{president}" subject="readmylips" text="nomoretaxes" />

That will send an email to to the person that acts as the president for that perticular process execution.

16.3. Specifying mail recipients

16.3.1. Multiple recipients

In the actors and to fields, multiple recipients can be separated with a semi colon (;) or a colon (:).

16.3.2. Address resolving

In all of jBPM, actors are referenced by actorId's. This is a string that servers as the identifier of the process participant. An address resolver translates actorId's into email addresses.

Use the attribute actors in case you want to apply address resolving and use the attribute to in case you are specifying email addresses directly and don't want to apply address resolving.

An address resolver should implement the following interface:

public interface AddressResolver extends Serializable {
  Object resolveAddress(String actorId);
}

An address resolver should return 1 of 3 types: a String, a Collection of Strings or an array of Strings. All strings should represent email addresses for the given actorId.

The address resolver implementation should be a bean configured in the jbpm.cfg.xml with name jbpm.mail.address.resolver like this:

<jbpm-configuration>
  ...
  <bean name='jbpm.mail.address.resolver' class='org.jbpm.identity.mail.IdentityAddressResolver' singleton='true' />
</jbpm-configuration>
      

The identity component of jBPM includes an address resolver. That address resolver will look for the User of the given actorId. If the user exists, the user's email is returned, otherwise null. More on the identity component can be found in Section 11.11, “The identity component”.

16.4. Mail templates

Instead of specifying mails in the processdefinition.xml, mails can be specified in a template file. When a template is used, each of the fields can still be overwritten in the processdefinition.xml. The mail templates should be specified in an XML file like this:

<mail-templates>

  <variable name="BaseTaskListURL" value="http://localhost:8080/jbpm/task?id=" />

  <mail-template name='task-assign'>
    <actors>#{taskInstance.actorId}</actors>
    <subject>Task '#{taskInstance.name}'</subject>
    <text><![CDATA[Hi,
Task '#{taskInstance.name}' has been assigned to you.
Go for it: #{BaseTaskListURL}#{taskInstance.id}
Thanks.
---powered by JBoss jBPM---]]></text>
  </mail-template>

  <mail-template name='task-reminder'>
    <actors>#{taskInstance.actorId}</actors>
    <subject>Task '#{taskInstance.name}' !</subject>
    <text><![CDATA[Hey,
Don't forget about #{BaseTaskListURL}#{taskInstance.id} 
Get going !
---powered by JBoss jBPM---]]></text>
  </mail-template>

</mail-templates>    
    

As you can see in this example (BaseTaskListURL), extra variables can be defined in the mail templates that will be availble in the expressions.

The resource that contains the templates should be configured in the jbpm.cfg.xml like this:

<jbpm-configuration>
  ...
  <string name="resource.mail.templates" value="jbpm.mail.templates.xml" />
</jbpm-configuration>

16.5. Mail server configuration

The simplest way to configure the mail server is with the configuration property jbpm.mail.smtp.host in the jbpm.cfg.xml like this:

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

Alternatively, when more properties need to be specified, a resource reference to a properties file can be given with the key '' like this:

<jbpm-configuration>
  ...
  <string name='resource.mail.properties' value='jbpm.mail.properties' />
</jbpm-configuration>

16.6. Customizing mail support

All the mail support in jBPM is centralized in one class: org.jbpm.mail.Mail This is an ActionHandler implementation. Whenever an mail is specified in the process xml, this will result in a delegation to the mail class. It is possible to inherit from the Mail class and customize certain behaviour for your perticular needs. To configure your class to be used for mail delegations, specify a 'mail.class.name' configuration string in the jbpm.cfg.xml like this:

<jbpm-configuration>
  ...
  <string name='mail.class.name' value='com.your.specific.CustomMail' />
</jbpm-configuration>

16.7. Mail server

If you need a mailserver that is easy to install, checkout JBossMail Server or Apache James