Using Event Notification

23 Using Event Notification

Learn how to enable and use the event notification feature in Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

About Event Notification

Event notification automatically triggers BRM operations when specified events occur.

The triggering events are mapped to one or more opcodes in a configuration object (/config/notify) stored in the BRM database. When any event occurs, BRM checks whether the event is listed as a triggering event in the configuration object. If it is, BRM calls the opcode or opcodes mapped to the event. The information in the event is passed to the opcodes in their input flists. Optionally, a flag can also be passed to the opcodes.

By default, event notification is not enabled. To enable and customize this feature, see "Implementing Event Notification".

About the Event Notification List

The event notification list contains all the events that trigger event notification in your BRM system. Each event in the list is mapped to the opcode or opcodes that are run when the event occurs. The event notification list is stored in the /config/notify object in your BRM database.

By default, the event notification list is not loaded into the database. To load the list into the database, you must first set up the list in a configuration file. Depending on which BRM features you use, your system may contain one or more of the following configuration files for event notification. Each file contains default event-to-opcode mapping that supports event notification for one or more BRM features. All of the event notification configuration files available in your system are in the BRM_home/sys/data/config directory, where BRM_home is the directory in which the BRM server software is installed.

pin_notify: Supports the following features:
- Automated Monitor Setup (AMS)
- Device management
- Discounting
- Email notification
- Event rerating
- Midcycle charge offer charge-change calculations
- Balance reservation for disputes and settlements
pin_notify_eai: Supports Enterprise Application Integration (EAI) Manager.
pin_notify_ifw_sync: Supports account synchronization and Suspense Manager.
pin_notify_ipc: Supports policy-driven charging.
pin_notify_kafka_sync: Supports the Kafka DM.
pin_notify_ldap: Supports Lightweight Directory Access Protocol (LDAP) Manager.

pin_notify_plugin_http: Supports the EAI Manager dm_http plug-in. See "Configuring EAI Manager to Publish to an HTTP Port".
pin_notify_ra: Supports Revenue Assurance Manager and Suspense Manager.
pin_notify_telco: Supports Global System for Mobile Communications (GSM) Manager.

To modify the content of one of these files, see "Editing the Event Notification List".

If your system contains more than one of these files, you must merge their contents into a single file. See "Merging Event Notification Lists".

To load the content of one of these files into the BRM database, see "Loading the Event Notification List".

Note:

Configuring notification thresholds that result in large number of subscriber breaches can impact call detail record (CDR) throughput.

Implementing Event Notification

By default, event notification is not enabled in BRM because the /config/notify object is not created during installation. To implement event notification:

If your system has multiple configuration files for event notification, merge them. See "Merging Event Notification Lists".
(Optional) To accommodate your business needs, add events to or comment them out of the configuration file that contains the final event notification list you want to load into the BRM database. See "Editing the Event Notification List".
(Optional) If necessary to accommodate your business needs, create custom code for event notification to trigger. See "Triggering Custom Operations".
Load your final event notification list into the BRM database. See "Loading the Event Notification List".

You can customize event notification by using the PCM_OP_ACT_POL_EVENT_NOTIFY opcode. This opcode is called by various event notification processes and by the PCM_OP_ACT_POL_EVENT_LIMIT policy opcode. This opcode processes events for LDAP integration and email notification when invoked by event notification.

Merging Event Notification Lists

To enable event notification, you run the load_pin_notify utility to load the configuration file containing your event notification list into the BRM database. Before running the utility, however, you must merge configuration files for event notification if either of the following is true:

You are enabling event notification for the first time, and your system has multiple configuration files for event notification.
Your BRM database already contains an event notification list, and you want to add an event notification list for another feature to the database.

Caution:

If you load the new feature's list before merging it with your system's current list, you will disable event notification for the features supported by the current list.

To merge event notification lists:

In a text editor, open all the event notification configuration files that you want to merge. By default, the files are in the BRM_home/sys/data/config directory.
Copy all the entries from the open files into one of the default files or into a new file.

Tip:

Save a copy of the default files before merging them.
Save and close the merged file.

Tip:

You can give the merged file any name you want, and you can store it in any location.

To edit the merged file, see "Editing the Event Notification List".

To load the merged file, see "Loading the Event Notification List".

Editing the Event Notification List

Your system's event notification list is set up in a configuration file (see "About the Event Notification List"). To modify the event notification list:

In a text editor, open the configuration file that contains the list. By default, the file is in the BRM_home/sys/data/config directory.
To add an entry to the list, use this syntax:
```
opcode_number     flag     event
```
where:
- opcode_number is the number associated with the opcode run when the event occurs. Opcode numbers are defined in header (*.h) files in the BRM_home/include/ops directory.
- flag is the name of the flag to pass to the opcode when it is called by the event notification feature. 0 means no flag is passed.
- event is the name of the event that triggers the execution of the opcode. You can use any BRM default or custom event defined in your system. Triggering events do not have to be persistent. For example, you can use notification events (see "About Notification Events") and events that you have excluded from the BRM database (see "Managing Database Usage" in BRM System Administrator's Guide).
For example:
```
301     0     /event/session
```
This example specifies that when an /event/session event occurs, the event notification feature calls opcode number 301, which is the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode, passing it the contents of the event but not passing it any flag.

To run multiple opcodes when an event occurs, see "Triggering Multiple Opcodes with One Event".
To disable an entry in the list, insert a number sign ( # ) at the beginning of the entry. For example:
```
# 301     0     /event/session
```
Close and save the edited file.

Tip:

You can give the file any name you want, and you can store it in any location.
Load the edited list into the BRM database. See "Loading the Event Notification List".

Triggering Multiple Opcodes with One Event

If an event is mapped to more than one opcode in the event notification list, BRM runs the opcodes in the order they are listed whenever the event is generated.

The following example specifies that when an /event/provisioning/service_order/telco/gsm event is generated, BRM first runs PCM_OP_TCF_PROV_HANDLE_SVC_ORDER (opcode number 4017), then runs PCM_OP_TCF_PROV_UPDATE_PROV_OBJECT (opcode number 4019).

4017   0   /event/provisioning/service_order/telco/gsm
4019   0   /event/provisioning/service_order/telco/gsm

Triggering Custom Operations

To use event notification to trigger custom operations not included in an existing policy opcode:

Add the operation to the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode.
Add the following entry to your system's event notification list:
```
301     flag     event
```
For more information, see "Editing the Event Notification List".

Note:

301 is the number of PCM_OP_ACT_POL_EVENT_NOTIFY.

Loading the Event Notification List

To add your event notification list to the BRM database, run the load_pin_notify utility. The utility loads the list into the /config/notify object.

Caution:

This utility replaces the current list in the /config/notify object with the list in the configuration file that you load. If you use event notification for multiple features, you must merge the old list with the new list before running this utility. Otherwise, you will lose existing event notification functionality. See "Merging Event Notification Lists".

Note:

To connect to the BRM database, this utility needs a configuration (pin.conf) file in the directory from which you run the utility. For information about creating configuration files for BRM utilities, see "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

To load the event notification list:

Go to the directory that contains the list you want to load. By default, configuration files containing event notification lists are in the BRM_home/sys/data/config directory.
If necessary, do one or both of the following:
- Edit the list. See "Editing the Event Notification List".
- Merge the list with other event notification lists. See "Merging Event Notification Lists".
  
  Caution:
  
  This utility overwrites all existing data in your system's /config/notify object. If you are updating the event notification list, you cannot load new or changed entries only. You must load the entire list each time you run the utility.
If you edited or merged the list, save the configuration file that contains the final list.

Note:

You can give the file any name you want, and you can place the file anywhere you want.
Use the following command to run the load_pin_notify utility:
```
load_pin_notify event_notification_configuration_file_name
```
If you do not run the utility from the directory in which the configuration file is located, include the complete path to the file. For example:
```
load_pin_notify BRM_home/sys/data/config/event_notification_configuration_file_name
```
Stop and restart the Connection Manager (CM).
(EAI Manager only) Stop and restart the EAI Data Manager (DM):
```
cd BRM_home/bin
stop_dm_eai
start_dm_eai
```
(EAI Manager only) Stop and restart the Payload Generator External Module (EM):
```
cd BRM_home/bin
stop_eai_js
start_eai_js
```
(GSM Manager only) Start the Provisioning DM:
```
start dm_prov_telco 
```
To verify that the event notification list was loaded, use one of these features to display the config/notify object:
- Object Browser
- robj command with the testnap utility
  
  Note:
  
  By default, the BRM database does not contain the /config/notify object. The object is created when you run the load_pin_notify utility.
For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File".

About Notification Events

Any subclass of the /event storable class can be used to trigger event notification. When standard /event subclasses are used to trigger event notification, the information their instances contain is handled as follows:

It is added to the input flist of the opcode or opcodes that are run.
It is stored in the BRM database.

For more information about standard /event subclasses, see BRM Storable Class Reference.

Unlike instances of standard events, instances of /event/notification subclasses (notification events) are not persistent. Hence, the information they contain is not stored in any database. Instead, it is used only to populate the input flists of opcodes run by the event notification feature.