Notification of Failed Instances

I’ve recently seen questions from several different sources where individuals wanted to understand their options for being notified of failed BPD instances in IBM BPM.  It turns out this feature has existed in BPDs since they were first introduced in Teamworks 5.0, but it seems many people don’t know how to leverage it.  Lets fix that.

Step One – Task Notification

Likely you already know how to get notified when a task is created and assigned to either you or a group you belong to.  However lets review and make sure we are all on the same page.  To make this work, do the following – (note: this assumes you are in IBM BPM 8.x, but the only thing that changes for other environment is the location of these items)

1. Login to the Portal for BPM instance you are targeting.
2. Click on your name in the upper right hand corner.
3. Select “User Profile”
4. Make sure you have an e-mail address set.  If you do not just click on it to edit.
5. Check the check boxes for task notification
6. Click Update.

Now send yourself a task.  Hopefully within a few seconds you get an e-mail notification as well.  If so, go to Step Three, otherwise, check out Step Two.

Step Two – Troubleshoot SMTP server

If you got an e-mail go on to step 3.  In my experience, most non production environments don’t have their SMTP server configured properly and therefore no e-mail is sent.  Lets fix that.  Please do the following –

1. Determine the address of an SMTP server that you can use that does not require a login.  (This may be a blocker for some people, but there are any number of SMTP servers you can run on Linux or Windows locally).
2. Create a file called something like 105SMTP.xml and put the the text below into the file (Sorry couldn’t get this in line and keep the numbering)
3. Upload this file to your server and put it in the directory <bpm-install>/profiles/<target profile>/config/cells/<target cell>/nodes/<target-node>/server/<target-server>/process-center/config
4. Restart the server.
5. Retest the task e-mail scenario.

Text for file (replace “localhost” with your SMTP Server) –

<properties>
 <server merge="mergeChildren">
 <email merge="mergeChildren">
 <smtp-server merge="replace">localhost</smtp-server>
 </email>
 </server>
</properties>

Notes:

• You can see your current setting for smtp-server in the TeamworksConfiguration.running.xml file.
• If you are in an ND install I likely have told you to do the wrong thing and you need to modify the DManager and synch nodes, but I’ll leave that to the WAS experts.

Step Three – Setup Notification User

Now that your server can send user’s e-mails, you are ready to tell it to send you the task/e-mail if an instance fails.  Realistically you likely want some sort of generic user that IT in general can be added to, but lets assume here you are a small shop and having to do this just on your own.  We want to create another XML file.  Lets call this one 110FailureUser.xml.  The content will be –

<properties>
 <event-manager merge="mergeChildren">
   <notify-error merge="replace">apaier</notify-error>
 </event-manager>
</properties>

Obviously, replace “apaier” with the correct user name.  If you had to do Step Two above the next steps will be familiar (and the same notes apply to this)

1. Upload this file to your server and put it in the directory <bpm-install>/profiles/<target profile>/config/cells/<target cell>/nodes/<target-node>/server/<target-server>/process-center/config
2. Restart the server.

Step Four – Test failure scenario

This setting, as you may have determined from the context, creates a task for a specific user when anything fails in BPM’s event manager.  This means tasks will be created for any unhanded exceptions that are raised to a BPD, or for any UCA failures.

The easiest way to test this is to simply create a BPD that assigns the first task to you. In that task I usually put a very simple coach (so I can be sure the task exists) with an OK button that goes to a server script that attempts to assign a value to a variable that doesn’t exist –

tw.local.nonExistentVariable = 'Bob';

This way when I hit “OK” a exception gets thrown.  Now run an instance of this BPD and hit “OK”.  Shortly you should get a new failure notification in your inbox.  I also tested this with the “Error” end point in a service and that works as well.

Conclusion

Hopefully you now are able to be significantly more aware of BPD instances that fail due to things like technical outages, where fixing the underlying problem and restarting the BPD instance will allow things to continue forward properly.  Of course you will also be notified of failures due to bad code.  Hopefully that is a very rare occurrence for you.