Configuring Notifications in ECE

10 Configuring Notifications in ECE

You can configure Oracle Communications Elastic Charging Engine (ECE) to publish in-session notifications to subscribers and system notifications to external applications.

Topics in this document:

About ECE Notifications

ECE supports these types of notifications:

In-session notifications for your subscribers: These notifications are sent to customers during online charging. For example, notifying customers about their reserved balance amounts.

You can configure in-session notifications for individual subscribers by using subscriber preferences. See "Configuring Subscriber Preferences".
Notifications for external applications: These notifications contain information that external applications need. For example:
- The network mediation system can use data in the external notification in conjunction with customer policy data for implementing network policy control.
  
  ECE sends notifications for external applications to the ECE Notification queue. You must configure your external application to retrieve and process notifications from the ECE Notification queue.
- BRM can use data in the external notification for running billing for a specific customer.
  
  ECE sends notifications for BRM to the ECE Notification queue. You can configure BRM to retrieve the notification from the queue and send it to the BRM Server for processing.

All notifications are disabled by default. You can configure ECE to do the following:

Publish in-session notifications to your subscribers
Publish notifications to external applications, such as BRM
Specify the type of notifications that are supported
Send notifications to everyone in a sharing group when one of its members triggers a notification
Configure BRM Gateway to retrieve notifications from the ECE Notification queue

Enabling External Notifications in ECE

To enable ECE to publish notifications to external applications such as BRM, do the following:

Open the ECE_home/config/charging-cache-config.xml file.

Under the ServiceContext module, set cache-store to oracle.communication.brm.charging.notification.internal.coherence.AsynchronousNotificationPublisher:

<init-param>
  <param-name>cache-store</param-name>
    <param-value>oracle.communication.brm.charging.notification.internal.coherence.AsynchronousNotificationPublisher</param-value>

Save the file.

Enabling Specific Notification Types

You can enable ECE to generate notifications for specific types of events, such as a credit limit being exceeded.

You specify whether a specific notification type is enabled and whether it can be sent to an external application, a subscriber, or both by setting its attribute to one of the values in Table 10-1.

Table 10-1 Notification Attribute Values

Attribute Value	Description
NONE	This notification type is disabled.
ASYNCHRONOUS	Send asynchronous notifications to external applications.
PIGGYBACK	Send in-session notifications to subscribers through the usage response message.
ASYNC_PIGGYBACK	Send both asynchronous notifications to external applications, and in-session notifications to subscribers through the usage response message.

To enable ECE to generate specific types of notifications:

Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the ECE Configuration node.
Expand charging.notification.
Expand Attributes.

Specify which type of notifications can be sent to your customers, external applications, or both by setting the attributes in Table 10-2 to NONE, ASYNCHRONOUS, PIGGYBACK, or PIGGYBACK.

Note:

An asterisk (*) appears next to the default attribute value.

Table 10-2 Notification Types

