Introduction

Part 13 of this series described some recommended approaches, depending on the event source, for sending events to WebSphere Business Monitor V6.1. For environments that use the .NET framework, and don't interact with any of the IBM products that serve as event sources for WebSphere Business Monitor (for example, IBM WebSphere Process Server and IBM WebSphere Business Services Fabric), an easy approach is to send events using a Web service. Hence, the WS-Notification configuration setup can play well in this scenario. Figure 1 shows the same configuration as in the previous article, except this time the event producer is a .NET application.

In this article, learn how to write a .NET application that can send events for a monitor model (the mortgage lending monitor model) that is deployed in your WebSphere Business Monitor server through WS-Notification. You'll see how a .NET client application can be written for the mortgage lending model. The results of running the application will be on the business dashboard. After reading this article, you should be able to write or extend your own .NET application to send events to your own specific monitor model.

.NET overview

.NET is a framework developed by Microsoft® that provides a set of base classes, which programmers can use to write their applications. It enables the development of various type of applications, including database, Web, desktop and mobile applications. The .NET framework includes a runtime, or virtual machine (common language runtime), that manages the execution of programs that were implemented using the framework. The framework is aimed at programmers who want to write applications for the Windows® platform, though there are open source projects, such as Mono, which provide an implementation of the .NET framework for UNIX® systems.

The .NET framework lets programmers write applications in several programming languages, such as Visual Basic, C#, C++ and J#. Because all of these languages are compiled into a common intermediate language (CIL), programs written in any of the languages can interact with one another through the common language runtime (CLR). The CIL would be equivalent to the bytecode in the Java world; the CLR would be equivalent to Java Virtual Machine. C# is the most widely used language in the .NET framework. It is similar to Java in many ways, including: code structure, multiple implementation of interfaces but a single inheritance from a class, creation of objects in the heap using the new keyword, and more.

Both J2EE and .NET frameworks are major forces in the enterprise application market today. Being able to consume events from both frameworks puts WebSphere Business Monitor in a great position.

Creating a .NET application for mortgage lending

The client application included as a sample with this article (see Download) can send events to the mortgage lending model using the WS-Notification service described in Part 13. Figure 2 shows the user interface for the application, which can be used to send five different types of events to the mortgage lending model. The rest of this article explains the required steps to create a client. Although the description is for sending only one event type, the steps are the same for all of the event types.

To create this application you need to:

1. Get the definition of a mortgage lending event.
2. Create a Windows Form Application and add controls to it to enter data for the event.
3. Generate a Common Base Event (CBE) class based on the CBE schema.
4. Generate a proxy for the WS-Notification service.
5. Add the code that creates a notification message, populates it with the event, and sends it using the WS-Notification proxy.

Step 1. Get the definition of a mortgage lending event

In the sample code, there are two event files for the mortgage lending model:

• 01_mortgageLendingProcessStart_0101.xml - starts the loan application process, so a new instance is created whenever this event is received.
• 02_loanApplicationUpload_0101.xml - is used to upload the loan amount for the application.

The steps in this article use the mortgageLendingProcessStart event as an example.

You can also find more events in the WebSphere Business Monitor installation. The event files are in:
%WAS_HOME%\installableApps.wbm\samples\mortgageLending\events\allevents.

If you don't have access to WebSphere Business Monitor server, you can also download the SupportPac™BA76: WebSphere Business Monitor – Banking Monitor Model, where you can find more sample events. The events on the following path are in the SupportPac:
ba76\FinancialPackageBAM\sampleevents\mortgageLendingBAMSampleEvents_2007\mortgageLendingSampleBAMEvents_2007\month_X.

From the 01_mortgageLendingProcessStart_0101.xml file, extract the section that is relevant to the model event, which is shown below. Later on, after you've created the application project, add this definition as a string constant in the code. You will also need the value of the extensionNamec attribute of the CBE, which for this case is mortgageLendingProcessStart.

