6 Configuring Revenue Assurance Alerts

This chapter describes how to configure alerts based on revenue assurance data collected in your Oracle Communications Billing and Revenue Management (BRM) system.

Before reading this chapter, read the following documents:

About Revenue Assurance Alerts

You can configure Revenue Assurance Manager to send alerts when the data collected meets criteria that you specify. For example, you can configure an alert to be sent when the number of EDRs rejected in one day exceeds a value that you specify.

Configuring and using revenue assurance alerts involves:

Alerts also require that event notification be configured. See "Configuring Event Notification" for more information.

You can customize the default alert behavior by changing the PCM_OP_PROCESS_AUDIT_POL_ALERT opcode. For example, you could customize the opcode to log alert information in addition to sending emails. For details, see "Customizing Alert Behavior" for more information.

Configuring Alert Thresholds

You configure alert thresholds in the pin_config_ra_thresholds file. When you configure an alert threshold, you define:

The values you specify work together to determine whether an alert is triggered. All conditions must be met for an alert to be triggered.

The pin_config_ra_thresholds file includes syntax information and examples. Consult the file for more information. Use this section to supplement the information in the file.

After your alert thresholds are defined in pin_config_ra_thresholds, you load that information into the database's /config/ra_thresholds objects. See "Loading Alert Details into the Database" for more information.

Defining Threshold Data and Time Periods

You define an alert threshold's data and time periods in a line with the following syntax:

RA_Threshold:
<Threshold Name> <Obj Type> <Date Range Type> <WeekDay> <Number of Units> <Start Offset> 
<Length of Period> <Secs/Mins/Hrs>
  

For example:

RA_Threshold:
Rejected_EDRs_Per_Day  /process_audit/batchstat/status  1  1  1  16:00:00  0  Secs
  

Table 6-1 describes the threshold parameters.

Table 6-1 Threshold Parameters

Parameter Description

Threshold Name

Defines the threshold name that is used when the alert is issued. The name should be as descriptive as possible. For example, Duplicate_SMS_EDRs_Per_Week is a good name for a weekly alert for the number of duplicate SMS EDRs.

Obj Type

Specifies the /process_audit subclass that contains the threshold value to be checked. For example, to generate alerts when the number of rejected EDRs reaches a certain value, enter /process_audit/batchstat/status.

Date Range Type

Determines the time range covered by the alert. There are three options:

  • Enter 0 to specify an alert configured for a specific time period. For example, you can configure a period alert to check data between 8:00 a.m. and 5:00 p.m. The time period is based on the process end time (PIN_FLD_PROCESS_END_T in the /process_audit object). Period alerts require a value for the Length of Period parameter.

  • Enter 1 to specify a daily alert configured to repeat on a 24-hour basis. For example, you can configure a daily alert to check data every day from 4:00 p.m. on the current day to 4:00 p.m. the next day.

  • Enter 2 to specify an alert configured to run for an entire week. For example, you can configure a weekly alert to check data from 8:00 a.m. Monday to 8:00 a.m. the following Monday.

WeekDay

Indicates the day of the week on which a period or weekly alert is processed. Each day is represented by a numerical value between 1 (Sunday) and 7 (Saturday).

Note: This entry is not valid for daily alerts; set the value to 0.

Number of Units

Indicates how many days or weeks a daily or weekly alert will be processed. For example, if a daily alert needs to be processed for five days, enter 5.

Note: This entry is not applicable to period alerts. Set the value to 0 if you are configuring a period alert.

Start Offset

Specifies the time of day at which the alert starts. This value should be specified the start time in hours, minutes, and seconds, expressed in 24-hour format. For example, to start an alert at 4:00 p.m., you must specify the start offset time as 16:00:00.

Length of Period

Specifies the duration of period alerts, expressed in seconds, minutes, or hours (depending on the value specified in the Secs/Mins/Hrs parameter). The duration must be less than or equal to one week.

Note: This parameter is applicable only to period alerts. For other alert types, set to 0.

Secs/Mins/Hrs

