7 Using the Event Notification Framework

The Event Notification Framework provides a way for complementary applications to publish events to external Operational Support Systems (OSSs).

This chapter describes the configuration of the Event Notification Framework in Oracle Communications Online Mediation Controller.

About the Event Notification Framework

Complementary applications use the Event Notification Framework to publish events. The type of event and its timing are application-specific.

Events can be targeted to internal Online Mediation Controller components, or to external systems, such as your OSS.

Complementary applications fire events toward external systems, to inform them of events that occur during application execution. For example, when a subscriber's state changes, or when a subscriber's monthly usage reaches a threshold.

Complementary applications fire events toward internal Online Mediation Controller components, to request them to perform an action. For example, request sending a text message to a subscriber using the Short Message Service (SMS), or to change the subscriber's state.

Firing events toward internal Online Mediation Controller components is necessary for optimization purposes; even though complementary applications can send requests to other Online Mediation Controller components internally, applications running on the session's setup path should optimally delegate requests, through the Event Notification Framework, to other entities which will asynchronously invoke execution of the requests, thus reducing the execution time of the complementary applications running on the session setup path.

When targeting events at internal Online Mediation Controller components you need to run a built-in Event Processor. See "About the Event Processor" for more information.

When targeting events to external systems, such as your OSS, you use an asynchronous Web services Event Notification API to consume these events in your system. See "Using the Event Notification API" for more information.

You can target events at only one destination, that is either an external OSS application, or the Event Processor.

If you target events at an external OSS application, then you must filter events published by built-in complementary applications and forward them to the Event Processor. Otherwise, you harm the functionality of the built-in complementary applications. Forwarding events to the Event Processor is necessary only if you deploy one or more of the built-in complementary applications. The exact events that you need to filter and forward to the Event Processor depends on built-in application that you deploy. The documentation of each of the applications includes a section listing the events that the application fires.

Figure 7-1 shows how you can either target events at the internal Event Processor, or at external OSS application, in which case your OSS application should filter built-in application events and forward them to the Event Processor.

Figure 7-1 Targeting Events at Either Internal or External Entities

Description of "Figure 7-1 Targeting Events at Either Internal or External Entities"

About the Event Notification API

The Event Notification API is SOAP-based. It gives the Online Mediation Controller the role of a SOAP client, and the application consuming the events acts as a SOAP server.

The methods and data types of the API are described using WSDL and XSD files. See "Using the Event Notification API" for more information.

About the Event Processor

The Event Notification Framework includes a built-in Event Processor that you use to manage events fired by built-in complementary applications. The Event Processor implements default handling for those events, that normally involves further activation of Online Mediation Controller components. For example, when receiving an event from the Threshold Notification application, the Event Processor triggers SMS sending to the subscriber.

The Event Processor can be extended by Oracle Consulting, to handle additional online events.

The Online Mediation Controller starts the Event Processor by default. The Event Processor itself does not require any specific configuration.

Using the Event Processor is optional. If you are not using the Event Processor, free the resources used by the Event Processor by stopping its bundles. See "Stopping the Event Processor" for more information.

Setting Up the Event Notification Framework

Complementary applications use their SAL API to fire events. Events are thereby published through the application's IM-ASF-SAL module.

Figure 7-2 shows how events pass through the OE to IM-WS, which converts the event to a SOAP message, and send it out through the Web Service SSU. The Web Services SSU sends events at either the Event Processor or an external OSS application. In either case, you configure the internal Online Mediation Controller Event Processor to receive incoming events.

Figure 7-2 also shows the Online Mediation Controller components required to set up the Event Notification Framework.

Figure 7-2 Online Mediation Controller Components Required by the Event Notification Framework

Description of "Figure 7-2 Online Mediation Controller Components Required by the Event Notification Framework"

Configuration Workflow

This section assumes that you have already deployed and configured the complementary application that publishes events and its related IM-ASF-SAL module.

