Them CEI-events – How Can They Be Communicated to Third Party?

By

Brief Description of How to Configure CEI in WPS/BPM to Send Events to CBE Listener – for Example NetCool Omnibus

Introduction

The technology in this description has been verified in Websphere Process Server 7.0.0.3, BPM Advanced – Process Server 8.0.0.1 and BPM Advanced 8.5.6.0 CF01. The discussion below about the deprecated functionality is – at the time of writing – only relevant for the last two of these tested environments. All of these environments are currently EOS – but the latest one is still supported until 2022 with an extended support agreement.

Deprecated – and Re-establishing

  • CEI (Common Event Infrastructure) has from Business Process Manager releases following V8.5.0 become deprecated. Instead the DEF (Dynamic Event Framework) has been introduced as an alternative. This document will focus on CEI events, primarily used for System Management reasons, more than as a KPI conveyer. It is important to emphasize that the technology indeed is deprecated and that the usage described by no means indicates that CEI should be used instead of standard system management architectures such as ITCAM and ITM. In order to re-enable CEI on post BPM v8.5.0 environments, one would typically connect to the relevant Websphere Application Service profile using wsadmin (<profile>\bin) and give the command (using -lang jython):

    AdminTask.wbmDeployCEIEventService ('[-eventService [-server -node -disabled false -enableDataStore false] -jmsAuthAlias [-user -password ]]')

    This command assumes that there is no cluster and/or Deployment Manager involved, in which case the syntax and procedure would be slightly different. After the command has been given, the server needs to be restarted.  If this command is not issued on post BPM v8.5.0 profiles, the menu options referred to in this document will not be available.

    In addition, this command assumes that events will not be persisted in an event database. If events indeed are to be persisted in an event database the options need to be revised. This is also relevant in regard to the chapter “Configure Event-Group Distributions Queue in Websphere Application Server” below, since an option during CEI event configuration allows the explicit choice whether to persist events or not.

  • If the Java API is used to emit CEI events, the appropriate packages:

    import com.ibm.events.EventsException;
    import com.ibm.events.emitter.Emitter;
    import com.ibm.events.emitter.EmitterFactory;
    import com.ibm.events.emitter.TransactionMode;

    .. were not included in IID V8.0 and up. That is it was prematurely deprecated, since it was not de facto to be deprecated until V8.5.0. In order to remedy this situation, the correct jar file:

    WebSphere\AppServer\plugins\com.ibm.events.client.jar

    .. needs to be added as an External JAR in the Java Build Path.

Overall Usage

In WebSphere Process Server and WebSphere BPM (Process Server) V8.5.0 and earlier (as well as post V8.5.0 systems with the aforementioned process to re-establish CEI functionality performed) is able to forward outbound events to the Common Event Infrastructure (CEI), which used to be IBM’s infrastructure for the creation, transmission, persistence and distribution of a wide range of business, system and network Common Base Event formatted events. A Common Base Event is a specification based on XML that defines a mechanism for managing events – such as logging, tracing, management, and business events – in business enterprise applications.

CEI provides basic event-management services, including consolidating and persisting raw events from multiple, heterogeneous sources and distributing those events to event consumers. It provides functionality for generation, propagation, persistence, and consumption of events representing service component processes. A standard, XML-based format, the Common Base Event model, defines the structure of these events. Each type of event used by the server contains a number of standard fields specific to a given type of event. In some cases, it contains an encapsulation of the business object data that is being used by the service component at a particular event point.

The basic concept behind the Common Base Event model is the situation. A situation can be anything that happens anywhere in the computing infrastructure, such as a server shutdown, a disk-drive failure, or a failed user login. The Common Base Event model defines a set of standard situation types that accommodate most of the situations that might arise (for example, StartSituation and CreateSituation).

An event is a structured notification that reports information related to a situation. An event reports three kinds of information:

  • The situation itself (what has happened)
  • The identity of the affected component (for example, the server that has shut down)
  • The identity of the component that is reporting the situation (which might be the same as the affected component)

The Common Base Event specification defines an event as an XML element containing properties that provide all three kinds of information. These properties are encoded as attributes and subelements of the root element, CommonBaseEvent.

Purpose

The purpose of this document is to formulate some kind of idea how CEI can/could be used to centrally distribute error events as well as informational- and audit events. This can be regulated by using priority and severity and creating proper filters where some information is sent to one destination and other information is sent to another destination. The concepts in this paper were proven in an environment where NetCool Omnibus received the CBE-events using its JMS Probe functionality – which natively supports the CBE format via style sheets provided with the solution.