<mor:mortgageLendingProcessStart mor:eventName="mortgageLendingProcessStart" 
xmlns:mor="http://MortgageLendingBAMModel">
    <mor:loanNumber>0101</mor:loanNumber>
    <mor:loanOfficer>Gerald Mander</mor:loanOfficer>
    <mor:dateStarted>2008-01-02T12:00:00.578Z</mor:dateStarted>
    <mor:dateCompleted>2008-01-02T12:00:15.578Z</mor:dateCompleted>
</mor:mortgageLendingProcessStart>
		

Step 2. Create a Windows Form Application

Now you're ready to create the .NET client. In Visual Studio, create a new Windows Form Application project by selecting File > New > Project > Visual C# > Windows > Windows Form Application. Enter a name for the project, such as MortgageLendingProducer. The client doesn't need to be a form application; it can also be a console application, a Web application or any other application type. This article uses a form application project type only because it is easier to describe the steps.

Add controls to the form to enter data for the event to be sent. For example, for the sample event mortgageLendingProcessStart you'll need two Textbox controls for the loanNumber and the loanOfficer fields, and two DateTimePicker controls for the dateStarted and dateCompleted fields. You will also need an additional Textbox control, and should set its multiline property to true to use it as an output field for trace messages. Finally, add a Button control to send the event. The sample application uses a TabControl to host the controls for the different event types, but you won't need this if you only plan to send this event type.

You will need a class that will hold the event definition in a string constant, and additional strings that will serve as place holders for the values in the event XML definition. In the sample application, these variables are part of the Constants class. An example of the constants is shown below.

public static readonly string PROCESSSTART_EVENT = 
   "<mor:mortgageLendingProcessStart 
    mor:eventName=\"mortgageLendingProcessStart\" 
    xmlns:mor=\"http://MortgageLendingBAMModel\">" +
      "<mor:loanNumber>LOAN_NUMBER</mor:loanNumber>" +
      "<mor:loanOfficer>LOAN_OFFICER</mor:loanOfficer>" +
      "<mor:dateStarted>DATE_STARTED</mor:dateStarted>" +
      "<mor:dateCompleted>DATE_COMPLETED</mor:dateCompleted>" +
   "</mor:mortgageLendingProcessStart>";

public static readonly string PROCESSSTART_LOANNUMBER = "LOAN_NUMBER";
public static readonly string PROCESSSTART_LOANOFFICER = "LOAN_OFFICER";
public static readonly string PROCESSSTART_DATESTART = "DATE_STARTED";
public static readonly string PROCESSSTART_DATECOMPLETE = "DATE_COMPLETED";
	

Step 3. Generate a CBE class based on the CBE schema

To send an event to the WebSphere Business Monitor model through the WS-Notification service, you will need a class that represents the CBE that will be the payload of the notification message and will contain the monitor model event. You can do this by generating a class based on the CBE XML schema definition.

Download the commonbaseevent1_0_1.xsd file to a temporary directory. Open a command prompt and go to the bin directory of the Microsoft SDK. The Microsoft SDK is usually installed with Visual Studio so it should be in your program files or in the same directory where you installed Visual Studio. Enter the command below. (You will need to substitute the %XSD_path% tag with the temporary directory path of where you copied the commonbaseevent1_0_1.xsd file.)

xsd.exe %XSD_path%\commonbaseevent1_0_1.xsd /classes /outputdir:%XSD_path% /language:CS

This command creates a C# class on the specified directory that defines a CBE object. Now add the generated class to the project. In Visual Studio, right-click on the project and select Add > Existing Item. Browse to the location of the generated file and add it to the project.

Step 4. Generate a proxy for the WS-Notification service

To generate the WS-Notification proxy, you first need to download the WSDLs and XSDs that define this service from the WebSphere Business Monitor server administrative console. (Part 13 provides the steps for downloading the WSDLs and XSDs.) Once you have the files in a local directory, you can use the svcutil.exe program in the Microsoft SDK to generate the proxy.

Open a command prompt, move to the bin directory of the Microsoft SDK, and execute the command below. The command creates a proxy named %PROXY_FILENAME% in the directory %OUTPUT_DIR% based on the WSDLs and XSDs located in the %WSDLs_XSDs_DIR% directory. This command specifies names for all of the XML namespaces found in the WSDLs and XSDs to avoid conflicts between the operations and elements defined in these files. The command should be on a single line.