Specifies the time unit that applies to the Length of Period parameter - seconds (Secs), minutes (Mins), or hours (Hrs). This value is ignored for daily and weekly alerts.


Defining Filter Conditions

You set filter conditions by specifying required values for a field or fields in the /process_audit objects defined for the threshold. For example, if the threshold is checking /process_audit/batchstat/status objects, you could specify that the value of the PIN_FLD_EDR_STATUS field must be REJECTED.

You can enter more than one filter for a threshold. Data must meet all filter conditions.

You define filter conditions with the following syntax:

RA_Filter:
<Filter Field Name>  <Filter Int Value>  <Filter String Value>
<Filter Field Name>  <Filter Int Value>  <Filter String Value>
  

For example:

RA Filter:
PIN_FLD_GROUP_DETAILS.PIN_FLD_EDR_STATUS  0  REJECTED
PIN_FLD_GROUP_DETAILS.PIN_FLD_SVC_TYPE  0  SMS

Defining Field Value Ranges

You define threshold values in alerts so that when the thresholds are reached or crossed, the alert generates notifications. You set threshold values by specifying a minimum and maximum value for a field in the /process_audit objects defined for the threshold. For the threshold to be reached, the value of the field must be less than or equal to the minimum value or greater than or equal to the maximum value.

For example, if the threshold applies to /process_audit/batchstat/status objects, you could specify 0 and 75 as the minimum and maximum value for the PIN_FLD_EDR_COUNT field.

You can define multiple field value ranges for the same field. This allows you to send a new alert when the field value reaches a new threshold. For example, you could define an additional field value range for the PIN_FLD_EDR_COUNT field with a maximum of 150. This would trigger an alert if the value continues to rise after the initial alert at 75.

You define the field value range with the following syntax:

RA_Field_Value_Range:
<Field Name>  <Max_Field_Value>  <Min_Field_Value>
<Field Name>  <Max_Field_Value>  <Min_Field_Value>
  

For example:

RA_Field_Value_Range:
PIN_FLD_GROUP_DETAILS.PIN_FLD_EDR_COUNT  50  0
PIN_FLD_GROUP_DETAILS.PIN_FLD_EDR_COUNT  150 0

Period Alert Example

This period alert runs from 8 a.m. to 5 p.m. every Friday, and is triggered when the number of rejected EDRs exceeds 75 for that period:

RA_Threshold:
Rejected_EDRs_Per_Day  /process_audit/batchstat/status  0  6  0  08:00:00  9  Hrs
  
RA Filter:
PIN_FLD_GROUP_DETAILS.PIN_FLD_EDR_STATUS  0  REJECTED
  
RA_Field_Value_Range:
PIN_FLD_GROUP_DETAILS.PIN_FLD_EDR_COUNT  75  0

Daily Alert Example

This alert runs daily starting at 4:00 p.m. It is triggered when the number of rejected EDRs reaches 1000 for the day. The alert is scheduled to repeat for 90 days.

RA_Threshold:
Rejected_EDRs_Per_Day  /process_audit/batchstat/status  1  0  90  16:00:00  0  Secs
  
RA Filter:
PIN_FLD_GROUP_DETAILS.PIN_FLD_EDR_STATUS  0  REJECTED
  
RA_Field_Value_Range:
PIN_FLD_GROUP_DETAILS.PIN_FLD_EDR_COUNT  1000  0

Weekly Alert Example

This alert runs weekly starting at 8:00 a.m. on Monday. It is triggered when the number of rejected SMS EDRs reaches 100 during that period and again when the number reaches 250. It will be valid for an entire year (52 weeks).

RA_Threshold:
Reject_SMS_EDRs_Week  /process_audit/batchstat/svctype_revstream  2  2  52  08:00:00  0  Secs
  
RA Filter:
PIN_FLD_GROUP_DETAILS.PIN_FLD_EDR_STATUS  0  REJECTED
PIN_FLD_GROUP_DETAILS.PIN_FLD_SVC_TYPE  0  SMS
  
