This chapter describes how to use events to trigger operations in Oracle Communications Billing and Revenue Management (BRM).
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 is a workflow mechanism that automatically triggers BRM operations when a notification-triggering event occurs.
A notification-triggering event is an event listed in your system's /config/notify object and mapped in that object to one or more opcodes. The list of notification-triggering events is called the event notification list.
When any event occurs, the PCM_OP_ACT_USAGE opcode checks whether the event is in the event notification list (that is, whether it is a notification-triggering event). 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 notification-triggering events in your BRM system. Each notification-triggering event in the event notification list is mapped to the opcode or opcodes that are called 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. Before loading the list into the database, you must set it up in a configuration file.
Depending on which BRM features you use, your system may contain one or more of the following event notification configuration files. Each configuration file contains default triggering event–to–opcode mapping that supports event notification for one or more BRM features. All 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 BRM is installed.
pin_notify, which supports the following features:
Automated Monitor Setup (AMS)
Device management
Discounting
Email notification
Event rerating
Midcycle product rate-change calculations
Resource reservation for disputes and settlements
pin_notify_eai, which supports Enterprise Application Integration (EAI) Manager.
pin_notify_ifw_sync, which supports Account Synchronization and Suspense Manager.
pin_notify_ipc, which supports policy-driven charging.
pin_notify.ldap, which supports Lightweight Directory Access Protocol (LDAP) Manager.
pin_notify_plugin_http, which supports the EAI Manager dm_http plug-in. See "Configuring EAI Manager to Publish to an HTTP Port".
pin_notify_ra, which supports Revenue Assurance Manager and Suspense Manager.
pin_notify_telco, which 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, merge their contents into a single file. See "Merging Event Notification Lists".
To load the content of the configuration file that contains your system's final event notification list (edited and merged as necessary) 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:
(Optional) Enable regular expressions to be used in the event notification list. See "Enabling the Use of Regular Expressions in the Event Notification List".
If your system has multiple event notification configuration files, merge them. See "Merging Event Notification Lists".
(Optional) If necessary to accommodate your business needs, add events to or comment them out of the event notification configuration file that contains the 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 operations not included in an existing policy opcode for event notification to trigger. See "Using Event Notification to Trigger Custom Operations".
Load your event notification list into the BRM database. See "Loading the Event Notification List".
By default, each entry in the event notification list must match the full name of an event type. You can, however, use regular expressions to make a single entry apply to multiple event types.
For example, by default, to trigger BRM to call opcode 301 each time any session event occurs, you must include all the /event/session subclasses in the event notification list as follows:
301 0 /event/session/call 301 0 /event/session/dialup 301 0 /event/session/pcm_client 301 0 /event/session/telco 301 0 /event/session/telco/gprs 301 0 /event/session/telco/gprs/master 301 0 /event/session/telco/gprs/subsession 301 0 /event/session/gsm 301 0 /event/session/imt 301 0 /event/session/telco/pdc
To shorten the list, you can replace those entries with the following regular expression, which matches all subclasses of the /event/session/ storable class:
301 0 /event/session/.*
By default, the use of regular expressions in the event notification list is disabled. When enabled, the notification list supports regular expressions that use the following special characters: asterisk (*), dot (.), and dollar sign ($).
To enable the use of regular expressions in the event notification list:
Open the BRM_home/sys/cm/pin.conf file in a text editor.
Set the following entry to 1:
- fm_act notify_mode 1
Note:
If the entry is not in the file, add it.
If the entry is commented out, uncomment it.
When the entry is set to 0, use of regular expressions in the event notification list is disabled.
Save and close the file.
Restart the Connection Manager (CM).
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 additional feature's list before merging it with your system's current event notification list, you will disable event notification for the features supported by the current event notification list.To merge event notification lists:
Save a copy of all the event notification configuration files you want to merge.
By default, the files are in the BRM_home/sys/data/config directory.
In a text editor, open all the event notification configuration files you want to merge.
Copy all the entries from the open files into one of the default files or into a new file.
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".
To edit the event notification list:
In a text editor, open the event notification configuration file that contains your system's event notification list.
By default, the file is in the BRM_home/sys/data/config directory.
Add entries to the list by using the following syntax:
opcode_number flag event
where:
opcode_number is the number associated with the opcode called when the notification-triggering 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. 0 means no flag is passed.
event is the name of the notification-triggering event that initiates the opcode call. You can use any BRM default or custom event defined in your system.
Notification-triggering events do not have to be saved in the database. 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).
By default, you must use a full event name in each entry. Optionally, you can use regular expressions to make a single entry apply to multiple event types (see "Enabling the Use of Regular Expressions in the Event Notification List").
For example:
301 0 /event/session
This example specifies that when an /event/session event occurs, opcode number 301, the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode, is called. The contents of the event are passed to the opcode, but no flag is passed.
To call multiple opcodes when a notification-triggering event occurs, see "Calling Multiple Opcodes with One Notification-Triggering Event".
Disable entries in the list by inserting a number sign ( # ) at the beginning of the entry. For example:
# 301 0 /event/session
Save and close 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 a notification-triggering event is mapped to more than one opcode in the event notification list, the opcodes are called in the order they are listed whenever the event is generated. For example, the default event notification configuration file (pin_notify) includes the following 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 calls opcode 7854 (PCM_OP_MONITOR_ACCOUNT_HIERARCHY), then calls opcode 7855 (PCM_OP_MONITOR_BILLING_HIERARCHY), and finally calls opcode 7856 (PCM_OP_MONITOR_SERVICE_HIERARCHY).
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 opcode number of PCM_OP_ACT_POL_EVENT_NOTIFY.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".To load the event notification list:
Go to the directory that contains the event notification configuration files whose contents you want to load.
By default, event notification configuration files are in the BRM_home/sys/data/config directory.
Save the event notification 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.Run the following command, which loads the event notification list:
load_pin_notify event_notification_configuration_file_name
where event_notification_configuration_file_name is the name of the event notification file that contains the final event notification list.
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 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 CM.
(Only systems running EAI Manager) Stop and restart the EAI Data Manager (DM):
cd BRM_home/bin stop_dm_eai start_dm_eai
(Only systems running EAI Manager) Stop and restart the Payload Generator External Module (EM):
cd BRM_home/bin stop_eai_js start_eai_js
(Only systems running GSM Manager) Start the Provisioning DM:
start dm_prov_telco
Verify that the event notification list was loaded by using Object Browser or the testnap utility's robj command to display the config/notify object. See "Reading Objects by Using Object Browser" for information on how to use Object Browser. See "Using testnap" for general instructions on using testnap.
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 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 saved in the database. Instead, they are used only to populate the input flists of opcodes called by the event notification feature.