Easy Consumption of BPM Events via Public API – using the example of custom task notifications

Introduction

In BPM, it is already possible to send e-mail notifications to potential owners when new tasks are created. What can you do if this is not your standard notification mechanism and notifications for new tasks should be done via e.g. SMS or any push message service? Starting with BPM 7.31 SP17, a public API is available to consume process, task and message events via JMS. The task activation event for example, can be used to notify your users about a new BPM task via your notification mechanism.

How-to

The first step is to activate the publishing of BPM events to JMS. This needs to be done in SAP NetWeaver Administrator (NWA) /nwa/sys-config -> Services -> Galaxy Core Service (com.sap.glx.core.svc). For our task notification event, we set the property eventlog.publish.jms.usertask.activated to true. Now, in case of activation of a new task, a JMS message is created.

The second step is to create a consumer for these events. The easiest way is to access the BPM task activation event via message driven bean (MDB).  The consumer bean needs to extend the abstract class com.sap.bpm.jms.api.AbstractBPMMessageListener and add the following annotation:

@MessageDriven(activationConfig = {

@ActivationConfigProperty(propertyName = “destinationType”, propertyValue = “javax.jms.Topic”),

@ActivationConfigProperty(propertyName = “messageSelector”, propertyValue = SELECT_EVENT_USERTASK_ACTIVATED) }, mappedName = AbstractBPMMessageListener.JMS_TOPIC_NAME)

public class ConsumeBpmEventsBean extends AbstractBPMMessageListener{}   

To consume only task activation events, set the “messageSelector” property using the enum SELECT_EVENT_USERTASK_ACTIVATED provided by BPM public API.

The class AbstractBPMMessageListener provides different onBPM*Event methods that can be overwritten and are called each time the corresponding events are created. For a task notification, the method onBPMTaskEvent can be used. The bpmMessage contains event-specific information such as the task instance ID.

    @Override

    public void onBPMTaskEvent(final BPMTaskEventMessage bpmMessage) {

       URI taskInstanceId = bpmMessage.getTaskInstanceId();

      }

The task instance ID solely, might not be relevant for the notification mechanism, however, the task instance manager from BPM public API provides different methods to get details of the task, e.g. the potential owner, subject of the task or the task execution URL.

TaskInstanceManager taskInstanceManager = BPMFactory.getTaskInstanceManager();

TaskDetail taskDetail = taskInstanceManager.getTaskDetail(taskInstanceId);

Set<? extends IPrincipal> potentialOwners = taskDetail.getPotentialOwners();

String taskSubject = taskDetail.getSubject();

URL generateTaskExecutionUrl = taskInstanceManager.generateTaskExecutionUrl(taskInstanceId);

Remark on Permission

Make sure that the task details are retrieved in the context of a user who has the correct permission e.g. administrator, task administrator or potential owner. Having task details like potential owner, subject and task execution URL available, any notification mechanism can be called.

Summary

Custom implementations might require insight into the execution of business processes to either track process progress (individually and grouped) or react on changes of process or task state. BPM public API provides access to various events which occur during the life cycle when a given process or task instance reaches another state or the next step. Listening to those events enables custom applications to react accordingly.

Further Links:

BPM Documentation 7.31 SP 17