Generating events from a BPMN process (Old)

Before a Process Application can generate events for Monitor, it must be instructed that it can communicate with Monitor. This is achieved through the Process Application settings in a process application:

Once this change has been made, when either a new snapshot is deployed or an update of the tracking definitions is performed, the generated Monitor Model EAR will be deployed to the Process Server.

The name of the generated application will be:

bmon_<ProcessAppSynonym>_Main

A BPD in a Process Application can emit events. It does this by building and sending event messages to a JMS queue.

The identity and details of the queue can be found in JNDI at:

jms/com.ibm.lombardi/EventEmissionQueue

An instance of this resource is created when a Process Server profile is built. It's default WAS resource name is LombardiEventEmissionQueue which resolves to an SIBus queue name of LombardiEventEmitterInputQueue.

There must also be a a JMS Queue Connection factory found at JNDI:

jms/com.ibm.lombardi/EventEmissionQueueFactory

An instance of this resource is created when a Process Server profile is built. Its default resource name is LombardiEventEmissionQCF. This points to an SI Bus called "MONITOR.<cellname>.Bus"

By default, Process Center does not have the event emission resources defined to it. However, if the JNDI resources are defined, it will start using them.

In summary, these resources are needed:

  • jms/com.ibm.lombardi/EventEmissionQueueFactory – A Queue Connection Factory
  • jms/com.ibm.lombardi/EventEmissionQueue – A Queue
Resource Type Value
LombardiEventEmissionQCF JMS Queue Connection Factory jms/com.ibm.lombardi/EventEmissionQueueFactory
LombardiEventEmissionQueue JMS Queue jms/com.ibm.lombardi/EventEmissionQueue

It is important to take a pause here and fully understand the story so far. In my experience, it is important to understand the architecture in order to be fully successful. What we have is that IBM BPM generates messages that are written to an SI Bus queue. The content of these messages are XML documents. It is here that IBM BPM ends its part of the Monitor interaction. At this point, the events have not made their way to monitor and merely reside in a queue. In the next part we will see how the messages are consumed by Monitor but before going there we have one more thought.

What if Monitor is not installed on the same cell or machine as IBM BPM? We will shortly see that Monitor has to be able to read the messages from the queue and if Monitor is remote we seem to have a problem as a remote machine can't read a queue that is local to IBM BPM. The solution to this comes from the IBM WAS SI Bus technology. SI Bus has the concept of "Foreign Connections". This means that we can define a network link from the WAS server hosting IBM BPM to the remote WAS server hosting Monitor.

From BPM's perspective, it continues to think that it is writing messages to a named queue and from Monitor's perspective, it thinks it is reading from a named queue but WAS is managing the movement of messages from WAS 1 to WAS 2.

Mechanically, the way we achieve this is through the SI Bus notion called the "foreign bus connection".

The IBM_BPM_EMITTER_SERVICE application

The messages sent to the JMS queue by BPM are (obviously) written to the target queue and are also not in a format that Monitor can directly consume. IBM has supplied an application called "IBM_BPM_EMITTER_SERVICE" that watches a JMS queue for such messages and, when they arrive, formats them for Monitor and delivers them to Monitor. This application should be installed on a machine which is part of the Monitor environment and which can also read from the BPM written queue. Since 8.5 of BPM can't co-exist on the same cell as Monitor, we normally set up a cross cell queuing environment where BPM writes the message to a queue which is actually remote from BPM. The message then ends up on the machine hosting Monitor which is where the IBM_BPM_EMITTER_SERVICE will be installed.

The application uses three WAS level JMS resource definitions:

  • jms/com.ibm.lombardi/JMSEmitterInputQueueFactory
    • WAS Resource Name – LombardiEventEmitterInputQCF
    • Points to MONITOR..Bus
  • jms/com.ibm.lombardi/JMSEmitterInput
    • WAS Resource Name – LombardiEventEmitterInputQueue
    • Points to SIBus Queue: LombardiEventEmitterInputQueue
  • jms/com.ibm.lombardi/JMSEmitterInputActivationSpec
    • WAS Resource Name – LombardiEventEmitterInputAS

To install the IBM_BPM_EMITTER_SERVICE application, a wsadmin command has been supplied called "wbmDeployBPMEmitterService":

AdminTask.wbmDeployBPMEmitterService(['-cluster', '<clustername>'])
AdminConfig.save()

eg.

AdminTask.wbmDeployBPMEmitterService(['-cluster', 'SingleCluster'])
AdminConfig.save()

