5 Providing In-Session Notifications for Network Connectivity Applications

This chapter describes how you can provide improved notifications in real time when performing authentication, authorization, and accounting (AAA) for prepaid services using Oracle Communications Billing and Revenue Management (BRM) in conjunction with a network connectivity application.

About AAA Responses Containing In-Session Notifications

By default, the AAA response to an authorization or reauthorization request for a service contains the result (pass or fail) of the request and its reason and other details, such as current balances and reservations. You also have the option of providing, in real time, additional time-critical information about the request in these AAA responses. This additional information enables you to notify the subscriber, who can then take appropriate action (in real time).

For example, a subscriber makes a request to download a video. The network receiving the video download request forwards the request to the network connectivity application, which then sends the request to BRM. BRM processes the request and adds information on the subscriber's streaming usage threshold in its response to the network application. The network informs the subscriber that the streaming usage threshold is reaching its limit. The subscriber takes the necessary action in real time to address the situation.

The notifications that BRM appends to the responses for authorization and reauthorization requests from the network are called in-session notifications.

Such online charging functionality is made possible when you use BRM in conjunction with a network connectivity application (such as the Online Mediation Controller component of Oracle Communications Service Broker).

Note:

The in-session notifications described in this chapter are different from the offer profile threshold breach notifications BRM sends to the network policy controller.

BRM supports offer profile threshold breach notifications when offer profiles are included in price lists for policy-driven charging for services. They are sent when a subscriber's usage of a resource crosses a threshold set in the offer profile for the service and purchased plan.

For more information, see "Policy-Driven Charging" in BRM Setting Up Pricing and Rating.

About the Flow of Information Between BRM and the Network Connectivity Application

Information between BRM and the network connectivity application flows in the following way:

1. When a subscriber attempts to access a service, the network sends an authorization (or reauthorization) request to the network connectivity application.

2. The network connectivity application analyzes the request from the network, translates the information as necessary for BRM, and calls an appropriate AAA opcode to process the request.

3. BRM processes the request by using the details in the service request and the information in the subscriber's account (such as the current balances, credit thresholds, subscription information, and so on). BRM uses the subscriber profile information in the subscriber profile repository and appends in-session notifications about the request to the AAA response.

4. BRM sends the response back to the network connectivity application.

5. The network connectivity application uses the additional appended information in the response to provide appropriate pre-call and mid-call announcements to the the subscriber.

6. The subscriber takes the appropriate action based on the announcement he receives from the network.

About In-Session Notifications in BRM

In-session notifications are optional features in the AAA responses provided by BRM to network connectivity applications. For more information, see "Enabling In-Session Notifications".

About the Conditions that Trigger In-Session Notifications

The following conditions in processing AAA requests trigger in-session notifications:

• When the current balance together with the reserved amount reaches the credit threshold configured for the resource in the purchased plan (in Customer Center)

• When the current balance in a customer's account and the reserved amount of the configured resource together exceed the streaming usage amounts maintained as a non-currency usage counter for that account

• When the subscription for a requested service is about to expire.

• If a tariff change is impending for the resource in the AAA request, BRM sets up a tariff change indication in the response to prevent a spike in the number of reauthorization requests.

Note:

When a call request is denied, the AAA response for that call request contains the details associated with the call denial only. BRM does not append any in-session notification to such a response. See "How BRM Provides Call Denial Notifications".

About the Maximum Scaled Delay Time for Tariff Changes

The maximum scaled delay time for a resource is the maximum delay that can be returned to the caller for that resource. The higher the value of the maximum scaled delay time, the longer the scaled delay and, thus, the later the reauthorization. If you have a large customer base, you may need to increase the maximum scaled delay time to spread out the reauthorizations over a longer period of time and thereby reduce network spikes more effectively.

BRM stores the maximum scaled delay time value in the MaxScaledDelayTime field for each resource ID in the /config/aaa object.

About the Opcode Used to Set Up In-Session Notifications

The PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode sets up in-session notifications for one or more of the following, using the details in the AAA request and the current data in the subscriber's account:

• If there was a credit threshold breach for a requested resource, the policy opcode places the balance details for that resource in the notification.

  See "How BRM Provides Credit Threshold Breach Notifications".

• The opcode places the timestamp for when the service will expire as an in-session notification and enters the current time in the subscriber's preference.

  See "How BRM Provides Subscription Expiration Notifications".

• If the resource is being monitored for streaming usage and the streaming usage threshold was breached, the policy opcode enters the breach information as an in-session notification.

  See "How BRM Provides Streaming Usage Threshold Summaries".

• If there is an impending tariff change, the policy opcode calculates the scaled delay time for the resource and uses it to calculate when the tariff change is to occur.

  See "How BRM Provides Tariff Change Indication in the AAA Responses".

The PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode returns the information it received from the calling opcode along with the created in-session notifications and the subscriber's preferences for announcements.

About Service-Related Information in the In-Session Notifications

In-session notifications appended to AAA responses contain information on one or more of the following:

• Credit threshold breach notifications contain information on current balances, credit thresholds, and so on.

• Streaming usage and credit summaries contain information on the current balance for the resource that crosses the subscriber's usage limit.

• Subscription expiration notifications contain the service expiration time from the /service object.

• Notifications of impending tariff changes for a service specify when the validity period ends for that service (the time when the tariff change is to take place).

See "How BRM Provides In-Session Notifications" for the AAA opcodes that provide this information. For the data contained in the in-session notifications, refer to the output flist of these AAA opcodes in Opcode Flist Reference in the BRM documentation.

About Subscriber's Preferences Data in In-Session Notifications

The following information from a subscriber's /profile/subscriber_preferences object are sent in the in-session notifications appended to the responses for the subscriber's requests:

• Preferred language

• Preferred channel

• Preferred time

In addition to this, the /profile/subscriber_preferences object contains information used to set up in-session notifications. See "Managing Subscriber Preferences" for more information.

Configuring Your Environment to Provide In-Session Notifications

To configure your environment to provide in-session notifications:

1. Enable in-session notifications in BRM.

   See "Enabling In-Session Notifications".

2. Provide the maximum scaled delay time allowed for tariff changes.

   See "About Configuring the Maximum Scaled Delay Time for a Resource".

3. Set up subscriber preferences data.

   For information on setting up subscriber preferences data using Customer Center, see "Maintaining Subscriber Preferences with Customer Center".

   For information on setting up subscriber preferences data using APIs, see "Maintaining Subscriber's Preferences Data with Custom Client Applications".

4. To provide subscription expiration notifications to your subscribers, enable custom service life cycles in BRM.

   See "Enabling BRM to Use Custom Service Life Cycles" in BRM Managing Customers.

For information on how to customize the handling of in-session notifications from BRM, see "Customizing the Handling of In-Session Notifications from BRM".

Enabling In-Session Notifications

To enable in-session notifications, enable the Piggyback business parameter in the following way:

1. Go to the BRM_Home/sys/data/config directory, where BRM_Home is the directory in which you installed BRM.

2. Run the following command, which creates an editable XML file from the AAA instance of the /config/business_params object:

   pin_bus_params -r BusParamsAAA bus_params_AAA.xml
   

   This command creates the XML file named bus_params_AAA.xml.out in your working directory. To place this file in a different directory, specify the path as part of the file name.

3. Open the bus_params_AAA.xml.out file.

4. Search for the following line.

   <Piggyback>disabled</Piggyback>
   

5. Change disabled to enabled.

   Caution:

   BRM uses the XML in this file to overwrite the existing AAA instance of the /config/business_params object. If you delete or modify any other parameters in this file, your changes affect the associated aspects of the BRM configurations.

6. Save this file as bus_params_AAA.xml.

7. Go to the BRM_Home/sys/data/config directory.

8. Load this change into the appropriate /config/business_params object by running the following command:

   pin_bus_params PathToWorkingDirectory/bus_params_AAA.xml
   

   where PathToWorkingDirectory is the directory in which bus_params_AAA.xml resides.

   Note:

   To run this command from a different directory, see the description for pin_bus_params in BRM Developer's Guide.