Attribute Name	Description	Supported Values
creditCeilingBreachNotificationMode	Sends notifications when a customer's balance has breached a credit ceiling.	NONE* ASYNCHRONOUS PIGGYBACK ASYNC_PIGGYBACK
creditFloorBreachNotificationMode	Sends notifications when a customer's balance has breached a credit floor.	NONE* ASYNCHRONOUS PIGGYBACK ASYNC_PIGGYBACK
thresholdBreachNotificationMode	Sends notifications when a customer's balance has breached a credit threshold.	NONE* ASYNCHRONOUS PIGGYBACK ASYNC_PIGGYBACK
topUpNotificationMode	Sends notifications when a customer's balance is topped up.	NONE* ASYNCHRONOUS PIGGYBACK ASYNC_PIGGYBACK
rarNotificationMode	Sends notifications when an ongoing session requires a reauthorization request. See "Enabling Server-Initiated Reauthorization Requests".	NONE* ASYNCHRONOUS
externalTopUpNotificationMode	Sends notifications when a customer's balance is topped up through an external application.	NONE* ASYNCHRONOUS
billingNotificationMode	Sends notifications when a subscriber starts a charging session near the time billing is set to run in BRM. This ensures that billing generates new recurring grants and charges on time.	NONE* ASYNCHRONOUS
adviceOfChargeNotificationMode	Sends notifications to support the Advice of Charge (AoC) supplementary service.	NONE* ASYNCHRONOUS PIGGYBACK ASYNC_PIGGYBACK
replenishPoidIdNotificationMode	Sends notifications when ECE needs to obtain POID IDs from BRM.	NONE ASYNCHRONOUS*
lifeCycleTransitionNotificationMode	Sends notifications when a customer's life-cycle state has changed.	NONE* ASYNCHRONOUS
firstUsageValidityInitNotificationMode	Sends notifications to synchronize validity of first usage balance elements from ECE to external applications.	NONE* ASYNCHRONOUS
offeringUsageValidityInitNotificationMode	Sends notifications to synchronize validity of offer usage balance elements from ECE to external applications.	NONE ASYNCHRONOUS*
spendingLimitNotificationMode	Sends notifications when a threshold for a policy-driven charging rule has been reached.	NONE* ASYNCHRONOUS
aggregatedSpendingLimitNotificationMode	Sends aggregated notifications when a threshold for a policy-driven charging rule has been reached.	NONE* ASYNCHRONOUS
loanGrantNotificationMode	Sends notifications when a customer is granted a loan.	NONE* ASYNCHRONOUS PIGGYBACK ASYNC_PIGGYBACK
automaticTopUpTriggerNotificationMode	Sends notifications when a customer's balance requires an automatic top up.	NONE* ASYNCHRONOUS PIGGYBACK ASYNC_PIGGYBACK

Enabling In-Session Group Notifications in ECE

You can configure ECE to send notifications to everyone in a sharing group when one of its members triggers a notification. For example, when a member breaches a credit limit or credit threshold, a notification is sent to all members in the sharing group.

When group notifications are disabled, ECE sends notifications only to the member that triggered the notification.

To enable group notifications:

Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the ECE Configuration node.
Expand charging.server.
Expand Attributes.
Set the groupNotificationEnabled attribute to True.
Configure the NotificationEnabledAgreements subscriber preference:
1. Add a string for NotificationEnabledAgreements in the BRM_home/sys/msgs/active_mediation/active_mediation.en_US file. For example:
```
STR
  ID = string_id;
  Version = 1;
  STRING = "NotificationEnabledAgreements";
END
```
  where string_id is a unique numerical ID for the string. See "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide for information about adding strings.
2. Add NotificationEnabledAgreements to the BRM_home/sys/data/config/config_subscriber_preferences_map.xml file. For example:
```
<SUBSCRIBER_PREFERENCES elem="preference_id">
       <NAME>NotificationEnabledAgreements</NAME>
       <SUBSCRIBER_PREFERENCE_ID>preference_id</SUBSCRIBER_PREFERENCE_ID>
       <STRING_ID>string_id</STRING_ID>
       <STR_VERSION>1</STR_VERSION>
       <DEFAULT></DEFAULT>
       <TYPE>1</TYPE>
 </SUBSCRIBER_PREFERENCES>
```
  where:
  - preference_id is a unique numerical ID for the preference.
  - string_id is the same value as you used for ID in the active_mediation.en_US file.
  Note:
  
  Leave the <DEFAULT> element blank to ensure that only subscribers who opt in will receive notifications.

When group notifications are enabled, you set subscriber preferences at the profile level to enable notifications for the individual subscribers that want to receive them. See "Configuring Group Notifications" for more information.

Configuring BRM Gateway to Process ECE Notifications

ECE publishes notifications intended for external applications to the ECE notification queue. If the notifications are targeted for BRM, BRM Gateway retrieves the notifications from the queue and then calls the appropriate BRM opcode.

To configure BRM Gateway to process ECE notifications, you must connect BRM Gateway to both BRM and the ECE notification queue:

When you install ECE, do this:
- Add details for connecting the BRM Gateway to the BRM Connection Manager (CM).
- If you are using Oracle WebLogic for notification handling, specify to create WebLogic queues and enter the details for your ECE Notification queue and Suspense queue.
- If you are using Apache Kafka for notification handling, specify to create Kafka topics and enter the details for your ECE Notification topic and Suspense topic.
  
  Note:
  
  Systems that support 5G networks must use Apache Kafka for notification handling.
