Wednesday, March 25, 2015

JBoss BPM Suite Quick Guide: Automating Email User Task Notifications (part 1)

Previously we went through a project where there was a bit of trouble around the completion of user tasks in a timely manner.

We showed you how to setup automated task reassignment for any task that was claimed from the group and then not completed in a timely manner.

We had the task reassigned back into the group for others to work on.

Little did we know this would not be enough to make this process project run smoothly for our users, so read on in this first part one of two articles that will lead you through setting up email notifications for your processes.

The problem

After putting this into production we noticed that it was not enough to just assume that users from a group would claim and complete tasks in a timely manner.

The issue that arose was that these users had no idea when a task was waiting for them as there were no alerts.

We need to setup an email alert to be sent to the group and/or users when a new user task is added to the group and sits unattended for a specified period of time.

The configuration

Before we can actually use the JBoss BPM Suite process designer to setup our desired email notifications, we need to make sure our server is configured to process email notifications, knows our users and knows our groups.

Within the JBoss BPM Suite we have a standard JBoss EAP server which for our purposes we will leverage with the default setup, making as few changes as possible to get you started.

Looking closer at this setup we have to make a few adjustments to the configuration we run (standalone), provide the business central component with user and group information.

There is also the issue of setting up a mail server to process the email notifications being sent by the JBoss BPM Suite. This is outside the scope of this article, but do not worry, we provide a simple SMTP java server component (covered in part 2) that can be started to test your project that will listen on the proper ports to capture sent emails.

Note that this setup will not block the process from running normally if you have no email server setup to process these notifications, you will just find errors in the JBoss BPM Suite server logs.

The changes

There are two files we will need to adjust to get the email notifications working:

  • JBoss EAP servers standalone.xml
  • JBoss BPM Suite business central components userinfo.properties

The standard standalone.xml delivered with our demo projects* have just a few system properties added to clarify for you how things are setup. There is a standard email setup already in place, it is just missing two things:

  1.  a from field with a valid email address for all sent mail from JBoss BPM Suite
  2. a system property to define what mail subsystem to use for sending mail

If you open the existing standalone.xml found and search for the mail subsystem you will need to adjust this code to look like this:

<subsystem xmlns="urn:jboss:domain:mail:1.1">
    <mail-session jndi-name="java:jboss/mail/Default" from="info@redhat.com">
        <smtp-server outbound-socket-binding-ref="mail-smtp"/>
    </mail-session>
</subsystem>

The line with jndi-name="java:jboss/mail/Default" will be missing the from=info@redhat.com", so you need to make sure this is added to allow mails to be sent.

Next you need to add a system property to let JBoss BPM Suite know which subsystem to use to send mails, so we add in the mail jndi-name for the org.kie.mail.session property. There may be other system properties in your standalone.xml file, just make sure the one here is added:

<system-properties>
    <property name="org.kie.mail.session" value="java:jboss/mail/Default"/>
</system-properties>

The second file is found inside the deployments directory of the JBoss BPM Suite server:

# The users and groups need to be made available to the business central component
# that is found inside the deployments directory, in our case we are running it in
# standalone mode, so this is the file we need to update.
#
jboss-eap-6.1/standalone/deployments/business-central.war/WEB-INF/classes/userinfo.properties

The default userinfo.properties file might or might not contain some or all of these entries here below, but you need to make sure at the very least these are in there for the example project* we are dealing with:

erics=erics@domain.com:en-UK:erics
manager=manager@domain.com:en-UK:manager:[erics]
Administrator=administrator@domain.com:en-UK:Administrator           
Administrators=administrators@domain.com:en-UK:Administrators:[Administrator]

The user is erics and the group that is assigned the tasks we want to monitor and send notifications to is manager. You must have the user Administrator and group Administrators too.

Once you have both of these files updated you are ready to start the JBoss BPM Suite and add email notifications to your user tasks.


[*In this article we will use the HR Employee Rewards demo project as a baseline, which you can also build from scratch by following the JBoss BPM Suite online workshop. If you obtain this project, follow the install instructions you will find a completed solution of what is described here.]