Diagnosing problems

If when you run a process and the data from that process does not show as instance data within a model, obviously, data is not moving from the process to monitor. Here is a check-list of items that can be checked.

BPM side definitions

Within the IBM BPM side of the house we have the following JMS definitions:

  • jms/com.ibm.lombardi/EventEmissionQueueFactory – A Queue Connection Factory
  • jms/com.ibm.lombardi/EventEmissionQueue – A Queue

Monitor side definitions

The following JMS definitions:

  • jms/com.ibm.lombardi/JMSEmitterInputQueueFactory
    • WAS Resource Name – LombardiEventEmitterInputQCF
    • Points to MONITOR..Bus
  • jms/com.ibm.lombardi/JMSEmitterInput
    • WAS Resource Name – LombardiEventEmitterInputQueue
    • Points to SIBus Queue: LombardiEventEmitterInputQueue
  • jms/com.ibm.lombardi/JMSEmitterInputActivationSpec
    • WAS Resource Name – LombardiEventEmitterInputAS

Configuring CEI on BPM

AdminTask.wbmDeployCEIEventService('[-busMember [-cluster <clusterName> -datasourceJndiName \<jndiName\> -datasourceAuthAlias \<authAlias\> -databaseSchema \<schemaName\> -createTables true] -eventService [-cluster \<clusterName\>] -jmsAuthAlias [-user \<userName\> -password \<password\>]]')

for example

AdminTask.wbmDeployCEIEventService('[-busMember [-cluster SingleCluster -datasourceJndiName jdbc/CEI -datasourceAuthAlias BPM\_DB\_ALIAS -databaseSchema db2admin -createTables true] -eventService [-cluster SingleCluster] -jmsAuthAlias [-user admin -password admin]]')

AdminConfig.save()

Notes:

It may be that the datasourceJndiName has to be a new unique entry

Configuring for remote Monitor ↔ BPM

In many cases, the Process Servers running IBM BPM will be separate from the server running Monitor. Because of this, the monitoring events in the form of JMS messages will have to be remotely "shipped" from a queue on IBM BPM to a queue on the Monitor server.

Collect the following:

Property BPM Monitor
Host Name localhost localhost
SOAP Port 8879 8885
WAS Admin Userid cadmin admin
WAS Admin Password password admin
Link Userid monlink monlink
Link Password password password
Cluster Name SingleCluster

WBM provides scripts and sample properties files to assist in setting this up.

Create a userid called “admin” (if it doesn't already exist) on both servers.

A properties file was created that contained the following (a template for such can be found at <Root>/scripts.wbm/crossCell/configRemoteMonitorBus.props):

SECURE\_CONFIGURATION=true
LOCAL\_WAS\_HOST=localhost
LOCAL\_WAS\_PORT=8882
LOCAL\_WAS\_USERID=admin
LOCAL\_WAS\_PASSWORD=admin
LOCAL\_WAS\_MESSAGING\_ENGINE=win7-x64Node03.server1-MONITOR.win7-x64Node03Cell.Bus
REMOTE\_WAS\_HOST=localhost
REMOTE\_WAS\_PORT=8880
REMOTE\_WAS\_USERID=admin
REMOTE\_WAS\_PASSWORD=admin
REMOTE\_WAS\_BUS\_USERID=admin
REMOTE\_WAS\_BUS\_PASSWORD=admin
LINK\_USERID=admin
LINK\_USERID\_REMOTE\_PASSWORD=admin
LINK\_USERID\_LOCAL\_PASSWORD=admin
REMOTE\_WAS\_ME\_NODE=win7-x64Node01
REMOTE\_WAS\_ME\_SERVER=server1
\#REMOTE\_WAS\_ME\_CLUSTER=
REMOTE\_WAS\_ME\_STORE=default

Next, the command "configRemoteMonitorBus.bat -props <fileName>" was executed.

The servers were then restarted.

At this point I gave up … not because it was broken but because I opted instead for augmenting my BPM server with WBM.

New instructions

Configure Server to Server SSL

Start both BPM and CEI

Login to WAS Admin Console

Go to

Security > SSL certificate and key management > (Related Items) Key stores and certificates

Select NodeDefaultTrustStore

> (Additional Properties) Signer Certificates

Click Retrieve from port

Enter details

Click OK to add the new entry

Go to Security > SSL certificate and key management > manage endpoint security configurations

Realm

defaultWIMFileBasedRealm

Results after execution:

C:\IBM\WebSphere80\AppServer\scripts.wbm\crossCell>configRemoteMonitorBus.bat -props configRemoteMonitorBus.props BM WebSphere Application Server, Release 8.0 ava EE Application Client Tool opyright IBM Corp., 1997-2009 SCL0012I: Processing command line arguments. SCL0013I: Initializing the Java EE Application Client Environment. 12/29/13 10:09:54:570 CST] 00000000 W UOW=null source=com.ibm.ws.ssl.config.SSLConfig org=IBM prod=WebSphere component=Application Server thread=[P=394289:O=0:CT] CWPKI0041W: One or more key stores are using the default password. SCL0035I: Initialization of the Java EE Application Client Environment has completed. SCL0014I: Invoking the Application Client class com.ibm.wbimonitor.sib.configassist.Launcher This utility will create a foreign bus link between the Monitor bus and a remote cell Reading properties from file configRemoteMonitorBus.props Creating remote Bus MONITOR.PCCell1.Bus Adding application server Node1 : SingleClusterMember1 to the bus Creating the foreign buses Creating the foreign bus links Saving the configuration changes Saved You must restart both application servers for this change to take effect C:\IBM\WebSphere80\AppServer\scripts.wbm\crossCell>