For more information, see "Installing an ECE Integrated System" in Elastic Charging Engine Installation Guide.
During the ECE post-installation process, do this:
- If you are using Oracle WebLogic for notification handling, run the post_Install.pl script to create your ECE Notification queue, Suspense queue, and Acknowledgment queue. See "Creating WebLogic JMS Queues for BRM" in Elastic Charging Engine Installation Guide.
- If you are using Apache Kafka for notification handling, run the kafka_post_install.sh script to create your ECE Notification topic and Suspense topic. Then, run the post_Install.pl script and choose to create only the Acknowledgment queue. See "Creating Kafka Topics for ECE" and "Creating WebLogic JMS Queues for BRM" in Elastic Charging Engine Installation Guide.
Configure your BRM Gateway instances:
- If you want to configure a single BRM Gateway instance, see "Configuring a Single BRM Gateway Instance".
- If you want to configure multiple BRM Gateway instances, see "Configuring Multiple BRM Gateway Instances".
  
  Note:
  
  Multiple BRM Gateway instances are supported only in ECE 12.0.0.3.0 with Interim Patch 32078697 and later.
Configure the BRM Gateway queues or topics:
- If you are using WebLogic queues, see "Configuring WebLogic Queues for BRM Gateway".
- If you are using Kafka topics, see "Connecting BRM Gateway to Kafka Topics and BRM".
- If you are using queues from an external application, see "Considerations for Using a Non-WebLogic Server JMS Provider".

Configuring a Single BRM Gateway Instance

To configure a single BRM Gateway instance:

Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the ECE Configuration node.
Expand charging.brmGatewayConfiguration.
Expand Attributes.
Use the following attributes to configure BRM Gateway:
- emptyQueueThreadSleepInterval
- jmsReceiveSleepInterval
- brmResponseTimeOutInterval
- gatewaySleepInterval
- jmsBatchSize
- jmsReceiveTimeout
- brmWorkerThreads
- brmSchedulerThreadInitialDelay
- brmSchedulerThreadDelayPeriod
- brmSuspenseQueuePeriod
- connectionRetryCount
- connectionRetryInterval

Configuring Multiple BRM Gateway Instances

Note:

Multiple BRM Gateway instances are supported only by:

ECE 12.0.0.3.0 with Interim Patch 32078697 and later.
ECE environments that use a NoSQL database and Kafka topics.

When your system contains multiple BRM Gateway instances, each instance is connected to one or more schemas in your BRM database. For example, a system with three instances could have BRM Gateway 1 connected to schema 1, and BRM Gateway 2 and BRM Gateway 3 both connected to schema 2. However, only one BRM Gateway instance is active and processing ECE notifications at a time. One of the passive instances comes online only if the active instance goes down.

For example, if BRM Gateway 2 is active, it remains active and processing ECE notifications until the instance goes down. Then, BRM Gateway 1 or 3 becomes active.

To configure multiple BRM Gateway instances:

Open the ECE_home/config/management/charging-settings.xml file.

If you are upgrading to ECE 12.0.0.3.0 with Interim Patch 32078697 or later, do this:

Delete the existing charging.brmGatewayConfiguration section:

<brmGatewayConfiguration
    config-class="oracle.communication.brm.charging.appconfiguration.beans.connection.BRMGatewayConfiguration"
    name="brmGatewayConfiguration"
    emptyQueueThreadSleepInterval="50"
    jmsReceiveSleepInterval="100"
    brmResponseTimeOutInterval="600000"
    gatewaySleepInterval="2000"
    jmsBatchSize="10"
    jmsReceiveTimeout="2000"
    brmWorkerThreads="10"
    brmSchedulerThreadInitialDelay="10"
    brmSchedulerThreadDelayPeriod="3"
    brmSuspenseQueuePeriod="1800000"
    connectionRetryCount="10"
    connectionRetryInterval="10000">
</brmGatewayConfiguration>

Copy the following charging.brmGatewayConfigurations section into the file:

<brmGatewayConfigurations 
    config-class="oracle.communication.brm.charging.appconfiguration.beans.connection.BRMGatewayConfigurations">
    <brmGatewayConfigurationList config-class="java.util.ArrayList">
        <brmGatewayConfiguration
            config-class="oracle.communication.brm.charging.appconfiguration.beans.connection.BRMGatewayConfiguration"
            name="brmGatewayN"
            clusterName="@CLUSTER_NAME@"
            emptyQueueThreadSleepInterval="50"
            jmsReceiveSleepInterval="100"
            brmResponseTimeOutInterval="600000"
            gatewaySleepInterval="2000"
            jmsBatchSize="10"
            jmsReceiveTimeout="2000"
            brmWorkerThreads="10"
            brmSchedulerThreadInitialDelay="10"
            brmSchedulerThreadDelayPeriod="3"
            brmSuspenseQueuePeriod="1800000"
            connectionRetryCount="10"
            connectionRetryInterval="10000"
            schemaNumber="N"/>
</brmGatewayConfigurationList>

Under brmGatewayConfigurationList, add this section for each additional BRM Gateway instance that you want to create:

<brmGatewayConfiguration
    config-class="oracle.communication.brm.charging.appconfiguration.beans.connection.BRMGatewayConfiguration"
    name="brmGateway"
    clusterName="@CLUSTER_NAME@"
    emptyQueueThreadSleepInterval="50"
    jmsReceiveSleepInterval="100"
    brmResponseTimeOutInterval="600000"
    gatewaySleepInterval="2000"
    jmsBatchSize="10"
    jmsReceiveTimeout="2000"
    brmWorkerThreads="10"
    brmSchedulerThreadInitialDelay="10"
    brmSchedulerThreadDelayPeriod="3"
    brmSuspenseQueuePeriod="1800000"
    connectionRetryCount="10"
    connectionRetryInterval="10000"
    schemaNumber="1"/>
</brmGatewayConfigurationList>

Edit these properties for each BRM Gateway instance:
- name: Set this to the name of your BRM Gateway instance in this format: brmGatewayN. For example, name the first instance brmGateway1, the second instance brmGateway2, and so on.
- schemaNumber: Set this to the schema number that the BRM Gateway instance connects to in the BRM database. Enter 1 to connect to the first schema, 2 to enter the second schema, and so on.
Save and close the charging-settings.xml file.
Stop BRM Gateway:
```
stop brmGateway
```
Open the ECE_home/config/eceTopology.conf file.

Add a row to the file for each BRM Gateway instance.

For example, to configure three BRM Gateway instances, add three rows in which the node name value is brmGateway1, brmGateway2, and brmGateway3, and the role value for all three rows is brmGateway:

#node-name          |role                 |host name (no spaces!) |host ip |JMX port |start CohMgt |JVM Tuning File
brmGateway1         |brmGateway           |localhost              |        |9994     |false        |defaultTuningProfile
brmGateway2         |brmGateway           |localhost              |        |9994     |false        |defaultTuningProfile
brmGateway3         |brmGateway           |localhost              |        |9994     |false        |defaultTuningProfile

Save and close the eceTopology.conf file.
From the ECE_home/bin directory, start Elastic Charging Controller (ECC):
```
./ecc
```
Start all BRM Gateway instances:
```
start brmGateway
```

Connecting BRM Gateway to Kafka Topics and BRM

To connect BRM Gateway to the ECE Notification Kafka topic and BRM:

Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the ECE Configuration node.
Expand charging.server.
Expand Attributes.
Set the kafkaEnabledForNotifications property to true.
Expand charging.kafkaConfigurations.
Expand Attributes.

Specify the Kafka configuration values for the attributes in Table 10-3.

Verify that the name, hostname, and topic names that you provide match the settings entered when installing ECE.

Table 10-3 Settings for Connecting BRM Gateway to Kafka Topics

Property Name	Description
name	The name of your ECE cluster.
hostname	The host name and port number of the machine in which Apache Kafka is up and running. If it contains multiple Kafka brokers, create a comma-separated list.
topicName	The name of the Kafka topic in which BRM Gateway retrieves notifications from ECE.
partitions	The total number of Kafka partitions in your topics. The recommended number to create is calculated as follows: [(Max Diameter Gateways * Max Peers Per Gateway) + (1 for BRM Gateway) + Internal Notifications]
kafkaBRMReconnectionInterval	The amount of time, in milliseconds, BRM Gateway waits before attempting to reconnect to the Kafka topic.
kafkaBRMReconnectionMax	The maximum amount of time, in milliseconds, BRM Gateway waits before attempting to reconnect to a broker that has repeatedly failed to connect. The kafkaBRMReconnectionInterval will increase exponentially for each consecutive connection failure, up to this maximum.