RA_Field_Value_Range:
PIN_FLD_GROUP_DETAILS.PIN_FLD_EDR_COUNT  100  0
PIN_FLD_GROUP_DETAILS.PIN_FLD_EDR_COUNT  250  0

Loading Alert Details into the Database

After you have configured alert details, you use the load_pin_config_ra_thresholds utility to load them into the /config/ra_thresholds object. See "load_pin_config_ra_thresholds". The pin_ra_check_thresholds utility then uses the threshold information in the /config/ra_thresholds object to search revenue assurance data when it generates alerts. See "pin_ra_check_thresholds".

Loading Alert Details by Using load_pin_config_ra_thresholds

To load your threshold values into the BRM database:

Important:

The load_pin_config_ra_thresholds utility needs a configuration (pin.conf) file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide for more information. If the utility fails, it does not overwrite the existing data.
  1. Open the BRM_Home/sys/data/config/pin_config_ra_thresholds file in a text editor.

  2. Use the instructions and examples in pin_config_ra_thresholds to configure alert details.

  3. Save and close the file.

  4. Load the alert details into the database by using this command:

    load_pin_config_ra_thresholds pin_config_ra_thresholds
      
    

    If you do not run the utility from the directory in which the file is located, include the complete path to the file; for example:

    load_pin_config_ra_thresholds BRM_Home/sys/data/config/pin_config_ra_thresholds
    

    Tip:

    If you copy the pin_config_ra_thresholds file to the directory from which you run the load_pin_config_ra_thresholds utility, you do not have to specify the path or file name. The file must be named pin_config_ra_thresholds.

    See "load_pin_config_ra_thresholds" for more information.

    To verify that the alert details were loaded, display the /config/ra_thresholds object by using Object Browser, or use the robj command with the testnap utility. See "Reading an Object and Writing its Contents to a File" in BRM Developer's Guide for more information.

Configuring Email Alerts

Configuring email alerts involves these tasks:

Specifying Email Alert Text

You configure the subject and message body of email alert messages in the locale of your choice. To configure email alert messages in U.S. English, edit the BRM_Home/sys/msgs/revenueassurance/ra_alert_message.en_US file. This file includes a default subject line and message body that you can edit. The file also includes information about syntax and required elements, which follow standard rules for localized string files. See "Localizing and Customizing Strings" in BRM Developer's Guide for more information.

You can use substitution parameters in the file that are replaced with appropriate information when the alert email is sent. These are the substitution parameters you can use:

  • %ALERT_NAME: Replaced with the alert name.

  • %START_TIME: Replaced with the start time of the period for which alert was generated.

  • %END_TIME: Replaced with end time of the period for which alert was generated.

  • %OBJECT_TYPE: Replaced with object type value configured for the alert.

  • %FILTERS: replaced with the field-value pairs of the filter conditions defined for the alert.

  • %THRESHOLD_VALUES: Replaced with the field and corresponding minimum and maximum limits defined for the alert.

  • %LINE_BREAK: Replaced with new line. (Applicable to the message body only.)

The default subject line is:

Alert %ALERT_NAME has crossed defined threshold values. 
  

The default message body defined in the file is:

The alert %ALERT_NAME has crossed defined threshold values for the period %START_TIME to %END_TIME. %LINE_BREAK The alert is configured as given below: %LINE_BREAK ObjectType = %OBJECT_TYPE %LINE_BREAK Filter = %FILTERS %LINE_BREAK Threshold Values = %THRESHOLD_VALUES" 
  

You can define localized versions of the email alert text by creating ra_alert_message.locale files with the appropriate file name extension for the locales. See "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide for more information.

After defining the email text, you use the load_localized_strings utility to load the contents of the file into the /strings objects.

The load command syntax is as follows:

load_localized_strings ra_alert_message.locale

See "load_localized_strings" in BRM Developer's Guide for more information.

Note:

When loading a localized version of this file, be sure to use the correct file extension for your locale. See "Locale Names" in BRM Developer's Guide for a list of file extensions.