In Omnibus it is possible to possibly remap the incoming CBE message to other formats should it be necessary to forward the information into the ITM System Management Change. An advantage of this approach is also the possibility to save a copy of the outgoing events – either in the archive database or possibly on another MQ queue. This information can be used to calculate statistics (for example how many events with priority 65 that have been managed over a time period), but it can also be used to show a client that an event has actually been sent to an Enterprise Console should there be any doubt.

IMHO it is not a good idea to use JMS Topics unless it is very carefully planned, since it is quite easy to register as a durable subscriber and later on forget to actually read the messages, meaning that they will queue up considerably. In addition, queues allow a higher degree of scaling, since it is possible to up the number of consumers should the queue depth increase. For topics this would not be an option unless one manages to register many subscribers with the same ID. Edit: JMS 2.0 – implemented in IBM MQ v8 – supports shared subscriptions among multiple consumers.

By using CEI it is possible to send events not only from Java (deprecated), but also using Mediations and JMS. In addition the components themselves use CEI to signal status, which means that all diagnostic events would use only one mediating functionality. The information below shows how to configure such a connection where the CEI emitters send events that via the Event Server is being forwarded to the Consumer.

Steps to Configure

In order configure WPS/BPM to send CBE-events to the MQ queue there are a number of steps one need to address:

  1. Create an MQ queue and administer proper authorities depending on your security scheme.  It is also probably a decent idea to create a Server Channel to be used when accessing the message event.

  2. Configure a JNDI-lookup to point to the MQ-queue and a queue connection factory. This can either be performed in the Websphere Admin Console or using the wsadmin command line utility.

  3. Verify that CEI is activated in the WebSphere Application Server. This is to be done in the Websphere Application Server Console.

  4. Configure an Event Group with a Distribution queue in Websphere Application Server. This can be done in the Administration Console.

  5. Create a bindings-file to deliver to the client. This .bindings-fil can be used by Omnibus to connect to the MQ Queue Manager.

Create an MQ Queue

This is typically rather straightforward. An example could be for example:

C:>runmqsc
5724-H72 (C) Copyright IBM Corp. 1994, 2009. ALL RIGHTS RESERVED.
Starting MQSC for queue manager qmcei.

define qlocal('ceiqueue') maxmsgl(100000000) defpsist(YES) maxdepth(5000)
1 : define qlocal('ceiqueue') maxmsgl(100000000) defpsist(YES) maxdepth(5000)

AMQ8006: WebSphere MQ queue created.

define channel('ceichl') chltype(SVRCONN) maxmsgl(100000000)
2 : define channel('ceichl') chltype(SVRCONN) maxmsgl(100000000)

AMQ8014: WebSphere MQ channel created.

end
3 : end
2 MQSC commands read.
No commands have a syntax error.
All valid MQSC commands were processed.

Configure JNDI-name

This can easily be done in the Websphere Admin console under Resources/JMS/Queues. It can also be created using wsadmin – which could be an idea if one wants to specify configuration values under configuration control. A simple cluster version of such a functionality could look like below using jython:

cluster = AdminConfig.list('ServerCluster').split("(")[0]

def createQueue(cluster, nameValue, jndiValue, queueNameValue, queueManagerValue):

        import java
        lineseparator = java.lang.System.getProperty('line.separator')
        print "Function createQueue starting. Name="+nameValue+" Jndi="+jndiValue
        existq = AdminConfig.getid("/ServerCluster:"+'SingleCluster'+"/JMSProvider:WebSphere MQ JMSProvider/MQQueue:" + nameValue)

        if existq == '':       
                mqqAttrs = "-name "+nameValue+" -jndiName "+jndiValue+" -queueName "+queueNameValue+" -qmgr " + queueManagerValue + " -useNativeEncoding false -useRFH2 false -sendAsync YES -readAhead YES -ccsid '' -customProperties [['MDREAD' 'YES']['MDWRITE' 'YES']['MSGBODY' 'MQ' ]]"
               clusterName = AdminConfig.getid("/ServerCluster:"+cluster).split("#")[0]+")"
               AdminTask.createWMQQueue(clusterName,mqqAttrs)
               AdminConfig.save()
        else:
               print "MQQueue "+nameValue+" already exists."
        print "Function createQueue done."

createQueue(cluster, "ceiqueue", "mq/ceiqueue", "ceiqueue", "qmcei")

In addition it is important to specify a queue connection factory pointing to the MQ Queue Manager. This can be done as a choice between the Websphere Admin Console (under Resources/JMS/Queue Connection Factories) and a script as well.