Expand charging.connectionConfigurations.brmConnection.
Expand Attributes.
Specify the configuration values for connecting BRM Gateway to the BRM Connection Manager (CM):
- hostName: Enter the host name of the server in which the CM is running. For example: abc01.example.com.
- loginName: Enter the user name for logging in to BRM. The default is root.0.0.0.1.
- cmPort: Enter the port number for the BRM CM.

About BRM Gateway Error Handling

When BRM Gateway calls an opcode, it checks whether the opcode ran successfully. If it did not, the exception from the opcode is checked and, if the exception is one of the following, it retries the opcode call.

ERR_TIMEOUT
ERR_DEADLOCK
ERR_STREAM_EOF
ERR_IM_CONNECT_FAILED
ERR_EM_CONNECT_FAILED
ERR_NAP_CONNECT_FAILED

If the opcode continues to fail after all of the configured retry attempts, the notification is moved to the Suspense topic.

If the exception is due to a duplicate message (ERR_DUPLICATE), the opcode call is not retried and the message is not moved to the Suspense topic.

Configuring WebLogic Queues for BRM Gateway

To configure WebLogic queues for BRM Gateway:

Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the ECE Configuration node.
Expand charging.connectionConfigurations.brmConnection.
Expand Attributes.
Use the following attributes to specify connection values to the BRM Connection Manager (CM):
- loginName: Enter the user name for logging in to BRM. The default is root.0.0.0.1.
- hostName: Enter the IP address or the host name of the computer on which BRM is configured.
- cmPort: Enter the port number for the BRM CM.

WebLogic Server Configuration Settings for the connectionFactory

For the connectionFactory created within the WebLogic server for creating connections to the JMS topic, do the following:

Log on to the WebLogic Server on which the JMS topic resides.
In the WebLogic Server Administration Console, from the JMS modules list, select the ConnectionFactory that applies to the JMS topic used for ECE notifications.
Do the following:
1. In the Client tab, set the Reconnect Policy to All.
2. In the Transactions tab, set the Transaction Timeout to 2147483647.

Refer to the Oracle WebLogic Server documentation for information about setting up a JMS topic on WebLogic Server.

Considerations for Using a Non-WebLogic Server JMS Provider

If you choose to use a JMS provider other than WebLogic Server for publishing ECE notification events, you must do the following on the driver machine:

Copy the other JMS provider's client JARs to the ECE_home/lib directory.
Rename the other JMS provider JAR file to wlthint3client.jar.
Update the ECE_home/config/JMSConfiguration.xml file to specify the InitialContextFactory and protocol information of the other JMS provider.

Modifying JMS Credentials for Publishing External Notifications

When you install ECE, you can specify to publish notifications to a WebLogic JMS queue (named ECE Notification queue) as well as how to connect to the queue.

If you need to change the connection information after ECE is installed, you can edit the parameters in the JMSConfiguration.xml file.

To modify the JMS credentials in ECE, do the following:

Open the ECE_home/config/JMSConfiguration.xml file.
Locate the <MessagesConfigurations> section.
Specify the values for the parameters in the NotificationQueue section:

Note:

Do not change the value of the JMSDestination name parameter.
1. For the HostName parameter, specify the host name of the WebLogic server on which the JMS topic resides.
2. For the Port parameter, specify the port number on which the WebLogic server resides.
3. For the UserName parameter, specify the user for logging in to the WebLogic server.
  
  This user must have write privileges on the JMS topic created.
4. For the Password parameter, specify the password for logging in to the WebLogic server.
  
  When you install ECE, the password you enter is encrypted and stored in the KeyStore. If you change the password, you must first run a utility to encrypt the new password before entering it here.
5. For the ConnectionFactory parameter, specify the connectionFactory created within the WebLogic server for creating connections to it.
  
  You must also configure settings in WebLogic server for the connectionFactory. See "WebLogic Server Configuration Settings for the connectionFactory" for information.
6. For the QueueName parameter, specify the JMS topic.
  
  This is the JMS topic which holds the published external notification messages.
7. For the Protocol parameter, specify the wire protocol used. For WebLogic server, set this to t3://.
Save and close the file.