This chapter describes the Oracle Communications Billing and Revenue Management (BRM) event notification feature and explains how to enable it.
Before reading this chapter, you should be familiar with the following:
BRM flists and storable classes. See "Understanding Flists and Storable Classes".
BRM opcodes. See "Understanding the PCM API and the PIN Library".
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, PCM_OP_ACT_USAGE checks whether the event is listed as a triggering event in the configuration object. If it is, PCM_OP_ACT_USAGE 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".
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 executed 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 you installed BRM components.
pin_notify - Supports the following features:
Automated Monitor Setup (AMS)
Midcycle product rate-change calculations
Resource 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.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.
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) If necessary 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".
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".
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
opcode_number is the number associated with the opcode executed 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).
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 execute 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".
If an event is mapped to more than one opcode in the event notification list, BRM executes the opcodes in the order they are listed whenever the event is generated. For example, the default pin_notify file includes these entries in this order:
7854 0 /event/notification/service/create 7855 0 /event/notification/service/create 7856 0 /event/notification/service/create
This example specifies that when an /event/notification/service/create event is generated, BRM first executes PCM_OP_MONITOR_ACCOUNT_HIERARCHY (opcode number 7854), then executes PCM_OP_MONITOR_BILLING_HIERARCHY (opcode number 7855), and finally executes PCM_OP_MONITOR_SERVICE_HIERARCHY (opcode number 7856).
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.
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:
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:
Stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
(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:
To verify that the event notification list was loaded, use one of these features to display the config/notify object:
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".
Any subclass of the /event 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 executed opcode or opcodes.
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 executed by the event notification feature.