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:

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.

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.

<?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:

<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.

<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:

<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.

<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.

<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.

<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.

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:

<?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:

<?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:

   • Caching this port information. For information on caching custom properties, see the developerWorks article Using resource environment providers in WebSphere Application Server.
   • Extending a plug-in with the user configuration. For information on implementing this solution, see Extending a plug-in with a user configuration in the WSRR information center.
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.

<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:

<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.

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.

<?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.

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.

Back to top

Download

Information about download methods

Resources

• WebSphere Service Registry and Repository resources
  • WSRR V7.5 information center
    A single Web portal to all WSRR V7.5 documentation, with conceptual, task, and reference information on installing, configuring, and using WSRR.
  • WSRR V8 information center
    A single Web portal to all WSRR V8 documentation, with conceptual, task, and reference information on installing, configuring, and using WSRR.
  • Using resource environment providers in WebSphere Application Server
    A developerWorks article on using resource environment providers in WebSphere Application Server.
  • JavaMail API R1.4.2
    Information on the JavaMail API on oracle.com.
  • CURL
    Information on CURL.
  • WebSphere Service Registry and Repository information center
    A single Web portal to all WebSphere Service Registry and Repository documentation, with conceptual, task, and reference information to help you install, configure, and use the product.
  • WebSphere Service Registry and Repository product page
    Product descriptions, product news, training information, support information, and more.
  • WebSphere Service Registry and Repository requirements
    Hardware and software requirements.
  • Getting started with WebSphere Service Registry and Repository
    This developerWorks article shows you how to populate WebSphere Service Registry and Repository with existing Web services information.
  • YouTube channel: WebSphere Service Registry and Repository demos
    These short video demos show you how to complete several key service governance tasks using WebSphere Service Registry and Repository.
  • WebSphere Service Registry and Repository Information Portal
    This wiki provides an alternative portal for quick access to a wide variety of WebSphere Service Registry and Repository resources, and also makes it easy for you to give feedback on the product.
  • IBM Redbook: WebSphere Service Registry and Repository Handbook
    This IBM Redbook discusses the architecture and functions of Service Registry, along with sample integration scenarios that you can use to implement Service Registry in an SOA.
  • WebSphere Service Registry and Repository support
    A searchable database of support problems and their solutions, plus downloads, fixes, and problem tracking.
  
  
• WebSphere resources
  • developerWorks WebSphere developer resources
    Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
  • developerWorks WebSphere application integration developer resources
    How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application integration and business integration solutions.
  • Most popular WebSphere trial downloads
    No-charge trial downloads for key WebSphere products.
  • WebSphere forums
    Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
  • WebSphere on-demand demos
    Download and watch these self-running demos, and learn how WebSphere products and technologies can help your company respond to the rapidly changing and increasingly complex business environment.
  • WebSphere-related articles on developerWorks
    Over 3000 edited and categorized articles on WebSphere and related technologies by top practitioners and consultants inside and outside IBM. Search for what you need.
  • developerWorks WebSphere weekly newsletter
    The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
  • WebSphere-related books from IBM Press
    Convenient online ordering through Barnes & Noble.
  • WebSphere-related events
    Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
  
  
• developerWorks resources
  • Trial downloads for IBM software products
    No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
  • developerWorks business process management developer resources
    BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
  • developerWorks blogs
    Join a conversation with developerWorks users and authors, and IBM editors and developers.
  • developerWorks tech briefings
    Free technical sessions by IBM experts to accelerate your learning curve and help you succeed in your most challenging software projects. Sessions range from one-hour virtual briefings to half-day and full-day live sessions in cities worldwide.
  • developerWorks podcasts
    Listen to interesting and offbeat interviews and discussions with software innovators.
  • developerWorks on Twitter
    Check out recent Twitter messages and URLs.
  • IBM Education Assistant
    A collection of multimedia educational modules that will help you better understand IBM software products and use them more effectively to meet your business requirements.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• WSRR subscription notification framework
• Building a custom subscription notifier
• Using the Common Base Event (CBE) specification
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Service Registry and Repository
• Article: WebSphere Service Registry and Repository
• Buy: WebSphere Service Registry and Repository

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers