Monitoring your business applications, Part 3: Enable

programmatic event emission to IBM Business Monitor

John W. Alcorn
Senior Software Engineer
IBM

04 February 2016
(First published 18 May 2011)

Latha Sivakumar (lsivakum@us.ibm.com)

Advisory Software Engineer
IBM
IBM Business Monitor provides dashboards that offer insight into the performance of your
business based on events sent from your applications. Part 3 explains how to programmatically
instrument your applications to emit business events.
View more content in this series

Overview
For an overview of the features and architecture of IBM Business Monitor, see Part 1.
IBM Business Monitor is designed to accept and process events from any source. Applications
can be instrumented to emit events containing a business payload which IBM Business Monitor
consumes; it extracts and analyzes the business data from the incoming events for later reporting
purposes in the dashboards.

Copyright IBM Corporation 2011, 2016

Monitoring your business applications, Part 3: Enable
programmatic event emission to IBM Business Monitor

Trademarks
Page 1 of 9

developerWorks

ibm.com/developerWorks/

Figure 1. IBM Business Monitor dashboard

This article describes how to enable event emission if your application is running in an
environment that does not provide automatic event emission.
IBM Business Monitor processes XML, extracts metric data of business relevance, then stores it
to a database, which can be queried by dashboards to display information relevant to a business
user. Regardless of how an application is implemented, whether in Java, C++, COBOL, or
other language, and regardless of where it runs, whether on a smartphone, a PC, or a mainframe,
as long as it can provide XML to IBM Business Monitor, an application can enjoy the benefits
of business activity monitoring. In this article, you'll learn how to get that XML to IBM Business
Monitor.
As described in Part 1, the preferred way of getting events to IBM Business Monitor is to run your
application in one of the many IBM products that are enabled for automatic event emission. In
such an environment, you can just check a box and the events will flow, without any coding at
all. You don't need to worry about how to structure your XML, what kind of wrapper to use, what
protocol will carry it, or the endpoint to which it will be delivered; this is all taken care of for you by
virtue of using an IBM runtime with built-in business event emission support.
However, sometimes you have no choice but to run your applications in an environment where
event emission is not automatically handled for you. In such cases, several means of manually
emitting events for business activity monitoring purposes are supported. The choice of which
approach to use depends on the environment in which your business application executes.

Monitoring your business applications, Part 3: Enable

programmatic event emission to IBM Business Monitor

Page 2 of 9

ibm.com/developerWorks/

developerWorks

Regardless of which approach you choose for programmatic event emission, you need to follow
the manual monitor model authoring approach described in Part 2, and you'll need to supply the
XSDs or WSDLs that describe the XML being sent as input. You also need to ensure that the
events you send follow the XML namespace recommendations from the W3C. In particular, all
tags in the XML should contain the namespace prefix, so that XPath expressions can properly
reference the desired elements or attributes of the XML event. Refer to Part 2 for details on
making your monitor model aware of the structure of your XML events.

Enabling asynchronous event emission

There are two ways to send events: synchronously or asynchronously. With synchronous event
emission, the application being monitored must pause and wait for the event to be processed,
whereas with asynchronous event emission, the event is simply placed in an intermediate
destination, allowing the application being monitored to continue, while the event gets processed in
parallel.
In general, most customers prefer the asynchronous route, since it causes the least impact on the
application being monitored, so we'll look at that option first. This method uses the Java Message
Service (JMS), as shown in Figure 2.

Figure 2. Event emission to IBM Business Monitor using JMS

The code snippet in Listing 1 shows an example of sending an XML message using JMS.

Listing 1. Code sample for emitting an event using JMS

String xml = null; //initialize with the XML you want to send
// Connect to the server
Context jndiContext = new InitialContext();
// Get the connection factory via its JNDI name
QueueConnectionFactory connectionFactory = (QueueConnectionFactory) jndiContext.lookup(
"jms/MonitorEventEmitter/QueueConnFactory");
// Create a connection
QueueConnection jmsConnection = connectionFactory.createQueueConnection();
// Start a session
QueueSession session = jmsConnection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
// Create your message
TextMessage jmsMessage = session.createTextMessage(xml);
// Get the queue via its JNDI name
Queue jmsQueue = (Queue) jndiContext.lookup("jms/MonitorEventEmitter/Queue");

Monitoring your business applications, Part 3: Enable

programmatic event emission to IBM Business Monitor

Page 3 of 9

developerWorks

ibm.com/developerWorks/

// Send the messsage to the queue

QueueSender sender = session.createSender(jmsQueue);
sender.send(jmsMessage);
// Cleanup
sender.close();
session.close();
connection.close();