Activate CEI

  1. Log in to the WAS Console
  2. Select ”Servers”/”Server Types”/”Websphere application servers”
  3. Select the correct Server
  4. Under ”Container Settings”/”Container Services” select  “Common Event Infrastructure Service” 
  1. Verify that the checkbox “Enable service at server startup” is checked

Configure Event-Group Distributions Queue in Websphere Application Server

Now we are to configure Websphere Application Server to send the CEI events to the queue we created previously!

  1. Select ”Service Integration”/”Common Event Infrastructure”/”Event Service”: Select “Event services”
  2. Select the only Service: “Default Common Event Infrastructure event server”.
  3. Verify that “Enable event distribution” is checked! Now Select ”Event groups”!
  4. All configured Event Groups are shown. We are now to create a new Event Group – aside from the default.

Select New…

  1. Event group name: <myGroup>
  2. Event selector string: CommonBaseEvent[@globalInstanceId]. Here it is also possible to add a filter specifying for example severity and priority. The purpose behind this could be to divert less serious events to one destination and warnings and errors to yet another.
  3. Make certain that “Compatibility mode with previous event service transmission protocol” is only ticked if it is a part of the design. Ticking this box will cause a serialized object to be sent to the queue instead of a CBE XML. The Topic entries are not relevant, since the intention is to send the event to a distribution queue!
  1. Do only “Persist event to event data store” if this is a part of the design and a datastore indeed exists. This will only actually be done if you have selected that the event store is to be used in the configuration panel for ”Default Common Event Infrastructure event server”. This is however outside of the document scope.

    Press Apply
  2. Select Save:
  1. Select the new Event-Group <myGroup> (in the example above ceigroup)
  2. Select “Distribution queues”
  3. Press New…
  4. Now select the Queue JNDI-name <mq/jndiname> we created previously from the pulldown menu beneath ”Queue JNDI name”.
  5. Also select the JNDI-name used for the queue connection factory we created previously from the pull down menu beneath ”Queue connection factory JNDI name”!
  6. Select OK! Press ”Save…” in order to save the new distribution queue. The configuration can now be used and the new distribution queue should be visible in the console

Note that after adding this configuration, one would need to restart the application server! Essentially after every cei configuration change one would need to restart the application server!!

CEI Event Results

After submitting a CEI-event – using arbitrary supported technology – the actual event CBE message will be sent to the queue specified in the JNDI entry specified in the picture above. Picking it up from the MQ queue would display the following CBE XML – or something similar depending on the values specified at the time of emission.

Create a Client Binding File

Most of the configuration is now performed – and one thing that remains is to tell NetCool Omnibus how to find our MQ queue manager and corresponding CEI queue. In order to do so, Omnibus needs a jndi-provider. In this case a simple provider configuration, based on the file system, is used. The result of the configuration will be a file named .bindings and it is to be delivered to the operator of the remote system in order to assist in connecting to the MQ queue using the channel we provided in the configuration example.

The configuration does not have to be performed on the specific MQ queue manager server. However an MQ installation must reside on the system in question, since the program JMSAdmin is to be used. JMSAdmin is distributed with the MQ Client and the MQ Server distributions.

Two examples are provided below: one for Unix and one for Windows:

Unix
1.	Log on to the Unix system:

su – mqm
cd /var/mqm
 
2.	Create a JNDI work directory:

bash-3.2$ pwd
/var/mqm
bash-3.2$ mkdir JNDI-Directory
bash-3.2$ cd JNDI-Directory
 
3.	Create configuration file - JMSAdmin.config - with the following content:

INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory
PROVIDER_URL=file:///var/mqm/JNDI-Directory
SECURITY_AUTHENTICATION=none
 
4.	Verify Environment variable

bash-3.2$ echo $MQ_JAVA_INSTALL_PATH
/usr/mqm/java
 
5.	Verify that Java runtime can be found in the System Path:

bash-3.2$ which java
which: 0652-141 There is no java in /…

bash-3.2$ PATH=/usr/java6/bin:$PATH
bash-3.2$ which java
/usr/java6/bin/java
 
6.	Start JMSAdmin in order to create the .bindings-file. InitCtx commands are marked with bold and installation specific information is specified within <>-characters. The MQ objects (queue manager name, queue name and server channel name) used previously in this document will be used in the examples.

bash-3.2$ $MQ_JAVA_INSTALL_PATH/bin/JMSAdmin -cfg /var/mqm/JNDI-Directory/JMSAdmin.config

