11.7    Using the Push API to Access SAP BPM Lifecycle Events

Extending on the concepts discussed in Section 11.6, the SAP BPM API provides the facility and the flexibility to use your SAP BPM data/events in different ways. It’s possible to externally (outside SAP BPM) access the data related to process and task execution. Imagine you’ve built a custom application that needs to raise a specific alert as soon as the business process (built in SAP BPM) has reached a certain step.

To enable this feature, SAP BPM publishes different events occurring during the execution of a processes or tasks using Java Message Service (JMS). As things currently stand, you can access the published events via two mechanisms:

Each of these mechanisms will be discussed in the following sections.

Notes

For SAP BPM events to be published, all Java Enterprise Edition (JEE) services in com.sap.glx.core.svc starting with the name eventlog.publish.jms should be activated with the Custom Calculated Value of true in the SAP NetWeaver Administrator, as shown in Figure 11.30.

Setup of Services to Publish SAP BPM Events

Figure 11.30    Setup of Services to Publish SAP BPM Events

11.7.1    Accessing Events through a Message Driven Bean

With this approach, it’s possible to use an EJB DC. If you’re a Java developer, this is one of the easiest way to access the events. Following is a list of high-level steps required to consume an event using a MDB:

  1. Ensure that when creating the DC, the following dependencies are added:
    • tc/bpem/facade/ear (public part API), which is part of the BPEM-FACADE SC
    • engine.jee5.facade, which is part of the SC ENGFACADE
    • tc/je/sdo21/api, which is part of the SC ENGFACADE
  2. Create a new Java class that extends the abstract class com.sap.jms.api.AbstractBPMMessageListener.
  3. Use the annotation as indicated in the example in Listing 11.3. 
    @MessageDriven(activationConfig = {
    @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Topic"),
    @ActivationConfigProperty(propertyName = "messageSelector", propertyValue = SELECT_EVENT_PROCESS_STARTED + " OR " +SELECT_EVENT_PROCESS_COMPLETED + " OR "+ SELECT_EVENT_PROCESS_CANCELED + " OR "+ SELECT_EVENT_USERTASK_CREATED + " OR "
    +SELECT_EVENT_USERTASK_COMPLETED + " OR "+ SELECT_EVENT_USERTASK_CLAIMED + " OR "+ SELECT_EVENT_USERTASK_CANCELED + " OR "+ SELECT_EVENT_USERTASK_ACTIVATED + " OR "+ SELECT_EVENT_SERVICETASK_STARTED + " OR " + " OR "+ SELECT_EVENT_USERTASK_DELEGATED + " OR "+ SELECT_EVENT_USERTASK_DELEGATED + " OR "
    +SELECT_EVENT_SERVICETASK_COMPLETED + " OR "+ SELECT_EVENT_INTERMEDIATE_MESSAGE_TRIGGERED + " OR "
    +SELECT_EVENT_CALLACTIVITY_STARTED + " OR "+ SELECT_EVENT_CALLACTIVITY_COMPLETED) }, mappedName = AbstractBPMMessageListener.JMS_TOPIC_NAME)
    + SELECT_EVENT_CALLACTIVITY_STARTED + " OR " + SELECT_EVENT_CALLACTIVITY_COMPLETED + " OR " + SELECT_EVENT_PROCESS_SUSPENDED
    + " OR " + SELECT_EVENT_USERTASK_SUSPENDED + " OR " + SELECT_EVENT_USERTASK_IN_ERROR) }, mappedName = AbstractBPMMessageListener.JMS_TOPIC_NAME)

    Listing 11.3    Example Annotation

  4. The methods of the class created in step one can be overwritten to suit your needs. An example is given in Listing 11.4. 
@Override
public final void onBPMEvent(final BPMEventMessage bpmMessage) {
   // process bpmMessage
}
 
@Override
public void onBPMProcessEvent(final BPMProcessEventMessage bpmMessage) {
   // process bpmMessage
};
 
@Override
public void onBPMTaskEvent(final BPMTaskEventMessage bpmMessage) {
   // process bpmMessage
};

Listing 11.4    Standard Methods of the Class com.sap.jms.api.AbstractBPMMessageListener

Notes

The class BPMEventMessage used in the methods in represents an instance of an event that occurred in SAP BPM. It’s therefore possible to extract information such as type of event, date and time, and a unique key for the related entity (process or task). If you want to extract detailed data about the process or task, you can use com.sap. bpm.pm.api.ProcessInstanceManager or com.sap.bpm.tm.api.TaskInstanceManager, respectively. Furthermore, you can access the original JMS message by using the getJmsMessage method on the BPMEventMessage object.

Finally, it’s important to note that using an MDB isn’t always an option because, in some cases, more control is required for processing the events. The next alternative is to use the JMS API.

11.7.2    Accessing Events through a Java Message Service API

You can access TopicConnectionFactory and the topic from the JNDI by their names. There is plenty of information available on https://help.sap.com on how to use the JMS API. Please refer to it for more details. The aim of this section is to give you some pointers to consider when accessing SAP BPM-specific events and using the JMS API.

As a starting point, to consume the events using the JMS API, you need to retrieve an instance of the BPMJmsManager by calling com.sap.bpm.api.BPMFactory.getBPMJmsManager().

Furthermore, the SAP BPM API makes available a number of string constants that you can use to look up names and retrieve the TopicConnectionFactory and topic via the JNDI. See Table 11.6 for the constant string names to be used for each object type.

Object Constant String
javax.jms.TopicConnectionFactory com.sap.bpm.jms.api.BPMJmsManager.JMS_TOPIC_CONNECTION_FACTORY_NAME
javax.jms.Topic com.sap.bpm.jms.api.BPMJmsManager.JMS_TOPIC_NAME

Table 11.6    Instances and Their Corresponding Constant String

Furthermore, it’s also possible to retrieve the same objects listed in Table 11.6 using methods, as follows:

Lastly, it’s also possible to access the content of the JMS message by using the com.sap.bpm.jms.api.BPMJmsManager.mapJmsMessageToBPMEventMessage(Message) method. This will return an instance of the object BPMEventMessage.