The following list includes JMS providers that are supported, as well as some guidance on when to
choose one versus another.
WebSphere Platform Messaging: For applications running in a WebSphere Application
Server based environment, the preferred approach is to place your business payload XML
into a JMS text message and send it using WebSphere Platform Messaging (also known as
the Service Integration Bus). Using this approach, you simply create a JMS TextMessage,
place your XML in that message, and submit it to a well-known JMS destination. You don't
need to worry about using any special wrappers or setting any special values in the JMS
header -- as long as you deliver it to the appropriate destination, IBM Business Monitor takes
care of the rest.

MQ as the enterprise JMS provider

Note that, even for some WebSphere Application Server based applications, the use
of IBM MQ may be advisable if you want to ensure you can handle cases where the
event consumption is temporarily halted. IBM MQ supports very deep queues, so
you can confidently send events and be assured of their eventual delivery. Even if
many millions of events are sent during a period, they will all be persisted and will be
consumed once everything is back online.

IBM MQ: For applications running in environments that are not based on WebSphere
Application Server, but with access to IBM MQ, the approach is very similar. You just create
an MQ message, place your XML in that message, and deliver it to a well-known MQ
destination. Your administrator can configure IBM Business Monitor to consume from this
destination defined under the MQ JMS provider.
Third-party JMS providers: If you prefer, you can use a non-IBM JMS provider. The
approach is the same: place the XML in the JMS message, deliver it to the well-known
destination, and configure IBM Business Monitor to consume from the destination defined
under the third-party JMS provider.

Enabling synchronous event emission

Sometimes you need to send your events synchronously, such as when the events do not contain
reliable sequence information, and therefore you need to choose an option that will ensure they
are kept in order. There are two approaches for synchronous event emission:
WS-Notification: If you are running in a web services environment, the most natural means
of event emission is to use WS-Notification. With this approach, you construct your XML, and
submit it via a web service (SOAP) invocation, to a well-known WSDL-described endpoint.
As with the other options, no special wrappers are required; you just send your XML, and
Monitoring your business applications, Part 3: Enable
programmatic event emission to IBM Business Monitor

Page 4 of 9

ibm.com/developerWorks/

developerWorks

IBM Business Monitor will consume it. Your administrator must configure WS-Notification
to forward the notification event to the JMS destination from which IBM Business Monitor
consumes.
Emitting events through WS-Notification to IBM Business Monitor was made easier with
WebSphere Business Monitor V7 and later IBM Business Monitor products, because you
no longer need to create the Common Base Event (CBE) wrapper around your XML.
Instead, you send the XML directly to the Notify method, as long as your IT administrator
configures your WS-Notification topic to deliver the message to the JMS queue specified in
the asynchronous section above.

Transactionality
Note that when using REST, there is no transactional support; that is, once the event is
emitted, there is no way to undo the emission via a rollback. Furthermore, if the HTTP call
fails to return, you cannot easily determine whether the server processed it and sent the
event, or whether it never made it that far, making retry logic problematic, because of the risk
of duplicate events. Due to these limitations with REST, it is generally not recommended.

REST: If you are running in a mashup or portlet environment, you may communicate with the
server via Representational State Transfer (REST). Using this approach, you construct your
XML, and submit it via an HTTP (or HTTPS) request to a REST service running on the IBM
Business Monitor server. Again, no special wrapper or HTTP header information is required;
you just submit the XML via the REST interface, and the IBM Business Monitor server will
handle it from there.
Listing 2 shows an example of sending an XML message using REST.

Listing 2. Code sample for emitting an event using REST

String xml = null; //initialize with the XML you want to send
// Set up URL to the desired host:port where REST Event Emitter is deployed
URL url = new URL("http://myhostname:80/rest/bpm/events");
// get the connection from the URL
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
// setup the connection
connection.setRequestMethod("POST");
connection.setRequestProperty("Accept", "multipart/mixed");
// set the content type
connection.setRequestProperty("content-type", text/xml));
// Set the DoOutput flag to true; use the URL connection for output
connection.setDoOutput(true);
// Write the XML to the stream
OutputStreamWriter writer = new OutputStreamWriter(connection.getOutputStream());
writer.write(xml);
writer.flush();
// Get the response from servlet
InputStreamReader reader = new InputStreamReader(connection.getInputStream())
BufferedReader buffer = new BufferedReader(reader);
String output = "";

Monitoring your business applications, Part 3: Enable

programmatic event emission to IBM Business Monitor

Page 5 of 9

developerWorks

ibm.com/developerWorks/

String line = null;

// Get all of the lines
while ((line = buffer.readLine()) != null) {
output += line;
}
// Cleanup
buffer.close();
writer.close();

