Eventing and Notifications with WSO2 Governance Registry

Curated on 12th March 2012

This article updated to the current version (4.1.1) of WSO2 Governance Registry.

Introduction

The WSO2 Governance Registry is designed to manage data in a web-friendly and community-enabled manner. Users are given the ability to not only store service descriptions, policies and other service-specific meta information, but also images, text files and office documents. The WSO2 Governance Registry also provides a simple RESTful remote interface which uses the Atom Publishing Protocol (powered by Apache Abdera). More information on the WSO2 Governance Registry can be found in here.

Users as well as Systems often want to receive messages when there is a change in an application. Such changes can trigger events which will contain useful information for interested users and systems. Such events (or messages) would often be generated at some point in time that is often unknown in advance or which changes over time. Therefore, a mechanism for registering interest is a definite requirement. Web Services Eventing (WS-Eventing) is a specification that defines a protocol for one Web Service (called a subscriber) to register interest (called a subscription) with another Web Service (called an event source) in receiving messages about events (called notifications or event messages). The subscriber may manage the subscription by interacting with a Web Service (called the subscription manager) designated by the event source, [1].

The WSO2 Governance Registry takes this one step forward by allowing Web Services (or systems) as well as users create subscriptions. The Web Services are presented with an easy to use API, where as users are offered a simple and easy to understand web based user interface. Further more, the notifications may delivered in a wide variety of formats including SOAP and POX (Plain Old XML) messages and also as E-mails.

Applies To

Contents

1. Introduction
2. Creating Subscriptions
3. Retrieving Status of Subscriptions
4. Deleting Subscriptions
5. Managing Notifications
6. Configuring the WSO2 Governance Registry to send E-mails
7. Pre-Defined Event Types
8. Topics used to Subscribe
9. API-Level Access
10. Summary

Creating Subscriptions

The WSO2 Governance Registry supports two main methods of creating subscriptions.

Method 1: Subscriptions can be made via the WSO2 Governance Registry Administration Console.

This can be done by,

Step 1: Browse the Resource/Collection on the WSO2 Governance Registry

Step 2: Expand the Subscriptions portlet, and click on Add Subscription which will bring up the user interface

Step 3: Select the Event Type, and Notification Method, and fill in the corresponding E-mail address, Web Service URL or User Name

Step 4: Click on the Subscribe button to confirm the subscription

Method 2: Subscription requests can be made according to the WS-Eventing specification, [2] to the dedicated subscription manager available at the endpoint https://localhost:9763/services/RegistryEventingService. Please note that the hostname and port may vary according to the present server configuration.

Retrieving Status of Subscriptions

Once having made the subscriptions, the WSO2 Governance Registry provides two main methods for querying for the available set of subscriptions.

Method 1: The WSO2 Governance Registry Administration Console lists the available subscriptions based on the access rights of the logged-in user.

Step 1: Browse the Resource/Collection on the WSO2 Governance Registry

Step 2: Expand the Subscriptions portlet, and the list of subscriptions made should be visible

Method 2: Get Status requests can be made according to the WS-Eventing specification, [2] to the dedicated subscription manager available at the endpoint https://localhost:9763/services/RegistryEventingService. The subscription identifier returned upon subscription is required for performing the Get Status request.

Deleting Subscriptions

The WSO2 Governance Registry supports two main methods of deleting subscriptions.

Method 1: Subscriptions can be deleted via the WSO2 Governance Registry Administration Console.

This can be done by,

Step 1: Browse the Resource/Collection on the WSO2 Governance Registry

Step 2: Expand the Subscriptions portlet, and the list of subscriptions made should be visible

Step 3: Delete the corresponding subscription by clicking on the Delete link, which will prompt you with a message requesting a confirmation to delete the subscription

Method 2: Unsubscribe requests can be made according to the WS-Eventing specification, [2] to the dedicated subscription manager available at the endpoint https://localhost:9763/services/RegistryEventingService. The subscription identifier returned upon subscription is required for performing the Unsubscribe request. A confirmation response will be returned upon unsubscription, and subsequent get status requests made for the same subscription identifier will fail as a result.

Managing Notifications

The WSO2 Governance Registry also allows administrators to Manage Notifications. This functionality is available via the Administration Console's Notification Management Page (Govern --> Notifications). More information on how to manage notifications is found in here. The WSO2 Governance Registry Resource Browser displays subscriptions made on a per resource (or collection basis), where as the Notification Management Page lists subscriptions made within the entire registry based on the logged-in user's access rights.

In addition to being able to delete notifications, this page also allows administrators to edit subscriptions without having to delete and recreate the subscriptions. Clicking on the Modify button will ensure that the current subscription is updated with the new information.

Configuring the WSO2 Governance Registry to send E-mails

The WSO2 Governance Registry requires to be configured in order to send notifications via E-mail. This is simple as editing the GREG_HOME/conf/axis2_client.xml and adding the following mail transport configuration.

    <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
        <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
        <parameter name="mail.smtp.port">587</parameter>
        <parameter name="mail.smtp.starttls.enable">true</parameter>
        <parameter name="mail.smtp.auth">true</parameter>
        <parameter name="mail.smtp.user">USERNAME</parameter>
        <parameter name="mail.smtp.password">PASSWORD</parameter>
        <parameter name="mail.smtp.from">[email protected]</parameter>
    </transportSender>