After execution, the following resource changes will be found:

On BPM

|| |Resource Name|Resource Type|Example| |MonitorBusAuth|J2C authentication data|cadmin| |MonitorBusAuthLink|J2C authentication data|monlink| |MONITOR.<Cell>.Bus|SI Bus|MONITOR.PCell1.Bus| |MONITOR.<MonCell>.Bus|Foreign SI Bus Link|MONITOR.win7-x64Node01Cell.bus|

On Monitor

|| |Resource Name|Resource Type| |||

See also:


Event data format

The format of the event data written to the JMS queue by IBPM's BPDs is an XML document. This data is well documented in a number of detailed articles in the IBM BPM InfoCenter.

Here is an example of an event message:

<?xml version="1.0" encoding="UTF-8"?>
<mon:monitorEvent mon:id="R7aa8b5a191e031792162189"
  xmlns:bpmn="http://schema.omg.org/spec/BPMN/2.0"
  xmlns:bpmnx="http://www.ibm.com/xmlns/bpmnx/20100524/BusinessMonitoring"
  xmlns:ibm="http://www.ibm.com/xmlns/prod/websphere/monitoring/7.5/extensions"
  xmlns:mon="http://www.ibm.com/xmlns/prod/websphere/monitoring/7.5"
  xmlns:wle="http://www.ibm.com/xmlns/prod/websphere/lombardi/7.5"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <mon:eventPointData>
    <mon:kind mon:version="2010-11-11">bpmnx:PROCESS_STARTED</mon:kind>
    <mon:time mon:of="occurrence">2011-06-30T12:21:16.728-05:00</mon:time>
    <ibm:sequenceId>0000000002</ibm:sequenceId>
    <mon:model mon:id="f4396aed-63c7-4da9-b66d-bcc051c7dd41"
            mon:type="bpmn:process"
mon:version="2064.a3ac4487-a8f3-47ee-9bfd-
51491d944d6T">
            <mon:name>Sale</mon:name>
            <mon:instance mon:id="653">
                <mon:state>Active</mon:state>
            </mon:instance>
        </mon:model>
        <mon:model mon:id="68c2430a-bc66-4460-8e1a-df27cbed7706"
            mon:type="wle:processApplication" mon:version="2064.a3ac4487-a8f3-47ee-9bfd-251491d944d6T">
            <mon:name>Mon1</mon:name>
            <mon:documentation/>
        </mon:model>
        <mon:correlation>
            <mon:ancestor mon:id="f4396aed-63c7-4da9-b66d-bcc051c7dd41.2064.a3ac4487-a8f3-47ee-9bfd-251491d944d6T.653"/>
            <wle:starting-process-instance>f4396aed-63c7-4da9-b66d-bcc051c7dd41.2064.a3ac4487-a8f3-47ee-9bfd-251491d944d6T.653</wle:starting-process-instance>
        </mon:correlation>
    </mon:eventPointData>
</mon:monitorEvent>

At a high level, it is composed of:

  • mon:monitorEvent – The root element of the event.

mon:eventPointData – The details of the event. There is only one of these per event.

mon:kind – Defines the kind of event

mon:time – The time the event was generated

ibm:sequenceId -??