svcutil.exe /t:code "%WSDLs_XSDs_DIR%\*.xsd" "%WSDLs_XSDs_DIR%\*.wsdl" /language:c# 
/out:%PROXY_FILENAME% /directory:%OUTPUT_DIR%  
/n:http://docs.oasis-open.org/wsn/b-2,b_2 
/n:http://docs.oasis-open.org/wsrf/bf-2,bf_2 
/n:http://docs.oasis-open.org/wsn/br-2,br_2 
/n:http://docs.oasis-open.org/wsn/brw-2,brw_2 
/n:http://docs.oasis-open.org/wsn/bw-2,bw_2 
/n:http://docs.oasis-open.org/wsrf/r-2,r_2 
/n:http://docs.oasis-open.org/wsrf/rp-2,rp_2 
/n:http://docs.oasis-open.org/wsrf/rpw-2,rpw_2 
/n:http://docs.oasis-open.org/wsrf/rw-2,rw_2 
/n:http://docs.oasis-open.org/wsn/t-1,t_1
/n:http://www.ibm.com/websphere/wsn/notification-broker,notificationbroker 
/n:http://www.w3.org/2005/08/addressing,ws_addr 
/n:*,WSNService
		

Add the generated proxy class to the project. You will also need to add the following using directive to the generated proxy file.

using WSNService;

Step 5. Add the code to send the event

In the constructor of the form you will need to add code that creates a NotificationConsumerClient, which will be used to send the notification message with the CBE as payload. This client object requires a binding definition that specifies the transport protocol and the message encoding. It also requires the endpoint address of where the service is located. Sample code is shown below. You can find the URL of the service in the CommonEventInfrastructure_Bus.WSNServiceNotificationBrokerService.wsdl file, which should be one of the WSDLs downloaded from the administrative console.

/// The transport of the SOAP message is using HTTPS for this case
HttpsTransportBindingElement httpsBindElem = new HttpsTransportBindingElement();

/// The encoding of the SOAP message needs to follow the SOAP 1.1 version
/// which employs WS-Addressing
TextMessageEncodingBindingElement textMessageBindElem =
   new TextMessageEncodingBindingElement(
   MessageVersion.Soap11WSAddressing10, Encoding.UTF8);

/// Creating the binding with the transport and encoding elements
CustomBinding customBinding = new CustomBinding();
customBinding.Elements.Add(textMessageBindElem);
customBinding.Elements.Add(httpsBindElem);
            
EndpointAddress endpoint = new EndpointAddress(url);

/// Web service proxy
this.notificationConsumer = new bw_2.NotificationConsumerClient(customBinding, endpoint);
		

The binding specified in this sample uses HTTPS protocol. This should change if the service is exposed through an HTTP port. The text encoding specifies a binding that uses SOAP 1.1 with WS-Addressing. The default encoding of .NET doesn't use this type of binding, which is why you need to specify it.

Now that you've created the NotificationConsumerClient, you just need to create an event to send. The function that does this in the sample code is shown below. It creates a CommonBaseEventType and sets the extensionName, creationTime, globalInstanceId, sourceComponentID, and the situation properties, among others.

The extensionName corresponds to the value that was extracted from the attribute of the same name in the sample event file (Step 1). The globalInstanceId is meant to uniquely identify each event that is sent. For this property, the code uses a globally unique identifier (GUID) obtained from a call to the .NET GUID class.

When using this class, be aware that because a valid globalInstanceId for a CBE must start with a non-numeric character, the code loops until it finds a valid value. The rest of the parameters are the same for all of the events defined for the mortgage lending model, so those values are hardcoded.

