Configuring the e-mail subscription notifier in WebSphere Service Registry and Repository

Examples in this article show you how to limit WSRR service outages by building a subscription notifier to send customized e-mail alerts to subscribed users, and by using the CBE specification to build event messages for use across disparate systems.

Nakul Bharade (nakulb@nz1.ibm.com), International Senior Designer, IBM Sales and Distribution team, IBM

Nakul Bharade is an International Senior Designer and IBM contractor on the IBM Sales and Distribution team in New Zealand. He has several years of experience with WebSphere products, including WebSphere Service Registry and Repository. You can contact Nakul at nakulb@nz1.ibm.com.



31 October 2012

Introduction

Building a customer subscription notifier in IBM® WebSphere® Service Registry and Repository V7.5 or V8 (hereafter called WSRR) enables you to create a custom notification mechanism using a Java® implementation class. Examples in this article show you how to use such notifications to proactively capture inadvertent deactivation of WSRR endpoints or service level agreements, and thereby limit or avoid any potential harm to the service consumer. The article will cover the following topics to show you how to configure and use of a WSRR custom subscription notifier:

  • Description of the WSRR subscription notification framework
  • Steps to build a custom subscription notifier to send e-mail alerts to subscribers
  • Procedure to use Common Base Event specification to promote consistency in the format of subscription notification event alerts. This consistency facilitates the exchange of notification events among disparate systems.

WSRR subscription notification framework

Figure 1 below shows key modules in the WSRR subscription notification framework that are required to send an event notification to a subscribed endpoint:

Figure 1. Key modules of subscription notification framework
Key modules of subscription notification framework