9. Read the object with the testnap utility or Object Browser to verify that all fields are correct.

   See "Using Testnap" in BRM Developer's Guide for instruction on using the testnap utility. See "Reading objects by using Object Browser" in BRM Developer's Guide for information on how to use Object Browser.

10. Stop and restart the Connection Manager (CM). For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

About Configuring the Maximum Scaled Delay Time for a Resource

To configure the maximum scaled delay time for a specific resource, edit the appropriate AAA parameters XML file from among the following files located in the BRM_Home/sys/data/config directory.

• pin_telco_aaa_params.xml

• pin_telco_gprs_aaa_params.xml

• pin_telco_gsm_aaa_params.xml

• pin_telco_gsm_data_aaa_params.xml

• pin_telco_gsm_fax_aaa_params.xml

• pin_telco_gsm_sms_aaa_params.xml

• pin_telco_gsm_telephony_aaa_params.xml

You then load each updated file into the BRM database's /config/aaa object by running the load_pin_telco_aaa_params utility.

See "Configuring Services Framework AAA Parameters XML Files" for a description of how to edit and load the AAA parameters XML file into the BRM database.

How BRM Provides In-Session Notifications

BRM provides in-session notifications in the responses to AAA requests received during a prepaid session and when called upon to end the prepaid session.

During a prepaid session, the network connectivity application calls one of the following opcodes depending on whether the request requires an authorization or reauthorization:

• PCM_OP_TCF_AAA_AUTHORIZE

• PCM_OP_TCF_AAA_REAUTHORIZE

• PCM_OP_TCF_AAA_UPDATE_AND_REAUTHORIZE

When the network ends the prepaid session, the network connectivity application calls PCM_OP_TCF_AAA_STOP_ACCOUNTING, the main opcode for ending prepaid sessions.

Each of these opcodes calls the PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode at the end of its process. Each opcode provides the service or the account information from the processing of the request in its input to the PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode. The policy opcode returns the input values with the appropriate in-session notifications appended to them. The calling opcode receives the output from the PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode and sends that information to the network connectivity application.

See "How BRM Processes Prepaid AAA Requests" for more information on the individual processes.

How BRM Provides Credit Threshold Breach Notifications

BRM provides credit threshold breach information in the in-session notifications if you have configured the necessary credit threshold information in the plans you offer your customers. For more information on credit thresholds, see "About applying credit limits to resources" in BRM Setting Up Pricing and Rating.

BRM calculates the charges for the required resource by using the PCM_OP_RESERVE_CREATE and the PCM_OP_RESERVE_EXTEND opcodes. After the charges are calculated, BRM compares the sum of the customer's balance and reserved amount for the required resource against the customer's credit threshold value. If this amount crosses the credit threshold value, BRM generates a notification.

For more information, see "Managing Customer Billing Information" in BRM Managing Customers.

How BRM Avoids Repetitions of Threshold Breach Notifications for a Session

To avoid multiple threshold breach notifications for the same resource, BRM maintains a list of the last credit thresholds breached for the current session in an /active_session object for each session. The PCM_OP_ACT_AUTHORIZE and PCM_OP_ACT_REAUTHORIZE opcodes record the credit breach information on the last credit thresholds breached for the current session in the /active_session object. See "How BRM Processes Prepaid AAA Requests" for more information.

How BRM Provides Subscription Expiration Notifications

BRM provides subscription expiration notifications if you have enabled custom service life cycles. See "Enabling BRM to Use Custom Service Life Cycles" in BRM Managing Customers.

The PCM_OP_TCF_AAA_POL_POST_PROCESS policy pocked sets up a subscription expiration notification in the following way:

1. It retrieves the following information:

   • The date and time when the current custom service state expires (PIN_FLD_SERVICE_STATE_EXPIRATION_T from the /service object).

   • The subscriber's preferences from the /profile/subscriber_preferences object:

     • The number of days for which the expiration notification must be sent (NotificationExpiry)

     • The interval between notifications in days (NotificationInterval)

     • The date and time when the last notification was sent for this service (SentNotificationTime)

   The opcode uses the date (without the time) from the timestamp value in all the associated time-related objects.