private CommonBaseEventType createNewCBE(string extensionName)
{
    CommonBaseEventType cbe = new CommonBaseEventType();
    cbe.creationTime = DateTime.Now;
    cbe.extensionName = extensionName;

    // The event bus only accepts events that start with a character (non-numeric), 
    // so we are ignoring all GUIDs until we are able to find one that
    // meets this requirement
    string guid;
    short temp;
    do
    {
        guid = System.Guid.NewGuid().ToString("N");
    }
    while (Int16.TryParse(Char.ToString(guid[0]), out temp));
    cbe.globalInstanceId = guid;

    cbe.version = "1.0.1";
    cbe.sequenceNumber = 1;
    cbe.sequenceNumberSpecified = true;

    cbe.sourceComponentId = new ComponentIdentificationType();
    cbe.sourceComponentId.application = "TestApplication";
    cbe.sourceComponentId.component = "TestComponent";
    cbe.sourceComponentId.componentIdType = "TestComponentIdType";
    cbe.sourceComponentId.location = "TestLocation";
    cbe.sourceComponentId.subComponent = "TestSubComponent";
    cbe.sourceComponentId.locationType = "IPV4";
    cbe.sourceComponentId.componentType = "TestComponentType";

    cbe.situation = new Situation();
    cbe.situation.categoryName = SituationCategoryName.StartSituation;
    StartSituation startSituation = new StartSituation();
    startSituation.reasoningScope = "EXTERNAL";
    startSituation.successDisposition = "SUCCESSFUL";
    startSituation.situationQualifier = "START_COMPLETED";
    cbe.situation.situationType = startSituation;
   
    return cbe;
}
		

To finally send the event, you need to include the MortgageLending event as a payload to the CBE, add the CBE to the notification message, and finally send this message object. You do this in two separate methods. The first one, shown below, is the method for the button Click event. In this method, the values from the form controls are read and substituted into the model event definition string. Then the model event is added as a payload of the CBE, and the CBE is passed to the publishEvent method that publishes the event.

private void ProcessStart_btnSendEvent_Click(object sender, EventArgs e)
{
    ProcessStart_btnSendEvent.Enabled = false;
    ProcessStart_btnSendEvent.Refresh();

    if (validateTextbox(ProcessStart_txtLoanNumber) && 
	    validateTextbox(ProcessStart_txtLoanOfficer))
    {
        string eventString = Constants.PROCESSSTART_EVENT;
        eventString = eventString.Replace(Constants.PROCESSSTART_LOANNUMBER, 
            ProcessStart_txtLoanNumber.Text);
        eventString = eventString.Replace(Constants.PROCESSSTART_LOANOFFICER, 
            ProcessStart_txtLoanOfficer.Text);
        eventString = eventString.Replace(Constants.PROCESSSTART_DATESTART, 
            ProcessStart_DateStarted.Value.ToString(Constants.DATETIME_FORMAT));
        eventString = eventString.Replace(Constants.PROCESSSTART_DATECOMPLETE, 
            ProcessStart_DateCompleted.Value.ToString(Constants.DATETIME_FORMAT));

        CommonBaseEventType cbe = createNewCBE("mortgageLendingProcessStart");
        XmlDocument xmlDoc = new XmlDocument();
        xmlDoc.LoadXml(eventString);
        cbe.Any = new XmlElement[] { xmlDoc.DocumentElement };

        string output = publishEvent(cbe);
        ProcessStart_console.Text += output + Environment.NewLine;
    }
    else
    {
        MessageBox.Show("Enter a value for all the textboxes");
    }
    ProcessStart_btnSendEvent.Enabled = true;
    ProcessStart_btnSendEvent.Refresh();
}
		

The publishEvent method is responsible for creating the notification object, setting the topic, and adding the CBE as a payload to the notification message. The topic namespace to which the notification should be sent is http://www.ibmcompany.com/wsn_topic_space (which is the value of the topic_ns variable), and the topic name is cei_wsn_topic. These two values were set by the configuration script described in the previous article.

The topic expression used in this example follows a SIMPLE dialect format, and you need to specify this in the Dialect attribute of the topic. See Resources for more information on topics and dialects.

The publishEvent method uses the helper function getCBERootElement, which converts the CBE to an XML document and returns its root. You can go to the sample application source code to see the implementation of this method.

private string publishEvent(CommonBaseEventType cbe)
{
    try
    {
        XmlDocument xmlDocument = new XmlDocument();

        /// Notification message that will be sent to the web service
        Notify notification = new Notify();
        NotificationMessageHolderType notificationHolder = 
		    new NotificationMessageHolderType();

        /// Topic to which the notifications are sent
        TopicExpressionType topic = new TopicExpressionType();
        topic.Dialect = SIMPLE_TOPIC_EXPRESSION;

        /// The following line specifies a namespace name, an attribute name 
		/// and the namespace URI
        /// We are just interested in creating the topns namespace, 
		/// so the attribute name can have any value
        XmlAttribute attr = xmlDocument.CreateAttribute("topns", "dummy", topic_ns);
        topic.AnyAttr = new XmlAttribute[] { attr };
        topic.Any = new XmlNode[] { xmlDocument.CreateTextNode("topns:cei_wsn_topic") };


        CommonBaseEventsType events = new CommonBaseEventsType();
        events.CommonBaseEvent = new CommonBaseEventType[] { cbe };

        /// Prepare the notification object that will be sent
        notificationHolder.Topic = topic;
        notificationHolder.Message = getCBERootElement(events);
        notification.NotificationMessage = 
		    new NotificationMessageHolderType[] { notificationHolder };

        /// Make the service call to send the event
        notificationConsumer.Notify(notification);
        return "Event was sent!!";
    }
    catch (Exception e)
    {
        return "Event could not be sent. " + e.Message;
    }
}
		

At this point, the application is ready to start sending events.

Running the application

Before you run the application, determine the changes you would expect to see on the dashboard after sending the event. Figure 3 shows the instances view before any events have been sent. After the mortgageLendingProcessStart event is sent, it should create an instance that will show up as a row in this table.

To run the application, enter values for the Loan Number and Loan Officer, as shown in Figure 4, then click Send Event to send the event.

A new instance row should appear now in the instances view. It should have the same Loan Number and Loan Officer values that you specified for the event. Figure 5 shows the resulting instances view.

You can use the sample application to send other event types. To update the same instance, you just need to specify the same Loan Number value when sending the event. Figure 6 shows the application sending an Update Application event, which corresponds to the loanApplicationUpload event in the model. You can download the XML definition file of this event.

In this event, you also need to specify the Loan Amount. The value should update the key performance indicators (KPIs) Average Application Loan Amount($) and Total Applications($)-[M]. Figure 7 shows the updated instance and KPI gauges.

Back to top

Extending an existing .NET application

This article describes how to create a new .NET application that could send events to a WebSphere Business Monitor server. If you were to enable an existing application for sending events, the steps in this article would still be valid. You will need to import the event definitions for the model, create a proxy based on the WS-Notification service, and populate the event with relevant data to send it to the server using the proxy. There are many options for achieving this, including reading the event definitions from external resource files or having a separate library class that manages the communication with the service through a proxy. It will be very dependent on your business systems layout.

Back to top

Summary

When adapting business activity monitoring in your business, a basic tenet is how to make your business applications "monitorable." How do you enable them to send the right events with the least impact to your investment and operational costs? WebSphere Business Monitor has continually expanded its capabilities to process events from different sources.

You've learned different approaches for sending events in conjunction with supporting many IBM products that serve as event sources. This article and Part 13 described yet another powerful method that caters to many applications. With WS-Notification, any application that uses Web service can ultimately send an event to WebSphere Business Monitor. Since this is based on a well-known standard, the approach can support a variety of frameworks, such as J2EE, .NET, and so on.

Acknowledgments

The authors would like to thank Eric Wayne for his guidance in configuring WebSphere Business Monitor with WS-Notification.

Back to top

Download

Information about download methods

Resources

Learn