mon:model – An executable model element

mon:instance

mon:correlation

mon:applicationData

wle:tracking-point

wle:kpi-data

wle:tracked-field

The monitoringEvent/eventPointData/kind is a critical entry. It defines the kind of the event that is received. The options include:

bpmnx:PROCESS_STARTED An instance of a process has been started. The models supplied include: type=bpmnProcess type=wle:processApplication
bpmnx:PROCESS_COMPLETED An instance of a process has completed
bpmnx:PROCESS_TERMINATED An instance of a process has terminated
bpmnx:PROCESS_DELETED An instance of a process has been deleted
bpmnx:PROCESS_FAILED An instance of a process has failed
bpmnx:ACTIVITY_READY An activity is ready. The models supplied include: type="bpmn:userTask" type="bpmn:process" type="wle:processApplication"
bpmnx:ACTIVITY_ACTIVE An activity is active. The models supplied include: type = "bpmn:userTask" type = "bpmn:process" type = "wle:processApplication"
bpmnx:ACTIVITY_COMPLETED An activity has completed
bpmnx:ACTIVITY_TERMINATED An activity has terminated
bpmnx:ACTIVITY_FAILED An activity has failed
ACTIVITY_LOOP_CONDITION_TRUE
ACTIVITY_LOOP_CONDITION_FALSE
ACTIVITY_PARALLEL_INSTANCES_STARTED
bpmn:EVENT_CAUGHT The models supplied include: The models supplied include: mon:type = "bpmn:startEvent" mon:type = "bpmn:process" mon:type = "wle:processApplication"
bpmn:EVENT_EXPECTED
bpmn:EVENT_THROWN
bpmn:GATEWAY_ACTIVATED
bpmn:GATEWAY_COMPLETED

The model type can be:

|| |bpmn:process|| |bpmn:intermediateThrowEvent|| |wle:processApplication||

A common pattern will be to create a Monitoring Context when a bpmnx:PROCESS_STARTED event is detected and close the Monitoring Context when a bpmnx:PROCESS_COMPLETED event is detected.

The XML Schema files that represent these events can be found in the InfoCenter at:

http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/topic/com.ibm.wbpm.admin.doc/topics/rmon_eventschemaext.html

These three files should be built, saved and added to the Monitor projects.

Common patterns

A Process has started

mon:monitorEvent/mon:eventPointData/mon:kind = bpmx:PROCESS_STARTED

Examining events issued from BPM

When a BPM process runs, it generates events that are sent to Business Monitor. From time to time, we may wish to examine these events and ensure that the data we expected to be sent arrived. Alternatively, we may simply be interested in seeing what is passing.

One way to achieve this is to switch on Event Recording. This can be done through the IBM WAS Admin Console in the

Applications > Monitor Services > Recorded Event Management > Event Recording

section. Within there we can enable or disable event recording:

Once enabled and new events generated, we can review those events from

Applications > Monitor Services > Recorded Event Management > Event Management

Clicking on an event will show its XML content:

Capturing additional data from BPM

The IBM generated monitor models are a great start but there are times when we might wish to capture additional information. Here we will document some recipes for additional items that may be of interest.

Capturing the Task ID of a task

When a task is created in the process, we may wish to know the Task ID for the task in the monitor data. This can be achieved by adding a new metric called "Task ID" in the "Steps" monitoring context. The data type of the metric should be "String" and the expression used to populate it should be:

if (fn:exists(ACTIVITY_RESOURCE_ASSIGNED_Event/EventPointData/mon:model[1]/mon:instance/wle:taskInstanceId)) then ACTIVITY_RESOURCE_ASSIGNED_Event/EventPointData/mon:model[1]/mon:instance/wle:taskInstanceId else Task_ID

Capturing the Process ID of a process

When a process instance is created, we may wish to know the Process ID of that process in the monitor data. This can be achieved by adding a new metric called "Process ID" in the top of the monitoring context for the generated model. The data type of the metric should be "String" and the expression used to populate it should be:

PROCESS_STARTED_Event/EventPointData/mon:model[1]/mon:instance/@mon:id

Capturing the Process Name of a process

When a process instance is created, we may wish to know the Process Name of that process in the monitor data. This can be achieved by adding a new metric called "Process Name" in the top of the monitoring context for the generated model. The data type of the metric should be "String" and the expression used to populate it should be:

PROCESS_STARTED_Event/EventPointData/mon:model[1]/mon:name

Page 10

No Comments
Back to top