To set up the Event Notification Framework:

In the Web Services SSU, configure Online Mediation Controller as a Web services client. See the discussion about SOAP client parameters in "Configuring SOAP Web Services Access" in Oracle Communications Signaling Server Units Configuration Guide.
In the Web Services SSU, configure the target consuming events. See "Configuring Target Event Consumers".
Deploy and configure an IM-WS module. See "Deploying and Configuring IM-WS".
Route events to IM-WS. See "Routing Events to IM-WS".
Enable HTTP network access by opening an HTTP listening port. See "Enabling HTTP Network Access".
Route incoming SOAP events to the Event Processor. See "Routing Incoming Events to the Event Processor".

Configuring Target Event Consumers

In the Web Services SSU, configure event consumers, as described in "Configuring Routing Rules for Outgoing Web Services Messages" in Oracle Communications Service Broker Signaling Server Units Configuration Guide.

You can define two or more consumers having a different URL that share the same alias, thereby adding a level of redundancy, treating all consumers as one logical destination, and balancing the load among consumers.

In the Administration Console:

In the navigation tree, expand OCSB.
Expand Signaling Tier.
Expand SSU Web Services.
Select General.
In the SSU WS tab, select the Outgoing Routing Rules tab.
Click New. The New dialog box appears.
In the Name field, enter a name for the target event consumer.
In the Alias field, enter an alias for the target event consumer.

If you target events at the Event Processor, enter sbeventprocess. Otherwise, enter an alias that represents the external OSS application that you are targeting. For example: esb.
In the Web Service URI, enter the Web URI of the target event consumer:

If you target events at the Event Processor, enter:
```
http://ip:port/soap/Events
```
Where:

ip: the address of the signaling servers in the Signaling Domain where the Web Services SSU is running. This should be the address of the signaling server or server cluster in your deployment.

port: the signaling servers' web services port.

Otherwise, enter the URI of the external OSS application that you are targeting, that is a web services server, in the format:

http://address:port/web-service-name.

For example, http://telmobil.esb.org:80/eventnotification.
Fill in the remaining fields. See the discussion on "Configuring Routing Rules for Outgoing Web Services Messages", in Oracle Communications Service Broker Signaling Server Units Configuration Guide for more information.
Click OK.

Deploying and Configuring IM-WS

Deploy the IM-WS module as described in "Managing Interworking Modules" in Oracle Communications Service Broker Modules Configuration Guide.

In the Administration Console:

In the navigation tree, expand OCSB.
Expand Processing Tier, and then Interworking Modules.
Click IM Management.
In the IM Management tab, click New.
From the Type list, select IMWS.
In the Name field, enter a module instance name. For example, imws_instance.
Click OK.
Click Commit.

Configure the IM-WS module.

Specifically, in the Web Service tab, set the following fields as described:

In the Web Service Alias field, enter the alias of the target event consumer that you configured in the Web Services SSU in step 2.
From the Web Service Type list box, select SOAP.
In the Web Service Body Type, enter eventnotification.

See the discussion on configuring the IM-WS in Oracle Communications Service Broker Modules Configuration Guide for more information.

Routing Events to IM-WS

Create an appropriate orchestration logic that routes events arriving from IM-ASF-SAL toward IM-WS. Use the Orchestration Studio to create the orchestration logic. See Oracle Communications Service Broker Orchestration User's Guide.

Specifically, you need to set a condition that identifies SAL messages with the Method set to MESSAGE and the To header containing the string events_service. For example:

To: sip:postEventRequest@events_service

Enabling HTTP Network Access

You enable HTTP network access to let incoming events reach the Event Processor.

To configure HTTP connectivity for the incoming events:

