Email configuration for jBPM

Quite frequent question from users is how to send emails from within process instance. This is rather simple activity but requires bit of configuration upfront.

So lets start with application server configuration to provide JavaMail Sessions via JNDI directly to jBPM so process engine does not need to be concerned too much with infrastructure details.

In this article, WildFly 10 is used as application server and the configuration is done via jboss cli. As mail server Gmail is used as it makes it quite common choice.

Configure WildFly mail session

This is quite simple as it requires to configure socket binding and then the actual JNDI resource of mail session type:

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=jbpm-mail-smtp/:add(host=smtp.gmail.com, port=465)

/subsystem=mail/mail-session=jbpm/:add(jndi-name=java:/jbpmMailSession, from=username@gmail.com)

/subsystem=mail/mail-session=jbpm/server=smtp/:add(outbound-socket-binding-ref=jbpm-mail-smtp, ssl=true, username=username@gmail.com, password=password)

Items in bold are external references:

• host - smtp server host name
• port - smtp server port number
• JNDI name the mail session will be bound to

Items in red must be replaced with actual Gmail account details that shall be used when sending emails:

• from - address that should be valid email account
• username - account to be used when login to SMTP server
• password - account's password to be used when login to SMTP server

When starting WildFly server, you have to provide the JNDI name to be used by jBPM to find the mail session, this is given as system property:

./standalone.sh .... -Dorg.kie.mail.session=java:/jbpmMailSession

this is all that is needed from application server point of view.

Configure jBPM for sending emails

There are two email components that can be used by jBPM to send emails:

• Email service task (backed by work item handler)
• User task notifications

Both of them can rely on application server mail sessions, so configuration of the application server applies to both email capabilities.

Work item handler configuration

Email activity is based on work item mechanism so that requires work item handler to be registered for it. Work item handlers can be registered via deployment descriptor that can be done on kjar level or server level. Below screen shot illustrates the configuration of the deployment descriptor on kjar level done in workbench

what this does - it's registering org.jbpm.process.workitem.email.EmailWorkItemHandler for Email work item/service task and since it should use mail session from JNDI we need to reset the handler property so they won't get in the way (argument of the EmailWorkItemHandler constructor):

• host set to null
• port set to -1
• username set to null
• password set to null
• useTLS set to true

this is done to make sure all these values are taken from JNDI mail session of the application server.

As it was mentioned, this email registration can also be done on server level, global deployment descriptor that all kjars will inherit from. See more about deployment descriptor in the docs.

That's all from jBPM configuration point of view. 

Process with Email task

Last thing is to actually take advantage of the configured Email infrastructure so let's model most basic process that the only thing it does is sending email and completing.

Email task can be found in the left hand side panel - palette - under Service Tasks category.

Once placed on the process flow you need to provide four data input to instruct email work item handler how to compose the email message:

• From - valid email address
• To - valid email address of the recipients (to specify multiple addresses separate them with semicolon ';')
• Subject - email subject
• Body - email body (can include html)

That's all, just build and deploy it and enjoy receiving emails from your processes.