Licensed Materials - Property of IBM
5724-H72, 5655-R36, 5724-L26, 5655-L82
(c) Copyright IBM Corp. 2008, 2011 All Rights Reserved.
US Government Users Restricted Rights - Use, duplication or
disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Starting WebSphere MQ classes for Java(tm) Message Service Administration

InitCtx> DEF CF(CEICF) QMGR(qmcei) TRANSPORT(CLIENT) HOSTNAME(<MQ queue manager hostname>) PORT(<MQ queue manager port number>) CHANNEL(ceichl)

InitCtx> def Q(CEIQ) QMGR(qmcei) QUEUE(ceiqueue)

InitCtx> DEF QCF(QCEICF) QMGR(qmcei) TRANSPORT(CLIENT) HOSTNAME(<MQ queue manager hostname>) PORT(<MQ queue manager port number>) CHANNEL(ceichl)



InitCtx> dis ctx

  JMSADM4089 InitCtx

      .bindings                 java.io.File
      JMSAdmin.config           java.io.File
   a  CEICF                     com.ibm.mq.jms.MQConnectionFactory
   a  QCEICF                    com.ibm.mq.jms.MQQueueConnectionFactory
   a  CEIQ                      com.ibm.mq.jms.MQQueue

  5 Object(s)
    0 Context(s)
    5 Binding(s), 3 Administered

InitCtx> END


Stopping WebSphere MQ classes for Java(tm) Message Service Administration

Windows

This is just a short summary of the steps required to create the .bindings file in Windows. The host name “ibmbpm” and channel port number “1414” has been assumed.



1.	Create a JNDI work directory:

C:\>cd MQ

C:\MQ>mkdir JNDI-Directory

C:\MQ>cd JNDI-Directory



2.	Create configuration file - JMSAdmin.config - with the following content:

C:\MQ\JNDI-Directory>copy con JMSAdmin.config
INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory
PROVIDER_URL=file://\\c:\\MQ\\JNDI-Directory
SECURITY_AUTHENTICATION=none
^Z
        1 file(s) copied.

3.	Verify Environment variable

C:\MQ\JNDI-Directory>echo %MQ_JAVA_INSTALL_PATH%
C:\Program Files\IBM\WebSphere MQ\java

4.	Verify that the path is correct to find JMSAdmin

C:\MQ\JNDI-Directory>PATH=%MQ_JAVA_INSTALL_PATH%\bin;%PATH%

5.	Start JMSAdmin in order to create the .bindings-file. InitCtx commands are marked with bold and installation specific information is specified within <>-characters. The MQ objects (queue manager name, queue name and server channel name) used previously in this document will be used in the examples.

C:\MQ\JNDI-Directory>jmsadmin -cfg %CD%\JMSAdmin.config


Licensed Materials - Property of IBM
5724-H72, 5655-R36, 5724-L26, 5655-L82
(c) Copyright IBM Corp. 2008, 2011 All Rights Reserved.
US Government Users Restricted Rights - Use, duplication or
disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Starting WebSphere MQ classes for Java(tm) Message Service Administration

InitCtx> DEF CF(CEICF) QMGR(qmcei) TRANSPORT(CLIENT) HOSTNAME(ibmbpm) PORT(1414)
 CHANNEL(ceichl)

InitCtx> def Q(CEIQ) QMGR(qmcei) QUEUE(ceiqueue)

InitCtx> DEF QCF(QCEICF) QMGR(qmcei) TRANSPORT(CLIENT) HOSTNAME(ibmbpm) PORT(141
4) CHANNEL(ceichl)

InitCtx> dis ctx

  JMSADM4089 InitCtx

      .bindings                 java.io.File
      JMSAdmin.config           java.io.File
   a  CEICF                     com.ibm.mq.jms.MQConnectionFactory
   a  QCEICF                    com.ibm.mq.jms.MQQueueConnectionFactory
   a  CEIQ                      com.ibm.mq.jms.MQQueue

  5 Object(s)
    0 Context(s)
    5 Binding(s), 3 Administered

InitCtx> end

Stopping WebSphere MQ classes for Java(tm) Message Service Administration

Distribution of

Now it is possible to distribute the resulting .bindings file to the Operator/administrator of the system to receive the CEI events. The operator will use the .bindings file as input to the JNDI-provider and connect to the queue manager where the MQ queue receiving the events is to be found. Note: In Unix – in order to see the .bindings file, one would need to use the “ls -a” command, since the fact that the file name starts with a dot (“.”) prevents it from being seen when just using “ls” without the -a option.