Configuring Revenue Assurance Alerts

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 event records rejected in one day exceeds a specified value.

Configuring revenue assurance alerts involves the following tasks:

Configure alert thresholds in the pin_config_ra_thresholds file, and load them into /config/ra_thresholds objects.

See "Configuring Alert Thresholds".
Configure email alerts as follows:
- Create the text of the email alerts in the ra_alert_message.locale file, and load it into /strings objects. See "Specifying Email Alert Text".
- Define email details, such as recipient information, in the pin_config_ra_alerts file, and load them into /config/ra_alerts objects. See "Specifying Email Alert Details".
Check for alerts periodically by using the pin_ra_check_thresholds utility.

See "Generating Revenue Assurance Alerts".
Configure event notification to call the PCM_OP_PROCESS_AUDIT_POL_ALERT policy opcode when the pin_ra_check_thresholds utility generates the /event/notification/ra_threshold event.

See "Configuring Event Notification for Revenue Assurance".

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 the chapter about billing in BRM Opcode Guide.

Configuring Alert Thresholds

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

The data you want to check and the time period in which it is checked.

See "Specifying Threshold Data and Time Periods".
Optional filter criteria to narrow results.

See "Specifying Threshold Filter Conditions".
Minimum and maximum threshold values for the data you specify.

See "Specifying Threshold Field Value Ranges".

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. Use this section to supplement the information in the file.

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

Specifying Threshold Data and Time Periods

You specify 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_Rrecordecords_Per_Day  /process_audit/batchstat/status  1  1  1  16:00:00  0  Secs

Table 6-1 provides explanations of the parameters in the definition.

Table 6-1 Threshold Parameters

Parameter	Description
Threshold Name	Specifies the threshold name used when the alert is issued. The name should be as descriptive as possible. For example, Duplicate_SMS_Records_Per_Week is a good name for a weekly alert for the number of duplicate SMS records.
Obj Type	Specifies the /process_audit subclass containing the threshold value to check. For example, to generate alerts when the number of rejected event records reaches a certain value, enter /process_audit/batchstat/status.
Date Range Type	Specifies the time range covered by the alert: Period alert: 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. See "Period Alert Example". Daily alert: Enter 1 to specify a daily alert that repeats 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. See "Daily Alert Example". Weekly alert: Enter 2 to specify an alert that runs 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. See "Weekly Alert Example".
WeekDay	Specifies 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 parameter does not apply to daily alerts. Set it to 0 for daily alerts.
Number of Units	Specifies how many days or weeks a daily or weekly alert is processed. For example, if a daily alert must be processed for five days, enter 5. Note: This parameter does not apply to period alerts. Set it to 0 for period alerts.
Start Offset	Specifies the time of day that the alert starts. Enter the start time in hours, minutes, and seconds, expressed in 24-hour format. For example, to start an alert at 4:00 p.m., 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 applies only to period alerts. For other alerts, set it 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.

Specifying Threshold Filter Conditions

You set filter conditions by specifying required values for one or more 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

Specifying Threshold Field Value Ranges

You specify threshold field value ranges in alerts so that when the thresholds are reached or crossed, the alert generates notifications. You set the ranges 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 threshold value ranges for the same field. This enables 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 threshold 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

Alert Threshold Examples

This section contains examples of the following threshold alert types:

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 event records exceeds 75 for that period:

RA_Threshold:
Rejected_Records_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 event records reaches 1000 for the day. The alert is scheduled to repeat for 90 days.

RA_Threshold:
Rejected_Records_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 records reaches 100 during that period and again when the number reaches 250. It is 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 configure alert details, use the "load_pin_config_ra_thresholds" utility to load them into the /config/ra_thresholds object. 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.

Loading Alert Details by Using load_pin_config_ra_thresholds

To load your threshold values into the BRM database:

Note:

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. If the utility fails, it does not overwrite the existing data.

Open the BRM_home/sys/data/config/pin_config_ra_thresholds file in a text editor.
Use the instructions and examples in pin_config_ra_thresholds to configure alert details.
Save and close the file.
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".

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

Configuring Email Alerts

Configuring email alerts involves the following tasks:

Specify the text you want in alert emails, and optionally localize that text.

See "Specifying Email Alert Text".
Specify email details, and load them into the database.

See "Specifying Email Alert Details".

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.

You can use the following substitution parameters in the file. They are replaced with appropriate information when the alert email is sent.

%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 the end time of the period for which the alert was generated.
%OBJECT_TYPE: Replaced with the 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 a new line. (Applicable to the message body only.)

The default subject line is the following:

Alert %ALERT_NAME has crossed defined threshold values.

The default message body is the following:

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.

After defining the email text, 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.

Note:

When loading a localized version of the file, use the correct file extension for your locale. For a list of file extensions, see "Locale Names" in BRM Developer's Guide.

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

Specifying Email Alert Details

You specify recipients and other details about email alerts in the pin_config_ra_alerts file. Specify the following 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

Specify the sender name and locale for each alert in a single line with the following 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 that appears in the From line of email messages.

You define recipients for each alert by specifying email addresses and types in a block below the RA_Alert line. Use the following 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. The following are valid values:

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_Records_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_Records_Per_Day  RA_NOTIFICATION  en_US 
  
RA_admin@mailserver.com  1
RA_operator@mailserver.com  2

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

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

Note:

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. If the utility fails, it does not overwrite the existing data.

To configure and load email alert details:

Open the BRM_home/sys/data/config/pin_config_ra_alerts file in a text editor.
Add your email details to the file. The file includes instructions and sample data.
Save and close the file.
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".

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

Generating Revenue Assurance Alerts

You use the "pin_ra_check_thresholds" utility to check alert thresholds periodically. 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 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 alert. You can customize the opcode to change the default alert behavior. See the chapter about billing in BRM Opcode Guide.

Note:

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.

Use the following command to run the pin_ra_check_thresholds utility:

pin_ra_check_thresholds

See "pin_ra_check_thresholds".