This will cause each E-mail to be sent to the corresponding delivery address present in the subscription, using [email protected] as the sender. This configuration is meant for an E-mail address obtained from gmail.com. Similarly, any other sender E-mail address for which the E-mail service provider grants access to a SMTP Server, can be used to send E-mail. More information on the Apache Axis2 Mail Transport can be found in here.

Pre-Defined Event Types

The WSO2 Governance Registry contains a number of pre-defined event types that become available according to the resource (or collection) location to which you attempt to make a subscription. Following types of events are available as pre-defined event types for any resource or collection.

1. Create Child - Represents an event of creating a resource (or collection) within the related collection.
2. Delete Child - Represents an event of deleting a resource (or collection) within the related collection.
3. Delete - Represents an event of deleting the related resource (or collection).
4. Update - Represents an event of updating the related resource (or collection).
5. Check LC Item - Represents an event that fires when a item is checked in a lifecycle check-list of the related resource (or collection).
6. Uncheck LC Item - Represents an event that fires when a item is unchecked in a lifecycle check-list of the related resource (or collection).
7. Create LC - Associate a LC to the related resource (or collection).
8. Delete LC - Remove associated LC from the related resource (or collection).
9. Change LC state - Promote or Demote the associated LC state of the related resource (or collection).

Topics used to Subscribe

If you choose to subscribe by making a SOAP call to the dedicated subscription manager endpoint of the WSO2 Governance Registry according to the WS-Eventing specification, you will need to specify the topic which will be used to filter the subscribed endpoints to which the notifications must be sent for each event generated. This is achieved by adding a Filter to the subscription request. This filter must be in the following format.

    <wse:Filter Dialect="https://wso2.org/registry/notify">TOPIC</wse:Filter>

The TOPIC should be of the following format.

    TOPIC := RESOURCE_PATH/EVENT_NAME

The RESOURCE_PATH would be / for the root collection and it will be /system for the system collection. Therefore, the Topic for the XYZ event generated for an operation performed at the root collection would be //XYZ and the event generated for an operation performed at the system collection would be /system/XYZ. The topics corresponding to the pre-defined event types for collections are as follows.

1. Create Child - ChildCreated
2. Delete Child - ChildDeleted
3. Delete - CollectionDeleted
4. Update - CollectionUpdated
5. Check LC Item - CheckListItemChecked
6. Uncheck LC Item - CheckListItemUnchecked
7. Create LC - LifeCycleCreated
8. Delete LC - LifeCycleDeleted
9. Change LC state - LifeCycleStateChanged

The topics corresponding to the pre-defined event types for resources are as follows.

1. Delete Resource- ResourceDeleted
2. Update Resource- ResourceUpdated
3. Check LC Item - CheckListItemChecked
4. Uncheck LC Item - CheckListItemUnchecked
5. Create LC - LifeCycleCreated
6. Delete LC - LifeCycleDeleted
7. Change LC state - LifeCycleStateChanged

It is essential that each subscription would be made to a valid topic or if not the notifications will not be delivered.

API-Level Access

The WSO2 Governance Registry also allows API-Level access to its embedded subscription manager via an OSGi Service. This service can be used to

1. Create Subscriptions
2. Delete Subscriptions
3. Retrieve Subscriptions
4. Obtain a reference to the Subscription Manager instance
5. Get Subscription Manager URL
6. Generate Notification
7. Register Event Type
8. Obtain Registered Event Types
9. Exclude an Event for a given Resource Path
10. Obtain the Resource Paths for which a given Event Type is excluded

The Eventing Service interface exposed as an OSGi Service can be found in here. An instance to this OSGi Service can be obtained by using the following annotation.

 * @scr.reference name="registry.eventing.service"
 * interface="org.wso2.carbon.registry.eventing.services.EventingService" cardinality="1..1"
 * policy="dynamic" bind="setRegistryEventingService" unbind="unsetRegistryEventingService"

Summary

Having read through this tutorial, we now have learned about the WS-Eventing and Notification capabilities made available by the WSO2 Governance Registry. Various other WSO2 Carbon Framework based products such as the WSO2 Enterprise Service Bus is also capable of supporting WS-Eventing and Notifications for operations performed on the resources and collections stored within the underlying registry instance.

We also have gained an understanding of the various types of events available and how to create and manage subscriptions made to these events. We also briefly understood how to configure the WSO2 Governance Registry to send E-mail notifications. Finally, we gathered a basic understanding of how a developer could make use of the API-Level access made available to the Subscription Manager embedded within the WSO2 Governance Registry instance.

The flexibility provided by the support for WS-Eventing and Notification allows users and systems receive messages when there is a change in an application, and take necessary actions as required.

References

[1] Introduction to WS-Eventing
[2] WS-Eventing Specification

Author

Senaka Fernando, Software Engineer, WSO2 Inc., senaka at wso2 dot com