• Check out the other parts of this series:
  • Part 1, "What's new in WebSphere Business Monitor 6.1" (developerWorks, Dec 2007)
  • Part 2, "WebSphere Business Monitor 6.1 installation improvements" (developerWorks, Jan 2008)
  • Part 3, "Improved Unit Test Environment in IBM WebSphere Business Monitor Development Toolkit V6.1" (developerWorks, Feb 2008)
  • Part 4, "Use the Integrated Test Client to improve iterative development with WebSphere Business Monitor V6.1" (developerWorks, Mar 2008)
  • Part 5, "Managing failed and unrecoverable events In IBM WebSphere Business Monitor V6.1" (developerWorks, Apr 2008)
  • Part 6, "Combine high-level monitor models from IBM WebSphere Business Modeler with low-level monitor models from IBM WebSphere Integration Developer" (developerWorks, Apr 2008)
  • Part 7, "Creating user-defined XPath functions for IBM WebSphere Business Monitor V6.1" (developerWorks, Apr 08)
  • Part 8, "Enabling IBM WebSphere Business Monitor V6.1 to receive events from WebSphere MQ" (developerWorks, Apr 08)
  • Part 9, "Empowered authoring of monitor models with IBM WebSphere Business Monitor development toolkit for 6.1" (developerWorks, May 08)
  • Part 10, "Improved data handling with IBM WebSphere Business Monitor 6.1" (developerWorks, Jun 08)
  • Part 11, "Advanced installation of IBM WebSphere Business Monitor 6.1" (developerWorks, Jul 08)
  • Part 12, "Diagnosing installation problems with IBM WebSphere Business Monitor V6.1" (developerWorks, Aug 08)
  • Part 13, "Publishing event messages to IBM WebSphere Business Monitor V6.1 with WS-Notification" (developerWorks, Sep 08)
  
  
• Browse the WebSphere Business Monitor 6.1 Information Center for more details and reference material.
  
  
• Get a great introduction to WS-Notification from "Events and service-oriented architecture: The OASIS Web Services Notification specifications" (IBM Systems Journal, 2005).
  
  
• Read "WS-Notification in WebSphere Application Server Version 6.1" (developerWorks, Nov 2006) to understand how WS-Notification is realized in WebSphere Application Server.
  
  
• The IBM Redbook Business Activity Monitoring with WebSphere Business Monitor V6.1 has detailed steps for using various products and technologies for sending events to WebSphere Business Monitor.
  
  
• "Enabling WebSphere Business Monitor V6.1 to receive events via WebSphere MQ" (developerWorks, Apr 2008) explores the use of WebSphere MQ as an "on-ramp" to WebSphere Business Monitor.
  
  
• Consult the IBM WebSphere Application Server 6.1 Information Center for more details on WS-Notification resources and configuration.
  
  
• For more details on WS-Notification resources and configuration, walk through other scenarios for using WS-Notification in Chapter 22 of the IBM Redbook Web Services Handbook for WebSphere Application Server 6.1.
  
  
• Browse the "Jump-start business activity monitoring (BAM) series" (developerWorks) for a wealth of WebSphere Business Monitor how-to information and samples.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  
• In the Architecture area on developerWorks, get the resources you need to advance your skills in the architecture arena.
  
  
• Get an RSS feed for the series Put new capabilities of business activity monitoring (BAM) to work.
  
  

Get products and technologies

• Download the official standard specifications from OASIS WS-Notification Technical Committee.
  
  
• Download a sample DB2 emitter from the WebSphere Business Monitor samples.
  
  
• Find more sample events in the SupportPac BA76: WebSphere Business Monitor – Banking Monitor Model.
  
  
• Download IBM product evaluation versions and get your hands on application development tools and middleware products from IBM DB2, Lotus®, Rational, Tivoli®, and WebSphere.
  
  

Discuss

• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

About the authors

Dr. Wilfred C. Jamison is a senior technical manager for the WebSphere Business Monitor development team at the IBM Research Triangle lab. He is currently involved in many projects within the Business Performance Management organization

Jaime Atiles was a technical intern in the WebSphere Business Monitor group. He has a BS in computer engineering from the University of Puerto Rico at Mayaguez and is currently completing an MEng in computer science at Cornell University. His interests include database systems and Web development.

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• .NET overview
• Creating a .NET application
• Running the application
• Extending an existing .NET application
• Summary
• Acknowledgments
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into IT architecture on developerWorks

Special offers