2. The policy opcode computes the date when the subscription expiration notification must start by using PIN_FLD_SERVICE_STATE_EXPIRATION_T in the corresponding /service object and NotificationExpiry.

   For example, if the current service state for a requested service expires on March 16 and the expiration notification must be sent for 8 days prior to the service expiration, the start date for the notification is March 8.

3. The policy opcode determines whether the current date belongs to the set of dates requiring a notification by applying the NotificationInterval value to the start date.

   Continuing with the example, if the start date for the notification is March 8 and the customer requires a 3-day interval between notifications, then, at this time, the dates when notifications must be sent are March 8, March 11, and March 14.

   The policy opcode does one of the following:

   • If the current date requires a notification (in our example, March 8, March 11, or March 14) and the SentNotificationTime field of the /profile/subscriber_preferences object is empty:

     • The policy opcode stores the current time in the SentNotificationTime field of the /profile/subscriber_preferences object. This entry now acts as the time the last notification was sent for this subscription.

     • The policy opcode places a description (for example, "Service Expiration") in the PIN_FLD_DESCR field and the current custom service state expiry time (from the /service object) in the PIN_FLD_EXPIRATION_T field of the PIN_FLD_PIGGYBACK_NOTIFICATIONS array.

   • If the current date is not one that requires a notification (in our example, it is not March 8, March 11, or March 14), the policy opcode does not set up any notification.

   The AAA opcode that receives the output from the PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode forwards this information to the network connectivity application for setting up and delivering the actual announcement to the subscriber.

How BRM Provides Streaming Usage Threshold Summaries

BRM provides streaming usage threshold summaries if you have configured the necessary non-currency counters in the rate plans you offer your customers. For more information on setting up non-currency counters in rate plans, see the discussion on setting up real-time rate plans in Pricing Center Help.

When it is called to process an authorization or reauthorization request, the PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode calculates the sum of the current balance for the non-currency usage amount and the amount to be reserved for this session. The opcode compares this computed value against the usage limit stored for this resource in the StreamingThreshold entry located in the subscriber's /profile/subscriber_preferences object.

If the computed value exceeds the usage limit, the policy opcode enters "Streaming Threshold reached" in the PIN_FLD_DESCR field and the current balance in the PIN_FLD_CURRENT_BAL field of the PIN_FLD_PIGGYBACK_NOTIFICATIONS array.

How BRM Provides Call Denial Notifications

A call request can be denied by any of the following:

• The opcode authorizing or reauthorizing the request: When the denial originates from the opcode authorizing or reauthorizing the request, the PIN_FLD_ERR_BUF or PIN_FLD_RESULT field in the output flist from the opcode contains the reason for the error.

• Reservation framework: When resources cannot be reserved for the requested service, the PIN_FLD_REASON field of the output flist from the opcode authorizing or reauthorizing the request contains the reason for the rejection.

• The rating process: When there is a failure in rating the event, the PIN_FLD_RATING_STATUS field contains the rating status entry. To interpret the rating status entry, see the BRM_Home/include/pin_rate.h file.

The opcode processing such a request from the network connectivity application sends the appropriate error code for the reason the call was denied as its output. In-session notifications are not included with any call denial response.

Call Denial Error Codes

Table 5-1 lists the possible call denial error codes and their values. See BRM System Administrator's Guide for information on troubleshooting.

Table 5-1 Error Values Returned for Call Denials