In the navigation tree, expand OCSB.
Expand Signaling Tier.
Expand SSU Web Services.
Select General.
Select the HTTP tab.
In the Server subtab, select the Network Access subtab.
Click New.
In the dialog box, set the properties for the HTTP listener as follows:
- Server Address: The local IP address or host name to which the port is bound. This should be the address of the signaling server or server cluster in your deployment.
- Server Port: An available listening port on Online Mediation Controller serving API client requests, such as 8989. This is the port number on which the signaling servers listens for incoming HTTP requests to the Event Processor.
- Protocol: The protocol used by incoming events. Choose HTTPS for secure HTTP or HTTP for unsecured HTTP. Oracle recommends using HTTPS for production deployments.
- SSL Client Auth: Whether SSL client certificate authentication is required for the connection. Enter false to disable SSL client certificate authentication, or true to require it. Enter true only if using HTTPS for the Protocol, in which case you will also need to set the key store and trust store identifiers.
- Keystore Id: The key you used when loading the keystore in the Credential Store. Use only with HTTPS. If you are using HTTP, this field can be left blank. If you have not already, load the keystore associated with the ID into the Credential Store. See Oracle Communications Service Broker Administrator's Guide for more information about the Credential Store.
- Truststore Id: The key you used when loading the trust store into the Credential Store. Use only with HTTPS. If using HTTP, this field can be left blank. See Oracle Communications Service Broker Administrator's Guide for more information about the Credential Store.
- Target: The signaling server to which this configuration applies. Leave blank to apply the configuration to all signaling servers in the deployment. Specify a signaling server name only if you want custom settings for individual signaling servers.

Routing Incoming Events to the Event Processor

To route incoming events to the Event Processor, create a new incoming routing rule in the Web Services SSU. See the discussion about incoming routing rules in "Configuring the Web Services SSU" in Oracle Communications Service Broker Signaling Server Units Configuration Guide.

Specifically, in the new rule, set the following fields as described:

In the Service Name field, enter oosEventService.
In the Alias field, enter ssu:ocsb/outofsession.

Stopping the Event Processor

To stop the Event Processor:

In the Administration Console, in the navigation tree, expand OCSB.
Expand Domain Management
Select Packages
In the Filter field, enter axia.oos. The Event Processor bundles will be listed:
- com.convergin.wcs.axia.oos
- com.convergin.wcs.axia.oos.ext
- com.convergin.wcs.axia.oos.ooshash
Select a bundle that you want to stop and click Stop.

Using the Event Notification API

The event notification API is a SOAP-based API that you use to consume events, and run your specific business logic in the occurrence of these events.

The event notification API includes a single operation for receiving a notification. In general, any kind of event, triggered by any complementary application, is submitted through this API.

For most deployments, the primary consumer of the API notifications is the customer's ESB, for example, Oracle Enterprise Service Bus. The ESB filters the various notifications and distributes them to other OSS modules, based on the type of the event published. However, any other SOAP server that you implement can consume events.

To consume events, you develop a Web service with the WSDL files describing the event notification interface, and deploy the Web service on your SOAP server.

Obtaining WSDL and Schema

The following files describe the interface of the Event Notification API and its data types:

events_service.wsdl
events_interface.wsdl
general.xsd
events.xsd

You obtain the files from the signaling server. To navigate to the WSDL, go to the following address:

http://host:port/soap/events

Where host is the host name or IP address and port is the server port number you specified as the server address. See "Enabling HTTP Network Access".

If the WSDL is accessible, you can start developing your API server application. Many Integrated Development Environments (IDEs) can generate client code you can use as a starting point for your application by importing the WSDL into the IDE.

Event Notification API Reference

The rest of this chapter is a reference of the event notification API, describing the operation of the API. It lists the parameters accepted and returned by the operation. It provides examples of HTTP requests and responses for the operation.

Note:

In the request and response message examples in this section, line breaks and spaces have been added to the data in the body of the message to improve readability.

Post Event

Notifies of the occurrence of an event.