Note that, in prior releases, you had to use a proprietary event format (Eclipse's Common Base
Event, or CBE) and a proprietary emission API (Common Event Infrastructure, or CEI) in order
to send your own events to IBM Business Monitor. This is no longer required in V7. Although the
old approach is still supported for backward compatibility, none of the approaches outlined above
involve the use of CBE or CEI when coding your own custom event emission.

Accessing IBM Business Monitor data

As shown in the architectural diagram in Part 1, the dashboards get their data by making REST
requests to the IBM Business Monitor server. Each widget in the dashboard makes an HTTP
request to get the desired data, receives the result in JavaScript Object Notation (JSON), and then
proceeds to parse that and render it as appropriate, using a technology like Dojo, as shown in
Figure 3.

Figure 3. REST access to monitor model data

To get programmatic access to IBM Business Monitor, you can write your own custom dashboard
iWidgets (or portlets), which make the same HTTP requests and then render the results in a highly
customized manner, to meet the needs of your business users. You can also do the same in a
simple servlet or JSP, or any other browser-based technology.
You can also go beyond the realm of web browser-based access to a monitor model's data. For
example, Microsoft Excel (2007 or later) provides a Ribbon, which is a Microsoft .NET based
plug-in that makes the appropriate REST calls to retrieve data and bring it into your spreadsheet
so that you can make charts and further computations based on this data. This data can be
configured to auto-refresh at a specified interval. Likewise, Lotus Notes and Lotus SameTime
have a plug-in that does the same thing, as a Java-based Eclipse/Expeditor plug-in, allowing you
access to your business monitoring data from within your e-mail and instant messaging clients.
You could do the same with native applications for smartphones, or any other environment capable
of making an HTTP connection to your IBM Business Monitor server (or the HTTP server/proxy
that delegates to it).

Monitoring your business applications, Part 3: Enable

programmatic event emission to IBM Business Monitor

Page 6 of 9

ibm.com/developerWorks/

developerWorks

Figure 4. Custom clients to business monitoring data

Summary
In Part 1, you learned about the products that offer first-class support for IBM Business Monitor.
In Part 2, you learned about additional products that can send events to IBM Business Monitor,
and how to enable that at model authoring time. In Part 3, you've learned how to instrument an
application to send events programmatically.
Some scenarios require more work on the part of IT developers than others, but all provide
for a rich experience for business users using the dashboards, providing them insight into the
performance of their business and suggesting areas where improvement is needed in their
business processes, wherever those processes may run. You can realize the full potential
of business process management by adding business activity monitoring to your enterprise,
regardless of what kind of business processes you are using, whether hosted in an IBM runtime or in a home-grown environment. You can empower your business users by giving them a
business dashboard from which they can monitor their business processes and optimize their
business results today.
Monitoring your business applications, Part 3: Enable
programmatic event emission to IBM Business Monitor

Page 7 of 9

developerWorks

ibm.com/developerWorks/

Resources
WebSphere Business Monitor REST APIs used to access information from the Monitor
database (WebSphere Business Monitor V7 product documentation)
WebSphere Business Monitor JMS Event Emitter (WebSphere Business Monitor V7 product
documentation)
WebSphere Business Monitor REST Event Emitter " (WebSphere Business Monitor V7
product documentation)
developerWorks BPM zone: Get the latest technical resources on IBM BPM solutions,
including downloads, demos, articles, tutorials, events, webcasts, and more.

Monitoring your business applications, Part 3: Enable

programmatic event emission to IBM Business Monitor

Page 8 of 9

ibm.com/developerWorks/

developerWorks

About the authors

John W. Alcorn
John Alcorn is the lead architect for the IBM Business Activity Monitoring (BAM)
platform. He has worked as a software engineer with IBM for 19 years, with more than
14 years on WebSphere products, including roles in both product development and
software services. John has been a technical leader with the IBM Business Monitor
product for seven years, and works closely with the wider IBM Business Process
Management (BPM) team.
John is IBM-certified in XML technologies, SOA technologies, and in multiple
WebSphere products, and is Sun-certified in Java programming. He is currently
privileged to work with an excellent team of software engineers at IBM's Research
Triangle Park lab in North Carolina.

Latha Sivakumar
Latha Sivakumar is currently a member of the WebSphere DataPower development
team. Prior to that, she was a developer on the WebSphere Business Monitor
development team, focusing on integration with other IBM products.

Copyright IBM Corporation 2011, 2016

(www.ibm.com/legal/copytrade.shtml)
Trademarks
(www.ibm.com/developerworks/ibm/trademarks/)

Monitoring your business applications, Part 3: Enable

programmatic event emission to IBM Business Monitor

Page 9 of 9