The next section describes the sequence of tasks undertaken by each of the modules in Figure 1, and the roles they play in moving a notification event message from the first origination point (triggered by changes to a subscribed object), to a subscriber end point delivery.

  1. After the Java Messaging Service (JMS) notification plug-in is enabled, it looks for event notification messages generated by certain changes to subscribed objects in WSRR.
  2. The JMS notification plug-in sends event notification messages to the persistent JMS topic SR/*/SubscriptionTopic. For more information on JMS topics in WSRR and their use, see Topics in the WSRR information center.
  3. When enabled, the subscription notifier scheduler task runs periodically to check the JMS Topic for event notification messages relevant to object changes and passes them on to the subscription notifier.
  4. The subscription notifier keeps an internal list of objects that are currently subscribed to. Upon receiving event notifications, it matches the object from the notification message with its internal list of subscribed objects. If a match is found, the Java class implementation of the subscription notifier is invoked, and this implementation may trigger a notification message to a subscriber endpoint.

Building a custom subscription notifier

Here are the high-level steps required to build a custom subscription notifier:

  1. Create a subscription object.
  2. Create subscription notifier implementation Java class.
  3. Load the JAR file into WSRR.
  4. Update the subscription notifier plug-in configuration file.
  5. Enable the subscription notifier scheduler.
  6. Enable the JMS notification.

Each of these steps will be covered in detail below.

Creating custom subscription objects

This section demonstrates the creation of custom subscription object for the following events:

  • Notification event for an update activity triggered on an online Simple Object Access Protocol (SOAP) service endpoint. Online SOAP service endpoints are endpoints that are available for consumption in a given WSRR environment.
  • Notification event when a SOAP service endpoint is taken offline -- in other words, when the endpoint is transitioned from online to offline state using the Governance Profile Lifecycle transition RevokeFromUse.

In the example below, these custom subscription objects will enable the automatic processing of the two events outlined above using a custom Java class. Custom subscription objects will be created using the WSRR REST API.

1. To create a custom subscription object called IBM_service_subscription1 for automatic processing of a notification event triggered following an update activity on an online SOAP service endpoint, use the HTTP POST command as shown in Listing 1 below. If you have multiple instances of WSRR deployed, see Multiple WSRR instances and URLs in the WSRR information center for details on specifying HTTP POST URL in such a configuration.

Tip: You can download the xml and Java files referenced below at the bottom of the article.

Listing 1. REST API command for creating subscription object IBM_service_subscription1 in WSRR
curl -v --insecure -H "Content-Type: application/xml" -X POST "
@C:/Sourcefiles/Create_subscription1.xml" -u wasadmin:wasadmin 
https://localhost:9443/WSRR/7.5/Content/Subscription"

This article uses CURL V7.16. For information on how to download and use CURL, see the CURL web site. Upon successful creation of the subscription object IBM_service_subscription1 using the REST API, a response message is returned that contains the bsrURI of this subscription object, as shown below. This bsrURI identifies the subscription object IBM_service_subscription1 in a WSRR instance.

Listing 2. REST API response showing bsrURI value of IBM_service_subscription1 subscription object
<?xml version="1.0" encoding="UTF-8" ?>
<properties>
  <property name="bsrURI" value="cc1c45cc-26d7-47da.a797.72c35c72971c"/>
</properties>

The body of the Create_subscription1.xml file defines the IBM_service_subscription1 subscription and specifies the conditions under which an event notification message will be generated. The next section describes the elements defined in this file that play an important role when configuring this custom subscription object. For a detailed explanation of the elements of the message body, see Body of a subscription creation message in the REST API in the WSRR information center.

<properties>

The <properties> element contains sub-elements that define the subscription IBM_service_subscription1. The example in Listing 3 below picks up an event notification message for processing if, and only if, an object is a SOAP service endpoint:

Listing 3. IBM_service_subscription1 subscription object properties element
<resources>
  <resource>
    <properties>
      <property name="name" value="IBM_service_subscription1"/>
      <property name="namespace" value="http://www.ibm.com/1.0/SubscriptionSrv1"/>
      <property name="version" value="1.0"/>
      <property name="description" value="Monitors changes to 
          online SOAP service endpoints"/>
      <property name="locale" value="en"/>
      <property name="_targetQuery" value="/WSRR/GenericObject[@sm63_endPointType=
          'SOAPAddress']"/>
      <property name="_notifierType" value="custom" />
      <property name="_endPointReference" value="Other"/>
      <property name="_duration" value="120"/>
      <property name="_correlationID" value="wsgw10942120-sub45021280"/>
      <property name="_notifyPolicyUpdates" value="true"/>
      <property name="_notifyMonitoringPolicyUpdates" value="true"/>
    </properties>    
  </resource>
</resources>

_name

The unique name of the subscription object to be created. In this example, the subscription object IBM_service_subscription1 will be created.

Listing 4. name property for defining custom subscription notifier
<property name="name" value="IBM_service_subscription1"/>

_targetQuery

An XPATH query that defines the set of objects for which event notifications are required. This example indicates that notifications are required for all SOAP service endpoints:

Listing 5. XPATH query for defining SOAP service endpoints
<property name="_targetQuery" 
    value="/WSRR/GenericObject[@sm63_endPointType='SOAPAddress']"/>

_notifierType

Indicates the mechanism to be used for sending event notification messages. This property can take the following values:

  • email -- The messages are sent to a specified e-mail address or addresses.
  • httppost -- The messages are sent to a specified URL.
  • Any other String -- Write your own Java class to process the events.

In the example, this value is set to custom as a custom Java class is implemented. The e-mail notifier that comes with WSRR provides a standard e-mail message template. Writing your own custom e-mail notification Java class lets you compose an e-mail message template that is specific to your organizational needs.

Listing 6. notifierType property for custom subscription notifier
<property name="_notifierType" value="custom" />

_endPointReference

The target end point to which the notification will be sent. In this example, this value is set to other1. The value of this property can be referenced in the Java class implementation of the custom subscription notifier. This value can play an important role in deciding the contents of the message body in situations where a Java class implementation is shared across multiple subscription objects.

Listing 7. _endPointReference property for custom subscription notifier
<property name="_endPointReference" value="Other1"/>

<subscribedOperations> and <targetClassifications>

The <subscribedOperations> element specifies the user operation that would trigger the generation of an event notification message, while the <targetClassifications> element specifies the Uniform Resource Identifier (URI) of a classification for which an event message is to be generated. Listing 8 below shows you how to configure these two together so that the subscription object IBM_service_subscription1 captures an update event on an online SOAP service endpoint. It picks up an event notification message for processing if, and only if, an object classified as Online is updated.

Listing 8. subscribedOperations and targetClassifications properties for subscription object IBM_service_subscription1
<resources>
  <resource>
    <subscribedOperations>
      <subscribedOperation operation="update"/>
    </subscribedOperations>
    <subscribedTransitions/>
    <targetClassifications>
      <targetClassification classification="http://www.ibm.com/xmlns/prod/
          serviceregistry/lifecycle/v6r3/LifecycleDefinition#Online" />
    </targetClassifications>
  </resource>
</resources>

2. Next, confirm the successful creation and configuration of IBM_service_subscription1 subscription object by using the REST API command shown below.

Listing 9. REST API command for querying IBM_service_subscription1 subscription object using bsrURI
curl -v --insecure -H "Content-Type: application/xml" -X GET -u wasadmin:wasadmin 
https://localhost:9443/WSRR/7.5/Metadata/XML/cc1c45cc-26d7-47da.a797.72c35c72971c

The response message returned by the REST API should look like this:

Listing 10. REST API response showing IBM_service_subscription1 subscription object properties in WSRR
<?xml version="1.0" encoding="UTF-8"?>
<resources>
  <resource bsrURI="cc1c45cc-26d7-47da.a797.72c35c72971c" type="Subscription">
    <properties>
      <property name="bsrURI" value="cc1c45cc-26d7-47da.a797.72c35c72971c"/>
      <property name="name" value="IBM_service_subscription1"/>
      <property name="namespace" value="http://www.ibm.com/1.0/SubscriptionSrv1"/>
      <property name="version" value="1.0"/>
      <property name="description" value="Monitors changes to 
          online SOAP service endpoints"/>
      <property name="owner" value="wasadmin"/>
      <property name="lastModified" value="1344381655203"/>
      <property name="creationTimestamp" value="1344380307750"/>
      <property name="lastModifiedBy" value="wasadmin"/>
      <property name="emailAddress" value=""/>
      <property name="locale" value="en"/>
      <property name="targetName" value=""/>
      <property name="targetNamespace" value=""/>
      <property name="targetVersion" value=""/>
      <property name="targetBsrURI" value=""/>
      <property name="_notifyMonitoringPolicyUpdates" value="true"/>
      <property name="_notifyPolicyUpdates" value="true"/>
      <property name="_duration" value="120"/>
      <property name="_endPointReference" value="Other1"/>
      <property name="_targetQuery" value="/WSRR/GenericObject[@sm63_endpointType=
          'SOAPAddress']"/>
      <property name="_expiryStartTime" value="1344381655078"/>
      <property name="_correlationID" value="wsgw10942120-sub45021280"/>
      <property name="_notifierType" value="custom"/>
    </properties>
    <relationships/>
    <classifications/>
    <subscribedOperations>
      <subscribedOperation operation="update"/>
    </subscribedOperations>
    <subscribedTransitions/>
    <targetClassifications>
      <targetClassification classification="http://www.ibm.com/xmlns/prod/
          serviceregistry/lifecycle/v6r3/LifecycleDefinition#Online"/>
    </targetClassifications>
  </resource>
</resources>

3. Next, using the Create_subscription2.xml file, follow Steps 1 and 2 above to create the new custom subscription object IBM_service_subscription2 for automatic processing of a notification event generated when a SOAP service endpoint is taken offline. When configured, this new object should look like this:

Listing 11. Properties of IBM_service_subscription2 subscription object in WSRR
<?xml version="1.0" encoding="UTF-8"?>
<resources>
  <resource bsrURI="c33867c3-1952-423c.b2e0.84494884e0ed" type="Subscription">
    <properties>
      <property name="bsrURI" value="c33867c3-1952-423c.b2e0.84494884e0ed"/>
      <property name="name" value="IBM_service_subscription2"/>
      <property name="namespace" value="http://www.ibm.com/1.0/SubscriptionSrv2"/>
      <property name="version" value="1.0"/>
      <property name="description" value="Monitors for SOAP service endpoints 
          taken offline"/>
      <property name="owner" value="wasadmin"/>
      <property name="lastModified" value="1344382267578"/>
      <property name="creationTimestamp" value="1344382149046"/>
      <property name="lastModifiedBy" value="wasadmin"/>
      <property name="emailAddress" value=""/>
      <property name="locale" value="en"/>
      <property name="targetName" value=""/>
      <property name="targetNamespace" value=""/>
      <property name="targetVersion" value=""/>
      <property name="targetBsrURI" value=""/>
      <property name="_notifyMonitoringPolicyUpdates" value="true"/>
      <property name="_notifyPolicyUpdates" value="true"/>
      <property name="_duration" value="120"/>
      <property name="_endPointReference" value="Other2"/>
      <property name="_targetQuery" value="/WSRR/GenericObject[@sm63_endpointType=
          'SOAPAddress']"/>
      <property name="_expiryStartTime" value="1344382267562"/>
      <property name="_correlationID" value="wsgw10942121-sub45021281"/>
      <property name="_notifierType" value="custom"/>
    </properties>
    <relationships/>
    <classifications/>
    <subscribedOperations>
      <subscribedOperation operation="Transition"/>
    </subscribedOperations>
    <subscribedTransitions>
      <subscribedTransition transition="http://www.ibm.com/xmlns/prod/
          serviceregistry/lifecycle/v6r3/LifecycleDefinition#RevokeFromUse"/>
    </subscribedTransitions>
    <targetClassifications>
      <targetClassification classification="http://www.ibm.com/xmlns/prod/
          serviceregistry/lifecycle/v6r3/LifecycleDefinition#Offline"/>
    </targetClassifications>
  </resource>
</resources>

At the end of step 3, two custom subscription objects required for automatic processing of the two subscription notification events identified at the beginning of this section have been successfully created.

Creating a subscription notifier implementation class

This section shows you how to create a subscription notifier implementation Java class. This class contains the code that processes event notifications triggered from the two subscription objects IBM_service_subscription1 and IBM_service_subscription2.

  1. Open your Java development environment. This article uses WSRR Studio, which is strongly recommend WSRR-related Java development.
  2. Create a new Java project called CustomSubscriptionNotifier in the WSRR Studio Java perspective.
  3. Include following JAR files in this project's build path:
    • ServiceRegistryClient.jar, located in the <WSRR_HOME> directory.
    • sdo-int.jar, located in the <WSRR_HOME> directory.
    • com.ibm.ws.admin.client_7.0.0.jar, located in the <WAS_HOME>/runtimes directory.
    • com.ibm.we.webservices.thinclient_7.0.0.jar, located in the <WAS_HOME>/runtimes directory.
    • com.ibm.jaxws.thinclient_7.0.0.jar, located in the <WAS_HOME>/runtimes directory.
    • mail.jar (V1.4.2), from attached zip file below.
    • mailapi.jar (V1.4.2), from the attached zip file below.

    For more information on the mail.jar and mailapi.jar files, see JavaMail API R1.4.2. on oracle.com

  4. In this step, create the Java class com.ibm.sr.subscriptionnotifier.plugin.custom.CustomNotifierPlugin, which implements the com.ibm.serviceregistry.subscriptionnotifier.Plugin interface. For a list of the methods defined in the com.ibm.serviceregistry.subscriptionnotifier.Plugin interface, see Creating a subscription notifier implementation class in the WSRR information center.

    Listing 12 shows an extract of code taken from processEvent method of com.ibm.sr.subscriptionnotifier.plugin.custom.CustomNotifierPlugin class in the CustomNotifierPlugin .java file. It shows you how to use the WSRR API to retrieve the following properties of the SOAP Service Endpoint object that triggered the notification event:

    • Object Name
    • Object Version
    • Object Namespace
    • Object BsrUri
    • End Point Reference value of Subscription Object (used to define the subject of e-mail alert)
    • Event Type in WSRR that triggered this event notification
    • Transition Name (published with Transition events only)
    • Status of the SOAP Service Endpoint object captured during the notification event
    • Environment in which the SOAP Service Endpoint is available
    • Object URL pointing to the SOAP Service Endpoint in WSRR

    For a complete code listing, see the Java files provided with this article.

    Listing 12. Code extract taken from processEvent method of CustomerNotifierPlugin Java implementation class
    StringBuffer strBuff = new StringBuffer();
    //Retrieve type of Object that triggered this event.
    objPrimaryType = arg0.getDescriptor().getGenericObjectPrimaryType();
    //Check if object type is SOAP service endpoint.
    if(objPrimaryType.equals(GENERICOBJ_SOAPSERVICEENDPOINT)){
        strBuff.append("Object Type: SOAPServiceEndpoint");
        strBuff.append(NEWLINE);
      }//End of if.
    //Retrieve name of object that triggered this event.
    strBuff.append("Object Name: ");
    strBuff.append(arg0.getTargetName());		
    //Retrieve version of object that triggered this event.
    strBuff.append("Object Version: ");
    strBuff.append(arg0.getTargetVersion());
    //Retrieve namespace of object that triggered this event.
    strBuff.append("Object Namespace: ");
    strBuff.append(arg0.getTargetNamespace());
    //Retrieve BsrUri of object that triggered this event.
    strBuff.append("Object BsrUri: ");
    String bsrURI = arg0.getTargetBsrUri();
    strBuff.append(bsrURI);
    //Retrieve end point reference value associated with subscription object.
    String endPointReference = arg0.getSubEPR();
    //Retrieve type of event generated.
    strBuff.append("Event Type: ");
    String eventType = arg0.getDescriptor().getEvent();
    strBuff.append(eventType);
    //Get transition name if event type == "TRANSITION".
    if(eventType.equals(EVENT_TRANSITION)){
      String transitionName = arg0.getDescriptor().getTransition();
      if(transitionName.equals(TRANSITION_REVOKEFROMUSE)){
          strBuff.append("Transition Name: ");           
          strBuff.append("RevokeFromUse");
          strBuff.append(NEWLINE);
        }
     }

    In this example, the value of wc_defaulthost_secure port has been hard-coded. But in a production like scenario, the following options are recommended:

  5. Next, this project is exported to CustomSubscriptionNotifier.jar file.

Now that the subscription notifier implementation JAR file has been developed, the next step is to load it into a WSRR instance.

Loading a subscription notifier JAR file

The subscription notifier CustomSubscriptionNotifier.jar contains the com.ibm.sr.subscriptionnotifier.plugin.custom.CustomNotifierPlugin Java class that performs the required actions in response to subscription notification events associated with the subscribed objects IBM_service_subscription1 and IBM_service_subscription2. Load this JAR file into WSRR using the web UI.:

  1. Switch to the Configuration perspective, if necessary, by selecting Configuration in the Perspective list.
  2. Click Active Profile => Plug-in JARS.
  3. Click Load JAR Plug-in.
  4. Click Browse, select CustomSubscriptionNotifier.jar, and click Open.
  5. Provide the plug-in JAR name CustomSubscriptionNotifier.
  6. Click OK to load the file.

To understand the different ways to load a JAR file into the WSRR instance, see Loading a subscription notifier JAR file in the WSRR information center.

Updating the subscription notifier plug-in configuration file

Now that the subscription notifier JAR file has been uploaded to the WSRR instance, the next task is to update the subscription notifier plug-in configuration file to reflect the subscription notifier Java implementation class.

The subscription notifier type is custom; when an event notification is triggered from a Subscription object whose _notifierType property has the value custom, the Java class com.ibm.sr.subscriptionnotifier.plugin.custom.CustomNotifierPlugin is invoked. The plug-in identifier CustomPlugin001 is a string that uniquely identifies the custom subscription notifier implementation class.

Listing 13. Subscription notifier plug-in configuration file showing our custom subscription notifier Java implementation class
<p:PluginSpace targetNamespace="http://tempuri.org" xmlns:p="http://www.ibm.com/xmlns/
    prod/serviceregistry/SubscriptionNotifierPlugin" xmlns:xsi="http://www.w3.org/2001/
    XMLSchema-instance" xsi:schemaLocation="http://www.ibm.com/xmlns/prod/
    serviceregistry/SubscriptionNotifierPlugin ../subscriptionNotifierPluginModel/
    subscriptionNotifierPluginConfiguration.xsd ">
  <Plugin identifier="com.ibm.sr.subscriptionnotifier.plugin.email.EmailNotifierPlugin"
      class="com.ibm.sr.subscriptionnotifier.plugin.email.EmailNotifierPlugin" 
      type="email" />
  <Plugin identifier="com.ibm.sr.subscriptionnotifier.plugin.httppost.
      HttpPostNotifierPlugin" class="com.ibm.sr.subscriptionnotifier.plugin.httppost.
      HttpPostNotifierPlugin" type="httppost" />
  <Plugin identifier="CustomPlugin001" class="com.ibm.sr.subscriptionnotifier.plugin.
      custom.CustomNotifierPlugin" type="custom" />
</p:PluginSpace>

Enabling the subscription notifier scheduler

The default Governance Enablement Profile contains a subscription notifier plug-in scheduler entry called SubscriptionNotifierPluginScheduler. This scheduler entry defines a subscription notifier plug-in scheduled task that is turned off by default. To use the subscription notifier plug-in framework, you must enable the scheduled task. The subscription notifier CustomSubscriptionNotifier is activated by enabling a WSRR scheduled task. Listing 14 shows the subscription notifier scheduler:

Listing 14. XML listing of subscription notifier scheduler when enabled in WSRR
<scheduler-configuration 
    xmlns="http://www.ibm.com/xmlns/prod/serviceregistry/6/1/SchedulerProperties">
  <scheduler-task name="SubscriptionNotifierPluginMessageTask">
    <type>Message</type>
    <subscriptions><topic>jms/SubscriptionTopic</topic></subscriptions>
    <interval>30</interval>
    <class>com.ibm.sr.subscriptionnotifier.plugin.SubscriptionNotifier
        PluginMessageTask</class>
    <enabled>true</enabled>
    <startTimeOffset>10</startTimeOffset>
    <intervalGranularity>seconds</intervalGranularity>          
    <startTimeOffsetGranularity>seconds</startTimeOffsetGranularity>
    <transactionality>perMessage</transactionality>
  </scheduler-task>
</scheduler-configuration>

The following elements in the default subscription notifier scheduler SubscriptionNotifierPluginScheduler have been updated:

  • <enabled> -- Controls whether the promotion scheduled task is enabled. The value of this element must be true or false. This value is set to true, thereby enabling the scheduled task.
  • <interval> -- Interval at which the scheduled task is executed. The time unit depends on the value of the <intervalGranularity> element. This value is set to 30 and the <intervalGranularity> value to seconds, indicating that the scheduled task will be executed every 30 seconds.
  • <startTimeOffset> -- Time delay after which the scheduled task begins processing. The time unit depends on the value of the <startTimeOffsetGranularity> element. This value is set to 10 and the <startTimeOffsetGranularity> value to seconds, indicating that the scheduled task will begin processing after 10 seconds.
  • <intervalGranularity> -- Time unit associated with the <interval> element. This value is set to seconds, indicating that the <interval> will be interpreted in seconds.
  • <startTimeOffsetGranularity> -- Time unit associated with the <startTimeOffset> element. This value is set to seconds, indicating that the <startTimeOffset> will be interpreted in seconds.

For more information on the WSRR Scheduler framework and the various XML configuration elements see Scheduler framework in the WSRR information center.

Enabling the JMS notification

Event notification messages that will be processed by the subscription notifier CustomSubscriptionNotifier are sent to the JMS queue. Therefore it is important that JMS notification is enabled. JMS notification configuration settings are stored in the notification properties configuration file. To enable JMS notification using the web UI, complete the following steps:

  1. Open the WSRR web UI.
  2. Switch to the Configuration perspective if necessary, by selecting Configuration in the Perspective list.
  3. Click Active Profile => Notifiers.
  4. Click Notification properties plug-in.
  5. Ensure that the notifiers and governanceNotifiers property settings include the entry com.ibm.sr.api.ServiceRegistryNotifierJMS, as shown below:
    Listing 15. Registering the JMS notification plug-in
    notifiers=com.ibm.sr.ale.wsrr.ALENotifier,com.ibm.sr.api.ServiceRegistryNotifierJMS
    governanceNotifiers=
        com.ibm.sr.ale.wsrr.ALENotifier,com.ibm.sr.api.ServiceRegistryNotifierJMS
  6. Ensure that the jmsNotification property setting has the enabled flag set to true. For example:
    Listing 16. Enabling the JMS notification plug-in
    jmsNotification=true,7
  7. Click OK to save your changes

Loading the sample WSDL file

Now that the customer subscription notifier has been configured, the next step is to load the sample WSDL file using the WSRR Web UI:

  1. Switch to the Development perspective if necessary, by selecting Development in the Perspective list.
  2. Click Actions > Load Documents
  3. Click Browse, select SampleWSDL.wsdl WSDL file, and click OK to load the file.

After the sample WSDL file is uploaded, for the sake of demonstration purposes, add the environment classification as specified in Table 1 below to the SOAP service endpoint http://www.ibm.com/ibm/services/Address. You must add this environment classification prior to pushing the SOAP service endpoint for consumption. Once added, it will indicate that the SOAP service endpoint belongs to the development environment. For instructions on how to add a classification to an object, see Add classifications in the WSRR information center.

Table 1. Governance Profile Taxonomy for development environment
SystemNameURI
Governance Profile TaxonomyDevelopment

Next, perform the ApproveForUse transition to move the SOAP service endpoint to online state. Once successful, the SOAP service endpoint is now available for consumers to use. From here on, the following two changes to the SOAP Service Endpoint will trigger notifications to subscribed end users:

  1. Any update to the SOAP service endpoint. As an example, update the Description property on the SOAP service endpoint. The custom subscription notifier CustomSubscriptionNotifier (built using Java files shared with this article) will trigger an e-mail alert as shown in listing below. The subject of this e-mail alert would resemble the pattern <environment_name>: <severity> WSRR Notification. In this example, the environment name would be Development and severity **WARNING**.
    Listing 17. Custom e-mail message sent in response to updating our (online) SOAP service endpoint in WSRR
    Object Type: SOAPServiceEndpoint
    Object Name: <a href="http://www.ibm.com/ibm/services/Address">\<code type="inline">
        http://www.ibm.com/ibm/services/Address</code></a>
    Object Version: 1.0
    Object Namespace: <a href="http://www.ibm.com/Address_Service"><code type="inline"
        >http://www.ibm.com/Address_Service</code></a>
    Object BsrUri: 3df8b73d-4124-4455.9ba3.ab1ab5aba341
    Event Type: UPDATE
    Status: Online
    Environment: Development
    Object URL: <a href="https://localhost:9443/ServiceRegistry/ViewDetail.do?
        uri=3df8b73d-4124-4455.9ba3.ab1ab5aba341"><code 
        type="inline">https://localhost:9443/ServiceRegistry/ViewDetail.do?
        uri=3df8b73d-4124-4455.9ba3.ab1ab5aba341</code></a>

    In the Java class com.ibm.sr.subscriptionnotifier.plugin.custom.CustomNotifierPlugin, the IBM_service_subscription1 subscription object's endpoint reference property is used to customize the subject of a notification e-mail alert message.

    Listing 18. Alert severity set in an e-mail using IBM_service_subscription1 subscription object's _endPointReference property
    //Check if the event was generated by IBM_service_subscription1.  
    static final String EPR1 = "Other1";
    if(endPointReference.equals(EPR1)){
      //Set the event severity to WARNING.
        eventSeverity = "**WARNING**";
     }
  2. Transition of the SOAP service endpoint from online to offline by performing a RevokeFromUse transition, indicating that it is no longer available for consumption. The custom subscription notifier CustomSubscriptionNotifier (built using the Java files provided with this article) triggers an e-mail alert, as shown in listing below. The subject of this e-mail alert follows the pattern <environment_name>: <severity> WSRR Notification. In this example, the environment name is Development and the severity is **Critical**:
    Listing 19. Custom e-mail message sent in response to taking our (online) SOAP service endpoint offline in WSRR
    Object Type: SOAPServiceEndpoint
    Object Name: http://www.ibm.com/ibm/services/Address
    Object Version: 1.0
    Object Namespace: http://www.ibm.com/Address_Service
    Object BsrUri: 3df8b73d-4124-4455.9ba3.ab1ab5aba341
    Event Type: TRANSITION
    Transition Name: RevokeFromUse
    Status: Offline
    Environment: Development
    Object URL: https://localhost:9443/ServiceRegistry/ViewDetail.do?
        uri=3df8b73d-4124-4455.9ba3.ab1ab5aba341

    In the Java class com.ibm.sr.subscriptionnotifier.plugin.custom.CustomNotifierPlugin, the IBM_service_subscription2 subscription object's endpoint reference property is used to customize the subject of a notification e-mail alert:

    Listing 20. Alert severity set in an e-mail using IBM_service_subscription2 subscription object's _endPointReference property
    //Check if the event was generated by IBM_service_subscription2. 
    static final String EPR2 = "Other2";
    if(endPointReference.equals(EPR2)){
        //Set the event severity to CRITICAL.
        eventSeverity = "**CRITICAL**";
     }

The two examples of event notifications shown above highlight the use of proactive alerts to:

  • Monitor events triggered by updates to online SOAP service endpoints. These alerts can be used by operational teams to capture any unintended updates to such endpoints.
  • Monitor events triggered as a result of taking the SOAP service endpoints offline. These alerts can be used by operational teams to instantly capture inadvertent deactivation of endpoints, and thereby limit or avoid any potential harm to the service consumer.

Now that the custom subscription notifier has been built, the next section will show you how to incorporate such subscription notification events into the IBM Common Base Event specification.

Using the Common Base Event (CBE) specification

The CBE is a standard XML data model for events that may be consumed by business enterprise applications. CBE offers consistency of data elements and the format of those elements, thus promoting effective communication between disparate enterprise systems that support logging and problem management functions across an enterprise.

Listing 21 below shows how a WSRR subscription notification event can be converted into a CBE-formatted event by incorporating the conversion logic into the processEvent method of a custom subscription notifier's Java implementation class. You can then use the subscription notification message matching the CBE specification for the exchange of such alerts across disparate systems, and you can extend this concept to build a robust subscription notification messaging framework using the CBE specification.

Listing 21. CBE message for a custom subscription notification event generated in response to taking a SOAP service endpoint offline
<?xml version="1.0" encoding="UTF-8"?>
<CommonBaseEvents xmlns="http://www.ibm.com/AC/commonbaseevent1_0_1" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <CommonBaseEvent creationTime="2012-09-10T09:30:47.0Z" globalInstanceId="ID000001" 
      elapsedTime="" repeatCount="0" sequenceNumber="1" extensionName=
      "WSRRSubscriptionNotifierEvent" msg="SOAP Service Endpoint subscriber notification
      event" severity="50" priority="90" version="1.0.1">
    <contextDataElements/>
    <extendedDataElements type="string" name="WSRRSubscriptionNotifierEvent">
      <AuditMsg>
        <WSRRObjectDetails>
          <Name>http://www.ibm.com/ibm/services/Address</Name>
          <Version>1.0</Version>
          <Namespace>http://www.ibm.com/Address_Service</Namespace>
          <BsrUri>3df8b73d-4124-4455.9ba3.ab1ab5aba341</BsrUri>
          <Status>Offline</Status>
          <EventType>Transition</EventType>
          <TransitionName>RevokeFromUse</TransitionName>
          <Environment>Development</Environment>
          <ObjectURI>https://localhost:9443/ServiceRegistry/ViewDetail.do?uri=
              3df8b73d-4124-4455.9ba3.ab1ab5aba341</ObjectURI>
        </WSRRObjectDetails>
      </AuditMsg>
    </extendedDataElements>
    <associatedEvents/>
    <reporterComponentId componentIdType="ServiceName" subComponent=
        "Custom Subscription Event Notifier" instanceId="1" locationType="Hostname" 
        executionEnvironment="Windows XP[x86]" component="WSRR Event Notifier" 
        location="localhost" application="WSRRv7.5" componentType="WSRR "/>
    <sourceComponentId componentIdType="Application" subComponent=
        "SOAP Service Endpoint Object" instanceId="1" locationType="Hostname" 
        executionEnvironment="Windows XP[x86]" component="WSRR Objects" 
        location="localhost" application="WSRRv7.5" componentType="WSRR"/>
    <msgDataElement msgLocale="en_US">
      <msgId>WSRRSNE0001</msgId>
      <msgIdType>Unknown</msgIdType>
      <msgCatalogId>WSRRSNE0001</msgCatalogId>
      <msgCatalogType>Subscription Notification Events</msgCatalogType>
      <msgCatalog>com.ibm.sr.subscriptionnotifier.plugin.custom.
          CustomNotifierPlugin</msgCatalog>
    </msgDataElement>
    <situation categoryName="OtherSituation">
      <situationType xsi:type="OtherSituation" reasoningScope="EXTERNAL">
        WSRRv7.5 SOAP Service Endpoint Subscription Notification Event.
      </situationType>  
    </situation>
  </CommonBaseEvent>
</CommonBaseEvents>

Table 2 below highlights some of the key CBE message elements and their values from the sample CBE XML above.

Table 2. Key WSRR-related CBE elements configured in sample CBE message above
Property NameValueDescription
severity30 for an online SOAP Service endpoint update event.
50 for when an online SOAP Service endpoint is taken offline (transition event)
The perceived status of the event is described with respect to the application that is reporting the event. The predefined severity levels are 30 (Warning), which means the user must decide if an action is necessary in response to the event, and 50 (Critical), which means the user must decide on an immediate course of action.
Priority70 for an online SOAP Service Endpoint update event.
90 for when an online SOAP Service Endpoint is taken offline.
Importance of event. A predefined value of 70 represents a high priority event while 90 represents a critical event.
/extendedDataElements/ AuditMsg/ WSRRObjectDetails/Namehttp://www.ibm.com/ibm/services/AddressName of WSRR object that triggered this event. In the example above, this is the Address Soap service endpoint (referred to as Address henceforth).
/extendedDataElements/ AuditMsg/ WSRRObjectDetails/Version1.0Version of Address endpoint that triggered this event.
/extendedDataElements/ AuditMsg/ WSRRObjectDetails/Namespacehttp://www.ibm.com/Address_ServiceNamespace of Address endpoint that triggered this event.
/extendedDataElements/ AuditMsg/ WSRRObjectDetails/BsrUri3df8b73d-4124-4455.9ba3.ab1ab5aba341BsrURI of Address endpoint that triggered this event. BsrURI value provides a unique representation of this object in WSRR and can be viewed as a primary key to this object.
/extendedDataElements/ AuditMsg/ WSRRObjectDetails/StatusOfflineStatus of the Address endpoint at the time this event was triggered. In the example above, this value is offline indicating that this endpoint is no longer available to consumers.
/extendedDataElements/ AuditMsg/ WSRRObjectDetails/EventTypeTransitionEvent associated with WSRR object that triggered this notification alert. In the example above, the Address endpoint went through a transition event.
/extendedDataElements/ AuditMsg/ WSRRObjectDetails/TransitionNameRevokeFromUseTransition state associated with WSRR object's transition event. In the example above, the Address endpoint was transitioned through RevokeFromUse state.
/extendedDataElements/ AuditMsg/ WSRRObjectDetails/EnvironmentDevelopmentService provider's environment that the WSRR object belongs to. In the example above, the Address object belongs to Development environment.
/extendedDataElements/ AuditMsg/ WSRRObjectDetails/ObjectURIhttps://localhost:9443/ServiceRegistry/
ViewDetail.do?uri=3df8b73d-
4124-4455.9ba3.ab1ab5aba341
URL of WSRR Address endpoint. It can be used to access the Address endpoint in a given WSRR instance without having to search for it by using query wizard or named queries.
/msgDataElement/msgIdWSRRSNE0001Specifies the unique message identifier value of the event. It can be used to identify the message in the message catalog.
/msgDataElement/msgCatalogIdWSRRSNE0001Acts as an index for the message that is used for resolving message text from a message catalog.
/msgDataElement/msgCatalogTypeSubscription Notification EventsSpecifies the meaning and format of message catalog.
/msgDataElement/msgCatalogcom.ibm.sr.subscriptionnotifier.plugin.
custom.CustomNotifierPlugin
Qualified name of the message catalog that contains the translated message specified by the msgCatalogId property.

Conclusion

This article showed you how to build a subscription notifier in WSRR to send customized e-mail alerts to subscribed users. It also showed you how to use the CBE specification to build a consistent notification event message for use across disparate systems. You can extend the custom subscription notifiers to build subscription notification events that meet the CBE specification and can be processed and persisted on WebSphere MQ queues or stored in databases to meet logging requirements. You can also extend custom subscription notifiers to send Short Message Service (SMS) alerts to subscribed users by implementing a Short Message Peer-to-Peer (SMPP) client. This article showed you how to use these alerts proactively to capture inadvertent deactivation of WSRR endpoints or service level agreements, and thus avoid or limit service outages.

Acknowledgements

The author would like to acknowledge Steve Groeger for his thorough review of this article, and Andrew Leonard for his review of the subscription notification framework described in this article. Both Steve and Andrew work on the IBM WSRR Product Development team.


Download

DescriptionNameSize
Code sampleSourcefiles.zip613 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=844485
ArticleTitle=Configuring the e-mail subscription notifier in WebSphere Service Registry and Repository
publish-date=10312012