See "Loading Localized or Customized Strings" in BRM Developer's Guide for more information.

Specifying Email Alert Details

You specify recipients and other details about email alerts in the pin_config_ra_alerts file. You specify these details for each alert:

  • Name of the alert

  • Locale to be used for subject and email body.

    The locale determines which localized version of the alert text is sent.

  • Name of the sender

  • Email addresses of recipients

You define the sender name and locale for each alert in a single line with this syntax:

RA_Alert: Alert_Name Sender_Name Locale

Note:

Each entry must begin with RA_Alert; the text is case-sensitive.

The Alert_Name parameter must be the name of an alert as defined in the pin_config_ra_thresholds file. The sender name is the name you want to appear in the From line of emails.

You define recipients for each alert by specifying email addresses and types in a block below the RA_Alert line. Use this syntax:

Email_addr_1 Email_Type> 
Email_addr_2 Email_Type> 
Email_addr_3 Email_Type> 
  

The email type is optional. It determines how the email is sent to the recipient. Valid values are:

  • 1 - Email is addressed directly to the recipient.

  • 2 - The recipient receives a copy (CC).

  • 3 - The recipient receives a blind copy and does not see other recipients (BCC).

  • 4 - Specifies that the address is to be used as the Reply To value in the alert message.

    This address is not a recipient of the alert email.

The default value is 1, which is used if no type is specified.

The following example configures email notification for the Rejected_EDRs_Per_Day alert. The sender of alert emails is RA_NOTIFICATION. The primary recipient is RA_admin@mailserver.com and RA_operator@mailserver.com receives a copy.

RA_Alert:  Rejected_EDRs_Per_Day  RA_NOTIFICATION  en_US 
  
RA_admin@mailserver.com  1
RA_operator@mailserver.com  2
  

For additional information see, the BRM_Home/sys/data/config/pin_config_ra_alerts file, which includes syntax information and examples.

After configuring alert details, you load the file into the database by using the load_pin_config_ra_alerts utility. See "load_pin_config_ra_alerts". Email alert data is stored in the /config/ra_alerts object.

Important:

The load_pin_config_ra_alerts utility needs a configuration (pin.conf) file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide for more information. If the utility fails, it does not overwrite the existing data.

To configure and load email details:

  1. Open the BRM_Home/sys/data/config/pin_config_ra_alerts file in a text editor.

  2. Add your email details to the file. The file includes instructions and sample data.

  3. Save and close the file.

  4. Load the email details into the database by using this command:

    load_pin_config_ra_alerts pin_config_ra_alerts
      
    

    If you do not run the utility from the directory in which the file is located, include the complete path to the file; for example:

    load_pin_config_ra_alerts BRM_Home/sys/data/config/pin_config_ra_alerts
    

    Tip:

    If you copy the pin_config_ra_alerts file to the directory from which you run the load_pin_config_ra_alerts utility, you do not have to specify the path or file name. The file must be named pin_config_ra_alerts.

    See "load_pin_config_ra_alerts" for more information.

To verify that the email details were loaded, you can display the /config/ra_alerts object by using Object Browser, or use the robj command with the testnap utility. See "Reading an Object and Writing its Contents to a File" in BRM Developer's Guide for more information.

Generating Revenue Assurance Alerts

You use the pin_ra_check_thresholds utility to check alert thresholds periodically. See "pin_ra_check_thresholds". You can run pin_ra_check_thresholds as part of a chron, chrontab, or at script, or you can run it manually.

This utility checks the /config/ra_thresholds object for the revenue assurance thresholds you have set. If it finds that a threshold has been crossed, it generates a notification event that causes the PCM_OP_PROCESS_AUDIT_POL_ALERT policy opcode to prepare and send an email. You can customize the opcode to change the default alert behavior. See "Customizing Alert Behavior" for more information.

Important:

The pin_ra_check_thresholds utility needs a configuration (pin.conf) file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide for more information.

Use this command to run the pin_ra_check_thresholds utility:

pin_ra_check_thresholds
  

See "pin_ra_check_thresholds" for more information.