The event can be of any kind. Its characteristic is defined by two fields: the event type and event category. The values of the event type and event category are not limited to a predefined set of values, and are extensible. The values depend on the complementary application initiating the event notification. Each application defines its own set of event types and categories. The events provided by each application are listed in the documentation of each application.

Request Body

Request body parameters are:

externalCorrelationID: (xs:string) Optional. An event identifier, that you can use to correlate to the event.
senderIdentifier: (xs:string) Optional. The identifier of the complementary application submitting the event.
subscriberID: (SubscriberID) Optional. The identifier of the subscriber that owns the session for which the application sending the event was invoked. SubscriberID comprises:
- code: (xs:int) The type of the subscriber identifier value. Possible values are:
  - 0: Mobile Subscriber ISDN Number (MSISDN) or Directory Number (DN)
  - 1: Mobile Identification Number (MIN) or International Mobile Subscriber Identity (IMSI)
  - 2: SIP URI
- value: (xs:string) The subscriber identifier.
type: (xs:string) The event type. Can be any number of characters, including any combination of letters, word characters and spaces.
category: (xs:string) The event category. Helps dividing the different types of events into sets of related events. A group of related events is assigned with the same category.

For example, events categorized as internal, are events consumed by internal Online Mediation Controller components and submitted by complementary applications to implement built in Online Mediation Controller features.

Complementary application developers can define categories as they need.

Can be any number of characters, including any combination of letters, word characters and spaces.
description: (xs:string) Optional. A free text description of the event. Can be any number of characters, including any combination of letters, word characters and spaces.
additionalParam: (NameValue) Optional. A recursive structure containing event specific parameters. Each parameter is a pair of:
- code: (xs:string) A unique parameter identifier. Can be any number of characters, including any combination of letters, word characters and spaces.
- A choice of:
  - value: (xs:string) The parameter value. Can be any number of characters, including any combination of letters, word characters and spaces.
  - nameValue (NameValue) more event specific parameters, related to each other, that you want to assemble in one set of parameters.

Response Body

Response body parameters are:

result: (GenericOutput). The result of the operation. A data structure containing the following parameters:
- fault: (Fault): Optional. A data structure containing the following:
  - faultcode: (xs:QName). A code identifying the fault.
  - faultstring: (xs:string). A human readable explanation of the fault.
  - faultactor: (xs:anyURI) Optional. Information about who caused the fault to happen.
  - detail (detail) Optional. Holds event specific error information. A data structure containing a sequence of xs:any and then xs:anyattribute
  Built-in complementary applications ignore this parameter.
- externalId (string). The event identifier. This must always be equal to the externalCorrelationID parameter in the request body.
- additionalInformation (NameValue) Optional. A recursive structure containing event specific parameters. See the description of the additionalParam parameter, in the request body. The list of parameters depends on the specific event.

Example

Example 7-1 shows a sample post event request.

Example 7-1 Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:even="http://xmlns.oracle.com/axia/events"
xmlns:gen="http://xmlns.oracle.com/ocsb/core/general">
        <soapenv:Header/>
                <soapenv:Body>
                        <even:postEventRequestParams>
        <even:externalCorrelationID>71b42285</even:externalCorrelationID>
        <even:senderID>FirstCallApplication</even:senderID>
        <even:subscriberID>
        <gen:code>0</gen:code>
        <gen:value>+14081154970</gen:value>
        </even:subscriberID>
        <even:type>FirstCall</even:type>
        <even:category>Charging</even:category>
        even:description>account activation complete</even:description>
        </even:postEventRequestParams>
        </soapenv:Body>
</soapenv:Envelope>

Example 7-2 shows a sample post event response.

Example 7-2 Response

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> 
        <S:Body>
        <postEventResponseParams xmlns="http://xmlns.oracle.com/axia/events
        xmlns:ns2="http://xmlns.oracle.com/ocsb/core/general">
                <even:externalCorrelationID>71b42285</even:externalCorrelationID>
        </postEventResponseParams>
        </S:Body>
</S:Envelope>