Field ID Containing Error Code	Error Codes
PIN_FLD_REASON	Error associated with reserving the resource: 0 (Authorization failure) 1 (Authorization success) 2 (Duplicate reservation found) 3 (Insufficient funds; partial reservation) 4 (No funds available) 5 (Insufficient Rated quantity) 6 (Invalid requested quantity)
PIN_FLD_RATING_STATUS	Status of quantity-based requests based on the rating process: 0 (Rating Successful) 1 (Zero quantity) 10 (No Scale to rate) 11 (No Candidate RUM) 12 (No Initial Products) 13 (Calc Max in Multi-RUM) 14 (No Matching RUM) 15 (No qualified products) 16 (No RUM) 17 (Status Mismatch) 18 (Product not in DB) 19 (No product in audit) 20 (No rate plan) 21 (No matching selector data) 22 (No rating currency) 23 (No valid rate span) 24 (No valid rate) 25 (No matching impact) 26 (Credit limit exceeded)
PIN_FLD_RESULT	Session or service related errors found: 0 (Authorization failure 0 (Authorization success
PIN_FLD_AUTHORIZATION_ID	PIN_ERR_DUPLICATE (An active session with the authorization ID already exists in database)
PIN_FLD_MSID	PIN_ERR_BAD_ARG (Service not found)
EBUF	PIN_ERR_CREDIT_LIMIT_EXCEEDED (Credit limit exceeded)

How BRM Provides Tariff Change Indication in the AAA Responses

BRM calculates and provides the tariff change time for a request if you have specified the maximum scaled delay time allowed before the tariff changes for the resource by configuring the MaxScaledDelayTime entry for the resource Id in the config/aaa object. See "About Configuring the Maximum Scaled Delay Time for a Resource".

BRM provides the maximum scaled delay time allowed for tariff changes for the resource in the PIN_FLD_VALID_TO entry of the notification. For example, the entry Thu Feb 16 05:12:07 2012 in the notification of a tariff change means that the old rates for the resource apply up to that time. After Thu Feb 16 05:12:07 2012, new rates apply, and the service request requires a reauthorization.

Network connectivity applications can use the tariff change time in the in-session notifications to prevent different sessions from returning for reauthorization at the same time.

How BRM Calculates the Scaled Delay Time for a Service

If a tariff change for a requested service is impending, BRM calculates the scaled delay time as a factor of the maximum scaled delay time (MaxScaledDelayTime) configured for that resource ID in the /config/aaa object.

Note:

If you have not configured MaxScaledDelayTime for that resource ID, BRM does not calculate or create a tariff change indication in the AAA response.

The PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode calculates the scaled delay time value as shown in Figure 5-1:

Figure 5-1 Scaled Delay Time Calculation

Description of ''Figure 5-1 Scaled Delay Time Calculation''

The PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode returns the computed scaled delay time in the PIN_FLD_VALID_TO field of the PIN_FLD_PIGGYBACK_NOTIFICATIONS array.

For more information on tariff change, see "Using Lightweight Authorization".

How BRM Provides Subscriber Preferences in Notifications

BRM sets up individual in-session notifications for the subscriber's preference for language, channel of communication and the preferred time for the announcements. It retrieves each of these values from the /profile/subscriber_preferences object associated with the account.

How the PCM_OP_TCF_AAA_POL_POST_PROCESS Policy Opcode Works

The PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode prepares the in-session notifications in the following way:

1. It retrieves the subscriber's current preference information by calling the PCM_OP_CUST_GET_SUBSCRIBER_PREFERENCES opcode. See "Maintaining Subscriber's Preferences Data with Custom Client Applications".

2. If you have enabled custom life cycles in BRM, it checks on the subscription status. If the subscriber's subscription is about to expire, a check is made to determine if a notification was already sent.

   • If a notification was not sent during this session, the PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode adds the subscription expiration notification to the output intended for the network connectivity application.

   • The policy opcode updates the subscriber's preferences with the time the notification was sent.

   See "Managing Custom Service Life Cycles" in BRM Managing Customers.

3. It checks whether the request is breaching the set threshold configured for the resource. If there is a threshold breach, the policy opcode appends an in-session notification for the breach. See "How BRM Provides Credit Threshold Breach Notifications".

4. If a streaming threshold usage notification was configured for the service or the account:

   1. The PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode retrieves the current balance and the reservation amount.

   2. It checks whether there are any breaches for the resource.

   3. It appends the streaming threshold counter in the in-session notification.

   See "How BRM Provides Streaming Usage Threshold Summaries".

5. The PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode calculates the scaled delay time and appends the tariff change for the resource in the PIN_FLD_VALID_TO field of the in-session notification.

   See "How BRM Provides Tariff Change Indication in the AAA Responses".

6. The PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode sets up the subscriber's preferences as in-session notifications to the response.

   See "How BRM Provides Subscriber Preferences in Notifications".

7. The PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode sends the updated in-session information to the calling opcode. For more information on this policy opcode, see Opcode Flist Reference in the BRM documentation.

Customizing the Handling of In-Session Notifications from BRM

You can customize how you handle in-session notifications from BRM in the following ways:

• Customize the configuration of the subscriber preferences data. Customer Center reads the configurations in the /config/subscriber_preferences_map object to dynamically list the preferences that a subscriber can configure in the Preferences Tab. See "Customizing Subscriber Preferences" for more information.

• Customize the information provided to the network connectivity application about the customer's service or account.

  See "Customizing AAA Processes by Extending Policies".

• Access and act upon credit threshold breaches using the testnap utility or external applications. See "About Setting Up Custom Applications to Receive Credit Threshold Breach Information".

Customizing AAA Processes by Extending Policies

A customer can be allocated a custom bandwidth, and that custom data has been stored in the /profile/subscriber_preferences object. You can read in this information and add it to the AAA response that the PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode sends to the network connectivity application.

To customize the processing of the AAA requests by extending the policies associated with AAA requests:

1. Retrieve the subscriber's preference data by calling the PCM_OP_CUST_GET_SUBSCRIBER_PREFERENCES opcode.

2. Perform your operations.

3. Update the data stored for the user by calling the PCM_OP_CUST_SET_SUBSCRIBER_PREFERENCES opcode.

4. Return the values in the output flist of the PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode.

See Opcode Flist Reference in the BRM documentation for more information on the PCM_OP_TCF_AAA_POL_POST_PROCESS policy opcode.

About Setting Up Custom Applications to Receive Credit Threshold Breach Information

You can set up the testnap utility or custom applications that you create to receive credit threshold breach information from the following AAA opcodes:

• PCM_OP_ACT_AUTHORIZE

• PCM_OP_ACT_REAUTHORIZE

• PCM_OP_RESERVE_CREATE

• PCM_OP_RESERVE_EXTEND

To receive credit threshold information from any of the above opcodes, set the PIN_FLD_PIGGYBACK_FLAG field to enabled in the input flist when you call the specific opcode.

See Opcode Flist Reference in the BRM documentation, for more information on these opcodes.

How Network Connectivity Applications Orchestrate Prepaid Sessions

Network connectivity applications use the information in the authorization or reauthorization request to select the logic appropriate to orchestrate a prepaid session and call the appropriate AAA opcode in BRM. Figure 5-2 shows how the flow works for a prepaid session:

Figure 5-2 Session-Based Request Flow

Description of ''Figure 5-2 Session-Based Request Flow''

Before the start of the session, the network connectivity application calls PCM_OP_TCF_AAA_AUTHORIZE with the necessary call details and subscriber information required by BRM to authorize the session. BRM does the following:

• It checks the subscriber's profile and the account balances and responds by authorizing the session (or denying the request).

• It appends notifications (associated with the service, credit thresholds, any tariff indications, and so on) to the response.

• It returns the response.

Based on this response, the network connectivity application may set up appropriate pre-call announcements to be delivered to the subscriber.

For the duration of the session, there may be updated requests from the network. These updated requests trigger the network connectivity application to call PCM_OP_TCF_AAA_UPDATE _AND_REAUTHORIZE with the necessary call details and subscriber information required by BRM. BRM does the following:

• It checks the subscriber's profile and the account balances and responds by authorizing the session (or denying the request).

• It appends the appropriate mid-call notifications in its response.

• It returns the response.

The network connectivity application converts these notifications into appropriate mid-call announcements to be delivered to the subscriber.

When the session ends, the network sends a request to the network connectivity application to terminate the session. The network connectivity application calls the PCM_OP_TCF_AAA_STOP_ACCOUNTING opcode to end the prepaid session. BRM records the usage event in the database and appends any in-session notifications in the response it sends to the network connectivity application.