This chapter provides an overview of Oracle Communications Billing and Revenue Management (BRM) Services Framework AAA Manager and describes how to implement AAA functionality for any service type.
Before you read this document, you should be familiar with BRM concepts and architecture. See BRM Concepts.
Services Framework AAA Manager performs authentication, authorization, and accounting (AAA) for prepaid services. For example, when a prepaid customer uses a service, Services Framework AAA Manager performs the following:
Verifies the customer's identity by using the device ID.
Determines whether the customer's prepaid balance contains enough resources to cover the cost of usage.
If you enabled in-session notifications, Services Framework AAA Manager provides in-session notifications in the AAA responses to your supported network connectivity application. See "Providing In-Session Notifications for Network Connectivity Applications".
Reserves a portion of the customer's resources for the session.
If you enabled in-session notifications, Services Framework AAA Manager provides in-session notifications in the AAA responses to your supported network connectivity application. See "Providing In-Session Notifications for Network Connectivity Applications".
Records information about any usage while it is in progress.
When a session ends, rates the customer's usage and updates the customer's prepaid balance.
If you enabled in-session notifications, Services Framework AAA Manager provides in-session notifications in the AAA responses to your supported network connectivity application. See "Providing In-Session Notifications for Network Connectivity Applications".
For more information about how BRM performs AAA, see "Understanding Prepaid AAA".
Services Framework AAA Manager is a generic framework of opcodes, storable classes, and utilities that allows you to quickly implement AAA support for any service type. BRM service managers, such as GSM AAA Manager and GPRS AAA Manager, as well as custom service managers are built on top of the generic framework.
Services Framework AAA opcodes are abstract, generic opcodes designed to process AAA requests for any service type. They perform AAA operations that are common to all service types, such as searching for storable objects and passing information to the Activity FM standard opcodes, and rely upon helper opcodes to perform service-specific functions. For example, helper opcodes build search templates and aggregate service-specific data.
Services Framework AAA standard opcodes call helper opcodes during any of these stages in the opcode's execution:
SEARCH_SESSION
PREP_INPUT
VALIDATE_LIFECYCLE
ACC_ON_OFF_SEARCH
TAG_SESSION
POST_PROCESS
At each processing stage, the opcodes determine which helper opcode to call by reading the /config/opcodemap/tcf object. By default, the opcodes call the Services Framework helper opcodes. See "Preparing Service-Specific Data by Using Helper Opcodes".
You configure the Services Framework AAA opcodes to call helper opcodes by using the "load_aaa_config_opcodemap_tcf" utility. See "Configuring Services Framework to Call Helper Opcodes".
BRM stores information about prepaid sessions in these storable classes.
/active_session/telco: Stores information about prepaid sessions that are in progress. This object can be subclassed for specific service types.
/event/session/telco: Stores information about a prepaid session that has been rated and closed. This object can be subclassed for specific service types.
/reservation: When your system does not include IMDB Cache, stores information about a single reservation for one balance group.
For policy-driven sessions, this object holds the consumed reservation amount for the resource.
/reservation/active: When your system includes IMDB Cache, stores information about a single reservation for one balance group.
/reservation_list: Tracks the total resources a balance group has reserved in /reservation/active objects.
/config/reserve: Stores the default authorization and reauthorization values for specific service types. This object can be subclassed for specific service types.
See "Specifying Default Authorization and Reauthorization Values" for information on how to load this object.
/config/aaa: Stores configuration information on how to manage session objects. See "Configuring How Services Framework AAA Manages Session Objects" for information on how to load this object.
Stores the maximum value permitted for the scaled delay for a resource to be used when providing the tariff change indication in the in-session notifications to network connectivity applications. See "About Configuring the Maximum Scaled Delay Time for a Resource".
/config/opcodemap/tcf: Stores the mappings between Services Framework AAA opcodes and helper opcodes. See "Configuring Services Framework to Call Helper Opcodes" for information on how to load this object.
You use Services Framework AAA Manager utilities to specify default preferences for processing events, including the following:
How to store and rate accounting subsessions.
Whether to keep or delete /active_session and /reservation/active objects when a prepaid session ends.
Whether to check for duplicate /active_session or /event/session objects.
The expiration time interval for /active_session objects stored in memory.
Default authorization and reauthorization values for services. BRM authorizes prepaid customers to use a service for a specified duration, volume, or amount. For example, BRM can authorize customers to initially make a 10 minute telephone call or download 100 bytes of data.
See "Specifying Default AAA Preferences".
If you enabled in-session notifications, you use Services Framework AAA Manager utilities to specify default preferences for the following:
The maximum scaled delay time by resource ID. See "About Configuring the Maximum Scaled Delay Time for a Resource".
The subscriber preferences for in-session notifications. See "Customizing Subscriber Preferences".
When a service manager calls a Services Framework AAA opcode, the opcode performs the following:
Retrieves the customer's account information.
At the SEARCH_SESSION processing stage, calls the helper opcode specified in the /config/opcodemap/tcf object. The helper opcode returns a search template for finding /event/session or /active_session objects.
Uses the search template returned by the helper opcode to find duplicate sessions.
At the PREP_INPUT stage, calls the helper opcode specified in the /config/opcodemap/tcf object. The helper opcode aggregates service-specific data and prepares a service-specific input flist.
At the VALIDATE_LIFECYCLE stage, calls the helper opcode specified in the /config/opcodemap/tcf object to validate the request if the service uses a custom life cycle. If validation succeeds, processing continues. If validation fails, the request is denied.
Passes the input flist returned by the helper opcode to an Activity FM standard opcode. The Activity opcode rates or records the event and then returns that the request succeeded or failed.
At the POST_PROCESS stage, calls the helper opcode specified in the /config/opcodemap/tcf object. The helper opcode aggregates service-specific data and returns a service-specific input flist.
Returns to the caller that the request either succeeded or failed.
A customer may use multiple services during a call connection. For example, a customer may send text messages and access email during one connection. The external network connects the service by opening a PDP context and then begins collecting usage information. The external network sends the usage data to BRM, which stores all of the information in one session object.
You can set up your BRM system to track and rate the usage for each service separately by using master sessions and subsessions. The master session tracks the usage for the first service accessed during the connection. Each subsession tracks the usage for each subsequent service that is accessed during the connection. For example, if a customer sends a text message and then accesses email during one connection, BRM stores the text message usage data in a master session and the email usage data in a subsession. This enables BRM to rate each service separately, based on the service's specific rating criteria.
To track data in master sessions and subsessions, you must:
Configure your external network to call BRM each time a master session or subsession starts. It must also call BRM each time a network trigger, such as a quality of service (QoS) change, occurs.
Configure your external network to flag each session as a master session or a subsession.
(Optional) Set up your system to store master session and subsession data in separate storable class extensions.
Configure your external network to notify BRM when the last subsession has ended.
Configure how BRM manages and rates master sessions and subsessions.
If a session includes both a master session object and one or more subsession objects, BRM performs one of the following at the end of the session:
Aggregates the data from the master and subsession objects into one session object.
Stores the data for each master and subsession object separately.
You specify how BRM manages subsession data by setting the subsession rating mode.
Table 20-1 describes how each rating mode stores and rates subsession data:
Table 20-1 Rating Modes and Subsession Data
| Rating Mode | How Subsession Data is Stored | When a Subsession is Rated and Closed | Description |
|---|---|---|---|
|
Rate mode |
In separate subsession objects. |
When each subsession ends. |
Master and subsessions are treated as separate AAA sessions and are rated separately. The master and subsession objects are created on receipt of the authorization request. The master and subsession objects are closed and rated, and the event is recorded on receipt of each subsession's stop accounting request. |
|
Deferred rate mode |
In separate subsession objects. |
When the last subsession ends. |
Master and subsessions are treated as separate AAA sessions and are rated separately. The master and subsession objects are created on receipt of the authorization request. The master and subsession objects are rated, and the event is recorded when the final stop accounting request is received. |
|
Aggregate mode |
In one master session object. |
When the last subsession ends. |
Usage information for subsessions is aggregated and recorded in a single usage event. During authorization of subsessions, new /active_session and /reservation objects are created. During stop accounting of subsessions, all of the /active_session objects are aggregated and a single event is created. Note: By default, only volume and amount are aggregated. |
For example, a customer connects to the network to download email and then in parallel wants to view a movie extract during the same connection. Because the customer uses the same connection for both services, BRM treats the usage as one session. However, because the email download may finish before the streaming session ends, BRM can optionally record the usage in two separate objects: a master session object that tracks the volume of email downloaded, and a subsession object that tracks both the volume and duration of the streaming session. If the rating mode is set to deferred rate mode, BRM waits until both the email download and streaming session have ended and then rates both usages at the same time.
You configure the rating mode by using the load_pin_telco_aaa_params utility. See "Configuring How Services Framework AAA Manages Session Objects".
When a customer accesses multiple services during a connection, BRM, by default, treats all the usage data as one AAA session.
To flag session data as a master session or a subsession, configure your external network to pass the following two input flist fields in the call to the Services Framework AAA opcodes:
PIN_FLD_SESSION_TYPE set to 0 for a normal session, 1 for a master session, or 2 for a subsession. The default is 0.
PIN_FLD_NETWORK_SESSION_CORRELATION_ID set to the unique session identifier. The master session and all of its subsessions must reference the same identifier.
For example, a master session would include these input flists fields:
0 PIN_FLD_SESSION_TYPE ENUM [0] 1 0 PIN_FLD_NETWORK_SESSION_CORRELATION_ID STR [0] "MA_1"
Any subsessions that started during the same connection would include these input flist fields:
0 PIN_FLD_SESSION_TYPE ENUM [0] 2 0 PIN_FLD_NETWORK_SESSION_CORRELATION_ID STR [0] "MA_1"
By default, BRM stores information about a master session and any of its subsessions in one storable class type: /active_session/telco/*. For example, if a session includes a master session and two subsessions and the subsession mode is rate mode or deferred rate mode, BRM creates three /active_session/telco objects.
You can direct BRM to store master session data in one storable class extension and subsession data in another storable class extension through calls to the Services Framework AAA opcodes. For example, BRM could store GPRS master session data in an /active_session/telco/gprs/master object. Likewise, BRM could store GPRS subsession data in an /active_session/telco/gprs/subsession object.
To store session data in a storable class extension, configure your external network to pass the PIN_FLD_OBJ_TYPE input flist field in the call to the Services Framework AAA opcodes. Set the PIN_FLD_OBJ_TYPE input flist field to the extension that should be added after /active_session/telco. For example, to store master session data in an /active_session/telco/gprs/master object:
0 PIN_FLD_OBJ_TYPE STR [0] "gprs/master"
When the rating susbsession mode is set to deferred rate mode or aggregate mode, BRM waits until the master session and all subsessions have ended before rating the usage data. In this case, the external network must notify BRM whether the network connection is closed or still open when a subsession ends.
Your external network indicates whether a network connection has ended or is still open by passing the PIN_FLD_SESSION_STOP_INDICATOR input flist field in the call to the PCM_OP_TCF_AAA_STOP_ACCOUNTING opcode. Set the PIN_FLD_SESSION_STOP_INDICATOR field to one of the following:
0 to specify that the network session is still in progress.
1 to specify that the network session has finished.
When AAA opcodes receive the final stop accounting request, the opcodes, by default, confirm that the master session and all subsessions have ended and have been processed before closing all of the /active_session objects and creating events. This prevents revenue leakage when subsessions are processed out of order.
To disable the extra search, perform these steps:
Open the Services Framework AAA configuration file (BRM_Home/apps/tcf_aaa/pin.conf) in a text editor.
Set the wait_for_all_interim_stop_request entry to NO:
When set to YES, the PCM_OP_TCF_AAA_STOP_ACCOUNTING opcode confirms that all stop accounting requests have been processed after it receives the final stop accounting request. This ensures that all usage information is captured if subsessions are processed out of order. This is the default setting.
When set to NO, the PCM_OP_TCF_AAA_STOP_ACCOUNTING opcode does not confirm that all stop accounting requests have been processed after it receives the final stop accounting request.
- fm_tcf_aaa wait_for_all_interim_stop_request NO
Save and close the file.
Stop and restart the Services Framework AAA Manager.
You can specify how BRM processes AAA requests for services by using the Services Framework AAA Manager utilities and configuration files. For example, you can specify the following:
The default authorization and reauthorization values for services. "Specifying Default Authorization and Reauthorization Values".
How to handle session objects. See "Configuring How Services Framework AAA Manages Session Objects".
The helper opcodes to call. See "Configuring Services Framework to Call Helper Opcodes".
How to calculate the total resources reserved by an account. See "Configuring How BRM Calculates Reservation Balances".
Prepaid customers are authorized to use a service for a specified amount, duration, volume, or activity. For example, you can authorize customers to initially download 100 bytes of data or make a 30-minute telephone call.
By default, BRM authorizes customers for the volume or duration passed in the input flist to the AAA opcodes. If a value is not passed in, the opcode uses the default value specified in the service-specific /config/reserve object. For example, it uses the /config/reserve/gsm/data object for GSM data services. If there is not an object for the specified service type, the opcode uses the default configuration object (/config/reserve).
You define default values by using the "load_config_reservation_aaa_prefs" utility. This utility loads the values from one of the following reservation preferences files into a service-specific /config/reserve object in the BRM database:
pin_config_reservation_aaa_prefs
pin_config_reservation_aaa_prefs_gprs
pin_config_reservation_aaa_prefs_gsm
pin_config_reservation_aaa_prefs_gsm_data
pin_config_reservation_aaa_prefs_gsm_telephony
pin_config_reservation_prefs
The reservation preferences file specifies the default values in flist format.
Single-RUM example:
0 PIN_FLD_RESERVATION_INFO ARRAY [0] 1 PIN_FLD_QUANTITY DECIMAL [0] 100 1 PIN_FLD_MIN_QUANTITY DECIMAL [0] 0 1 PIN_FLD_INCR_QUANTITY DECIMAL [0] 100 1 PIN_FLD_RUM_NAME STR [0] "Amount" 1 PIN_FLD_IS_PRIMARY_RUM ENUM [0] 1 1 PIN_FLD_REQ_MODE ENUM [0] 1 1 PIN_FLD_UNIT ENUM [0] 0 1 PIN_FLD_RATIO INT [0] 2
Multi-RUM example:
0 PIN_FLD_RESERVATION_INFO ARRAY [0] 1 PIN_FLD_QUANTITY DECIMAL [0] 100 1 PIN_FLD_MIN_QUANTITY DECIMAL [0] 0 1 PIN_FLD_INCR_QUANTITY DECIMAL [0] 100 1 PIN_FLD_RUM_NAME STR [0] "Amount" 1 PIN_FLD_REQ_MODE ENUM [0] 1 1 PIN_FLD_UNIT ENUM [0] 0 1 PIN_FLD_IS_PRIMARY_RUM ENUM [0] 0 1 PIN_FLD_RATIO INT [0] 1 0 PIN_FLD_RESERVATION_INFO ARRAY [1] 1 PIN_FLD_QUANTITY DECIMAL [0] 50 1 PIN_FLD_MIN_QUANTITY DECIMAL [0] 0 1 PIN_FLD_INCR_QUANTITY DECIMAL [0] 50 1 PIN_FLD_REQ_MODE ENUM [0] 2 1 PIN_FLD_UNIT ENUM [0] 0 1 PIN_FLD_IS_PRIMARY_RUM ENUM [0] 1 1 PIN_FLD_RATIO INT [0] 2 0 PIN_FLD_RESERVATION_INFO ARRAY [2] 1 PIN_FLD_QUANTITY DECIMAL [0] 5 1 PIN_FLD_INCR_QUANTITY DECIMAL [0] 50 1 PIN_FLD_RUM_NAME STR [0] "Volume" 1 PIN_FLD_REQ_MODE ENUM [0] 4 1 PIN_FLD_UNIT ENUM [0] 0 1 PIN_FLD_IS_PRIMARY_RUM ENUM [0] 0 1 PIN_FLD_RATIO INT [0] 4
PIN_FLD_RESERVATION_INFO is an array that stores the default authorization and reauthorization values for one ratable usage metric (RUM). You create an array for each RUM that you support.
PIN_FLD_QUANTITY specifies the default authorization quantity.
PIN_FLD_MIN_QUANTITY specifies the minimum quantity to be rated for an AAA session. For example, you can specify a minimum of 1 minute or 1 MB is rated for an AAA session.
PIN_FLD_INCR_QUANTITY specifies the default extension quantity when reauthorizing a prepaid session. For example, you can specify to reauthorize a customer for an additional 20 minutes or 100 MB.
PIN_FLD_RUM_NAME specifies the ratable usage metric (RUM) to use when calculating the authorization and reauthorization value.
PIN_FLD_IS_PRIMARY_RUM specifies whether this RUM is a primary RUM. 0 indicates that this is not a primary RUM; 1 indicates that this is a primary RUM. This field is optional. It is ignored if present for a single-RUM request.
PIN_FLD_REQ_MODE specifies to rate the amount (1), duration (2), volume (4), duration and volume (6), or occurrence (8).
PIN_FLD_UNIT specifies the currency resource ID for amounts; for example, 840 for US dollars or 978 for Euros. This field is required only for amounts.
PIN_FLD_RATIO specifies the ratio for scaling in multi-RUM scenarios. This field is optional. It is ignored if present for a single-RUM request.
To specify default authorization and reauthorization values:
Open the reservation preferences file in a text editor. Sample files are located in the BRM_Home/sys/data/config directory.
Specify your default authorization and reauthorization values.
Save the file.
Load the file into the BRM database by using the "load_config_reservation_aaa_prefs" utility.
load_config_reservation_aaa_prefs reservation_prefs
Note:
To connect to the BRM database, this utility requires a configuration file in the directory from which you run it. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.Stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
To verify that the default authorization and reauthorization values were loaded, you can display the /config/reserve object by using the 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.
You configure how Services Framework AAA manages session objects by editing the appropriate AAA parameters XML file 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 the file into the BRM database's /config/aaa object by running the load_pin_telco_aaa_params utility.
If you enabled in-session notifications, specify the maximum scaled delay time for each supported resource in the AAA parameters XML files listed above.
When BRM processes a AAA service request for a resource from the network connectivity application, if you have not configured the maximum scaled delay time for that resource in the appropriate AAA parameters XML file, BRM does not calculate or provide the tariff change indication for that resource in its in-session notifications to the network connectivity application.
See BRM_Home/sys/data/config/config_beid.xml file for the set of configured resources.
To configure how Services Framework AAA manages session objects:
Go to the BRM_Home/sys/data/config directory and open the appropriate AAA parameters XML file in a text editor.
Specify whether BRM checks for duplicate /active_session or /event/session objects by editing the DuplicateCheckType entry:
<DuplicateCheckType>1</DuplicateCheckType>
1 specifies to check for duplicate /active_session objects.
2 specifies to check for duplicate /event/session objects.
Specify how long in seconds to store /active_session objects in memory before deleting them by editing the ExpirationInterval entry:
Note:
This entry is required for IMDB Cache. This value must match the ExpirationTimeInSeconds registry entry value. Set ExpirationInterval to 0 if the transient object pool is disabled. Se.
<ExpirationInterval>0</ExpirationInterval>
Specify how to store and rate subsessions by editing the SubsessionMode entry:
<SubsessionMode>1</SubsessionMode>
1 specifies aggregate mode. Subsessions are stored and rated in one event object.
2 specifies rate immediately. Subsessions are stored and rated individually. BRM rates each subsession as soon as it ends.
3 specifies deferred rate mode. Subsessions are stored and rated individually. BRM rates all of the subsessions at once, after the last subsession ends.
For more information, see "Specifying How to Rate Subsessions".
Specify whether to keep or delete /active_session objects and /reservation/active objects when a prepaid session ends by editing the DeletedFlag entry:
<DeletedFlag>3</DeletedFlag>
0 specifies to keep both /active_session and /reservation/active objects.
1 specifies to keep /active_session objects but delete /reservation/active objects.
2 specifies to delete /active_session objects but keep /reservation/active objects.
3 specifies to delete both /active_session and /reservation/active objects.
Specify the maximum scaled delay times for the supported resources.
If the file contains a ScaledDelayInfo entry for a resource, the current maximum scaled delay time for the resource is the MaxScaledDelayTime value specified for that ScaledDelayInfo entry. Change the entry for MaxScaledDelayTime.
If the file does not contain a maximum scaled delay time for a resource, add the ScaledDelayInfo entry for that resource and enter its MaxScaledDelayTime value. For example,
<ScaledDelayInfo ResourceId="978"> <MaxScaledDelayTime>12000</MaxScaledDelayTime> </ScaledDelayInfo>
In this example,
The resource for which the maximum scaled delay time is being added to the file is 978 (Euro).
The maximum scaled delay time for this resource is set as 12000 seconds.
Save and close the file.
Load the AAA parameters XML file into the BRM database by using the load_pin_telco_aaa_params utility:
load_pin_telco_aaa_params [-f pin_telco_aaa_params_file]
where pin_telco_aaa_params_file specifies the name and location of the file that defines how to manage session objects. By default, the utility uses the BRM_Home/sys/data/config/pin_telco_aaa_params.xml file.
For more information, see "load_pin_telco_aaa_params".
Stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
To verify that the configuration parameters were loaded, you can display the /config/aaa object by using the 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.
You configure Services Framework AAA Manager to call helper opcodes at specific processing stages by using the "load_aaa_config_opcodemap_tcf" utility. This utility loads your mappings from the pin_config_opcodemap_tcf configuration file into the /config/opcodemap/tcf object in the BRM database.
The pin_config_opcodemap_tcf file maps AAA opcodes to helper opcodes in the following format:
Framework_Opcode: Opcode_Name Processing_Stage: Stage Opcode_Map: Service_Type, Helper_Opcode
where:
Opcode_Name specifies the name of the opcode.
Stage specifies the processing stage at which to call the helper opcode. The processing stages are SEARCH_SESSION, PREP_INPUT, VALIDATE_LIFECYCLE, ACC_ON_OFF_SEARCH, TAG_SESSION, and POST_PROCESS.
Service_Type specifies the service type that triggers a call to the helper opcode.
Helper_Opcode specifies the name of the helper opcode to call. For each combination of framework opcode, processing stage, and service type, Services Framework can call only one helper opcode.
Note:
You can configure the dropped calls feature to call more than one helper opcode during the TAG_SESSION stage. See "Setting Up Your System to Identify Dropped Calls and Continuation Calls" for more information.For example, the following entry specifies that when the PCM_OP_TCF_AAA_AUTHORIZE opcode processes /service/telco/gsm/sms services and reaches the PREP_INPUT processing stage, it calls the PCM_OP_TCF_AAA_AUTHORIZE_PREP_INPUT helper opcode.
Framework_Opcode: PCM_OP_TCF_AAA_AUTHORIZE Processing_Stage: PREP_INPUT Opcode_Map:/service/telco/gsm/sms, PCM_OP_TCF_AAA_AUTHORIZE_PREP_INPUT
To configure opcodes to call helper opcodes:
Open the BRM_Home/sys/data/config/pin_config_opcodemap_tcf file in a text editor.
Edit the file.
Save and close the file.
Load the file into the BRM database by using the load_aaa_config_opcodemap_tcf utility.
Note:
To replace the entire contents of the /config/opcodemap/tcf object, use the -f parameter. To append data to the object, use the -i option.load_aaa_config_opcodemap_tcf -i|-f pin_config_opcodemap_tcf
For more information, see "load_aaa_config_opcodemap_tcf".
Stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
To verify that your opcode mappings were loaded, you can display the /config/opcodemap/tcf object by using the 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.
BRM tracks the total resources reserved by a balance group in two objects:
/reservation_list: This object tracks the total resources a balance group has reserved in /reservation/active objects. This object is required for IMDB Cache-enabled prepaid systems.
For policy-driven charging sessions, this object also holds the consumed reservation amount for those resources.
/balance_group: This object's RESERVED_AMOUNT field tracks the total resources a balance group has reserved in /reservation objects.
For policy-driven charging sessions, this object also holds the consumed reservation amount for those resources.
You specify how BRM calculates a customer's reservation balance by setting the balance_coordinator entry in the CM's pin.conf file.
When the entry is set to 0, BRM retrieves reservation balances from both types of objects. Use this setting for systems that have the CM connected to IMDB Cache DM.
When the entry is set to 1, BRM retrieves reservation balances from /balance_group objects only. Use this setting for systems that have the CM connected to Oracle DM. This is the default setting.
For IMDB Cache-enabled prepaid systems, you must configure BRM to calculate reservation balances by adding the balances from the /balance_group and /reservation_list objects:
Open the Connection Manager (CM) configuration file (BRM_Home/sys/cm/pin.conf) in a text editor.
Set the balance_coordinator entry to 0:
- fm_bal balance_coordinator 0
Save and close the file.
You do not need to restart the CM to enable this entry.
For prepaid systems that do not use IMDB Cache, you must configure BRM to calculate reservation balances by retrieving the RESERVED_AMOUNT field in the /balance_group object:
Open the Connection Manager (CM) configuration file (BRM_Home/sys/cm/pin.conf) in a text editor.
Set the balance_coordinator entry to 1.
- fm_bal balance_coordinator 1
Save and close the file.
Make sure you pass the PIN_FLD_RESERVATION_OBJ input flist field for the following opcodes:
PCM_OP_TCF_AAA_AUTHORIZE
PCM_OP_TCF_AAA_REAUTHORIZE
PCM_OP_TCF_AAA_UPDATE_AND_REAUTHORIZE
Note:
The PIN_FLD_RESERVATION_OBJ field is marked as optional in the opcode input flist. However, this field is mandatory for prepaid systems that do not use IMDB Cache for AAA.By default, BRM locates a customer's service object by using the customer's login name and then, if the login name is not found, by using the customer's alias name. That is, BRM searches through /service objects by first using the object's PIN_FLD_LOGIN field and then using the object's PIN_FLD_ALIAS_LIST array.
However, prepaid service types use alias names rather than login names to identify customers. This increases the amount of time required to find these /service objects.
You can improve search performance for prepaid service types by configuring BRM to search alias names first and login names second for specified service types. To do this, add the list of service types that identify users through alias names to the pin_excluded_logins.xml file and then load it into the BRM database's /config/login_exclusion object.
To improve search performance for services, perform the following tasks:
Open the BRM_Home/sys/data/config/pin_excluded_logins.xml file in a text editor.
Add an entry for each service type that identifies users through alias names rather than login names.
Note:
The default XML file contains the following entries, but you can add custom services to the file.
<LoginExclusionManagementComponent>
<ServiceList>
<Service>/service/telco/gsm</Service>
<Service>/service/telco/gsm/telephony</Service>
<Service>/service/telco/gsm/fax</Service>
<Service>/service/telco/gsm/data</Service>
<Service>/service/telco/gsm/sms</Service>
</ServiceList>
</LoginExclusionManagementComponent>
Save and close the file.
Load the XML file into the BRM database by using the load_pin_excluded_logins utility.
Note:
This utility requires a configuration file in the directory from which it is run.cd BRM_Home/sys/data/config load_pin_excluded_logins pin_excluded_logins.xml
For more information, see load_pin_excluded_logins in BRM Developer's Guide.
Stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
To verify that the pin_excluded_logins.xml file loaded properly, display the /config/login_exclusion object by using the Object Browser or by using the robj command with the testnap utility. For information, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.
By default, Services Framework AAA Manager supports the following RUM types: duration, volume, amount, and occurrence. To enable Services Framework AAA Manager to perform AAA by using a custom RUM, you must configure it to do so.
To perform AAA for a custom RUM, see "Supporting Custom RUMs during the AAA Process".
To perform AAA for a custom RUM in a multiple RUM scenario, see "Supporting Custom RUMs in a Multiple RUM Scenario".
To configure Services Framework AAA Manager to rate events by using custom RUMs:
Define your custom RUMs in the BRM_Home/sys/data/pricing/example/pin_rum file and then use the load_pin_rum utility to load it into the database's /config/rum object. See "Setting Up Ratable Usage Metrics (RUMs)" and load_pin_rum in BRM Setting Up Pricing and Rating.
Specify the default authorization and reauthorization values for the custom RUM in the reservation preferences file and then use the load_config_reservation_aaa_prefs utility to load it into the database's /config/reserve object. See "Specifying Default Authorization and Reauthorization Values".
Note:
Make sure you map the new PIN_FLD_REQ_MODE field for the custom RUM.Configure your external network to collect the request mode and pass it in the PIN_FLD_REQ_MODE input flist of the appropriate Services Framework AAA opcode. If a mode is not passed in the input flist, Services Framework uses the mode specified in the default /config/reserve object.
For authorization requests, configure your external network to collect the initial authorization quantity and pass it in the PIN_FLD_QUANTITY input flist of the PCM_OP_TCF_AAA_AUTHORIZE opcode. If a quantity is not specified in the input flist, the opcode uses the quantity specified in the default /config/reserve object.
For reauthorization requests as well as update and reauthorization requests:
Configure your external network to collect the request mode, extension quantity, and original authorization quantity and pass it in the input flist of the PCM_OP_TCF_AAA_REAUTHORIZE opcode and the PCM_OP_TCF_AAA_UPDATE_AND_REAUTHORIZE opcode.
Customize the PCM_OP_TCF_AAA_REAUTHORIZE_PREP_INPUT helper opcode to aggregate the custom RUM fields. See "Preparing Service-Specific Flists for Reauthorization".
Services Framework AAA Manager can perform AAA for GSM and custom service types by using multiple RUMs that consist of the following RUM types only: amount, duration, volume, and occurrence. To perform AAA for GSM or custom service types by using multiple RUMs that include a custom RUM type, you must perform one of the following:
Customize the service-specific POST_PROCESS helper opcode to handle the logic for the custom RUM. For example, for GSM services, you would modify the PCM_OP_GSM_AAA_POL_POST_PROCESS helper opcode to aggregate GSM data according to the custom RUM type and the value passed in the PIN_FLD_AGGREGATE_MODE flist field. See "Aggregating Return GSM Data".
Configure Services Framework AAA Manager to skip all service-specific aggregation during the post-processing stage when processing reauthorization requests for any services that use a custom RUM in a multiple RUM scenario.
To configure Services Framework AAA Manager to skip all service-specific aggregation during the post processing stage when processing reauthorization requests:
Open the BRM_Home/sys/data/config/pin_config_opcodemap_tcf file in a text editor.
At the POST_PROCESS stage of the PCM_OP_TCF_AAA_REAUTHORIZE and PCM_OP_TCF_AAA_UPDATE_AND_REAUTHORIZE opcodes, remove all lines that map a service type that uses your custom RUM to a service-specific helper opcode.
For example, if your GSM services support a custom RUM in a multiple RUM scenario, you would comment out or delete the entries shown in bold below:
#Framework_Opcode: PCM_OP_TCF_AAA_REAUTHORIZE #Processing_Stage: POST_PROCESS #Opcode_Map:/service/telco/gsm/telephony, PCM_OP_GSM_AAA_POL_POST_PROCESS #Opcode_Map:/service/telco/gsm/sms, PCM_OP_GSM_AAA_POL_POST_PROCESS #Opcode_Map:/service/telco/gsm/data, PCM_OP_GSM_AAA_POL_POST_PROCESS #Opcode_Map:/service/telco/gsm/fax, PCM_OP_GSM_AAA_POL_POST_PROCESS #Framework_Opcode: PCM_OP_TCF_AAA_UPDATE_AND_REAUTHORIZE #Processing_Stage: POST_PROCESS #Opcode_Map:/service/telco/gsm/telephony, PCM_OP_GSM_AAA_POL_POST_PROCESS #Opcode_Map:/service/telco/gsm/sms, PCM_OP_GSM_AAA_POL_POST_PROCESS #Opcode_Map:/service/telco/gsm/data, PCM_OP_GSM_AAA_POL_POST_PROCESS #Opcode_Map:/service/telco/gsm/fax, PCM_OP_GSM_AAA_POL_POST_PROCESS
Save and close the file.
Load the file into the BRM database by using the load_aaa_config_opcodemap_tcf utility.
Note:
To replace the entire contents of the /config/opcodemap/tcf object, use the -f parameter. To append data to the object, use the -i option.load_aaa_config_opcodemap_tcf -i|-f pin_config_opcodemap_tcf
For more information, see "load_aaa_config_opcodemap_tcf".
Stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.
To set up your system to perform prepaid AAA for custom service types, perform the following tasks:
Set up your external network to collect the information needed and pass the information to the Services Framework AAA standard opcodes. See "Sending AAA Requests to the Services Framework AAA Opcodes".
Add a library file for your custom service manager to the BRM_Home/lib directory and add a pointer to the library file in the CM pin.conf file. See "Syntax for Facilities Module (FM) Entries" in BRM System Administrator's Guide.
Create custom helper opcodes to aggregate service-specific data. You can use the Services Framework AAA helper opcodes as a starting place. See "Preparing Service-Specific Data by Using Helper Opcodes".
Configure the Services Framework AAA standard opcodes to call your custom helper opcodes. See "Configuring Services Framework to Call Helper Opcodes".
To perform AAA for custom services, your system must be designed to collect the information needed from the customer and pass the appropriate fields in the input flist to the Services Framework AAA opcodes.
Your external network can pass information to the opcodes through the following:
Oracle Communications Service Broker (OCSB).
A service manager, such as GSM AAA Manager, GPRS Manager, or a custom service manager. See "About Performing AAA for Prepaid GSM Services".
You can use the Services Framework AAA API to perform the following actions:
Authenticate customers. See "Authenticating Users for Custom Services".
Authorize customers to use services. See "Authorizing Prepaid Services".
Reauthorize customers to continue using a service. See "Reauthorizing Prepaid Sessions".
Update and reauthorize prepaid sessions. See "Updating and Reauthorizing Prepaid Sessions".
Cancel authorization. See "Canceling Authorization for Prepaid Services".
Rate and record activity events. See "Rating and Recording Activity Events".
Manage prepaid sessions. See "Managing Prepaid Sessions".
If you have enabled in-session notifications, add custom details to the response sent to the network connectivity application. See ""Customizing AAA Processes by Extending Policies".
To authenticate users for custom services, call the PCM_OP_TCF_AAA_AUTHENTICATE opcode with the following information in the input flist:
Service type
Device ID
Action
(Optional) Password. If a password is passed in, BRM authenticates in PAP mode. If one is not passed in, BRM authenticates in CHAP mode.
This opcode calls the helper opcodes specified in the /config/opcodemap/tcf object. For detailed information about the authentication process, see "How BRM Authenticates Prepaid Customers".
The authorization process determines whether a customer is allowed to access a specific service. This includes determining whether the customer has a subscription for the specified service and sufficient resources for the requested service.
Customers that are approved to access a service are authorized for a specified volume or duration and, optionally, a validity period.
For more information, see "About Authorizing Prepaid Usage".
To authorize prepaid customers to use a service, call the PCM_OP_TCF_AAA_AUTHORIZE opcode with the following information in the input flist:
Service type
Device ID
Direction of the call
Name of the calling application
Details about the event, such as the IMEI value, the dialed number, and the quality of service (QoS)
(Optional) The authorization request mode: volume, duration, or amount
(Optional) The authorization request's volume or duration
Note:
If you are not using IMDB Cache for AAA, you must also pass the PIN_FLD_RESERVATION_OBJ field in the opcode's input flist. For more information, see "Calculating Reservation Balances for Non-IMDB Cache Systems".The opcode determines whether the customer has sufficient resources to use the service for the volume or duration passed in the input flist. If a volume or duration is not passed in, the opcode uses the default authorization value specified in the /config/reserve object. (See "Specifying Default Authorization and Reauthorization Values".)
The opcode returns the following to the calling application:
The result of the authorization (pass or fail), which is returned in the PIN_FLD_RESULT output flist field.
The authorized volume or duration, which is returned in the PIN_FLD_QUANTITY output flist field.
(Volume-based authorizations only) The authorization validity period, which is returned in the PIN_FLD_VALID_TO output flist field.
Note:
This opcode calls the helper opcodes specified in the /config/opcodemap/tcf object. For detailed information about the authorization process, see "How BRM Authorizes Users to Access Prepaid Services".If you have enabled in-session notifications and the call request is not denied, the opcode returns additional in-session notifications for credit threshold breaches, service expirations, streaming usage threshold summaries, tariff change indications and subscriber preferences for such notifications.
If you are rating with real-time non-duration RUMs, you can use the optional PIN_FLD_VALID_TO output flist field to limit product authorizations to a specific time period (in conjunction with PIN_FLD_RATED_TIMEZONE). This allows you to limit authorizations to the rate tier they are appropriate for, and force a reauthorization of the event when usage crosses into a different rate tier.
By default, if an event is rated with two different products or rate tiers that have two different time limits, the shortest time limit is added to PIN_FLD_VALID_TO. There is an exception if the event spans two time periods (for example, starts in off-peak hours and ends in peak hours), and is rated by the event end time. In that case, PIN_FLD_VALID_TO is populated with the end time of the second period.
To reauthorize customers to continue their prepaid session, call the PCM_OP_TCF_AAA_REAUTHORIZE opcode with the following information in the input flist:
Service type
Device ID
Direction of the call
Name of the calling application
Requested reauthorization amount or quantity
Details about the call, such as the IMEI value, the dialed number, and the QoS
Note:
If you are not using IMDB Cache for AAA, you must also pass the PIN_FLD_RESERVATION_OBJ field in the opcode's input flist. For more information, see "Calculating Reservation Balances for Non-IMDB Cache Systems".You can specify whether the reauthorization amount or quantity is cumulative or incremental by passing the optional PIN_FLD_AGGREGATE_MODE input flist field:
4 specifies that the reauthorization amount or quantity passed in the input flist is cumulative (that is, it represents the original authorization amount plus a requested extension amount). BRM reauthorizes by using the amount or quantity passed in the input flist.
8 specifies that the amount or quantity passed in the input flist is incremental (that is, it represents the requested extension amount or quantity only).
Note:
If you specify incremental mode (8), you can also specify whether to adjust the quantity by setting the PIN_FLD_RATING_MODE input flist field to the following:0: Calculates the reauthorization amount by adding the customer's previous reservation balance and the value passed in the input flist. This is the default.
1: Calculates the reauthorization amount by adding the amount in the /active_session object and the value passed in the input flist.
If you have enabled in-session notifications and the call request is not denied, the opcode returns additional in-session notifications for credit threshold breaches, service expirations, streaming usage threshold summaries, tariff change indications and subscriber preferences for such notifications.
This opcode calls the helper opcodes specified in the /config/opcodemap/tcf object. For detailed information about the reauthorization process, see "How BRM Reauthorizes Prepaid Services".
To update customer usage data and reauthorize a prepaid session in one transaction, call the PCM_OP_TCF_AAA_UPDATE_AND_REAUTHORIZE opcode with the following information in the input flist:
Service type
Device ID
Direction of the call
Name of the calling application
Requested reauthorization amount or quantity
Details about the call, such as the IMEI value, the dialed number, and the QoS
Note:
If you are not using IMDB Cache for AAA, you must also pass the PIN_FLD_RESERVATION_OBJ field in the opcode's input flist. For more information, see "Calculating Reservation Balances for Non-IMDB Cache Systems".You can specify whether the reauthorization amount or quantity is cumulative or incremental by passing the optional PIN_FLD_AGGREGATE_MODE input flist field:
1 specifies that the update amount or quantity passed in the input flist is aggregated (that is, it represents the total amount or quantity used during the session).
2 specifies that the update amount or quantity passed in the input flist is incremental (that is, it represents the amount or quantity used since BRM last updated the /active_session object). BRM calculates the total usage amount or quantity by adding the value passed in the input flist to the value in the /active_session object. This is the default update mode.
4 specifies that the reauthorization amount or quantity passed in the input flist is cumulative (that is, it represents the original authorization amount plus a requested extension amount). BRM reauthorizes by using the amount or quantity passed in the input flist.
8 specifies that the reauthorization amount or quantity passed in the input flist is incremental (that is, it represents the requested extension amount or quantity only). This is the default reauthorization mode.
Note:
If you specify incremental mode (8), you can also specify whether to adjust the quantity by setting the PIN_FLD_RATING_MODE input flist field to the following:0: Calculates the reauthorization amount by adding the customer's previous reservation balance and the value passed in the input flist. This is the default.
1: Calculates the reauthorization amount by adding the amount in the /active_session object and the value passed in the input flist.
If you have enabled in-session notifications and the call request is not denied, the opcode returns additional in-session notifications for credit threshold breaches, service expirations, streaming usage threshold summaries, tariff change indications and subscriber preferences for such notifications.
This opcode calls the helper opcodes specified in the /config/opcodemap/tcf object. For detailed information about the updating and reauthorization process, see "How BRM Updates and Reauthorizes Prepaid Sessions".
To cancel an existing authorization and return reserved resources back to the customer's account balance, call the PCM_OP_TCF_AAA_CANCEL_AUTHORIZATION opcode with the following information in the input flist:
Service type
Device ID
Authorization ID
This opcode calls the helper opcodes specified in the /config/opcodemap/tcf object. For detailed information about the cancellation process, see "How BRM Cancels Prepaid Service Authorizations".
To rate and record activity events, such as purchasing a product or changing a password, call the PCM_OP_TCF_AAA_ACCOUNTING opcode with the following information in the input flist:
Service type
MSID
Name of the calling program
Authorization ID
This opcode calls the helper opcodes specified in the /config/opcodemap/tcf object. For detailed information about rating activity events, see "How BRM Rates and Records Prepaid Activity Events".
After a customer is authorized to use a service, the external network connects the call and begins collecting information about the customer's usage, such as the starting time, the dialed number, and the direction of the call. The network sends this information to BRM, which records the information in /active_session objects.
When the session ends, BRM rates any usage, closes or deletes the associated /active_session and /reservation/active objects, and records the data in /event/session objects in the BRM database.
You use the Services Framework AAA ACCOUNTING standard opcode to perform the following tasks:
Start prepaid sessions.
Update information about an existing prepaid session.
End prepaid sessions.
Close any open sessions when the external network shuts down abnormally or restarts.
To start a prepaid session, call the PCM_OP_TCF_AAA_START_ACCOUNTING opcode with the following information in the input flist:
Service type
Device ID
Authorization ID
Direction of the call
Information about the call, such as the IMEI value, dialed number, and QoS
This opcode calls the helper opcodes specified in the /config/opcodemap/tcf object. For detailed information about starting sessions, see "How BRM Starts Prepaid Sessions".
To update information about an existing prepaid session, call the PCM_OP_TCF_AAA_UPDATE_ACCOUNTING opcode with the following information in the input flist:
Service type
Device ID
Authorization ID
Direction of the call
Details that changed, such as the quantity or amount used during the session
This opcode can also be called at any time during a session to update any inherited data (PIN_FLD_INHERITED_INFO) fields in an active session object. Only the fields specified in the opcode's input flist are updated; all other fields in the session objects are left unchanged.
You can specify whether the usage amount or quantity is cumulative or incremental by passing the optional PIN_FLD_AGGREGATE_MODE input flist field:
1 specifies that the update amount or quantity passed in the input flist is aggregated (that is, it represents the total amount or quantity used during the session). BRM applies the usage amount or quantity from the input flist.
2 specifies that the update amount or quantity passed in the input flist is incremental (that is, it represents the amount or quantity used since BRM last updated the /active_session object). BRM calculates the total usage amount or quantity by adding the value passed in the input flist to the value in the /active_session object.
This opcode calls the helper opcodes specified in the /config/opcodemap/tcf object. For detailed information about updating sessions, see "How BRM Updates Prepaid Sessions".
To end a prepaid session when a call ends successfully, call the PCM_OP_TCF_AAA_STOP_ACCOUNTING opcode with the following information in the input flist:
Service type
Device ID
Direction of the call
Details about the call, such as the IMEI value, dialed number, and QoS
You use this opcode to perform the following actions:
Close, cancel, or delete the active session object.
Release or delete any associated reservation objects.
Rate any usage.
Record information about the session into an /event/session object in the BRM database.
You can specify whether the usage amount or quantity is cumulative or incremental by passing the optional PIN_FLD_AGGREGATE_MODE input flist field:
1 specifies that the update amount or quantity passed in the input flist is aggregated (that is, it represents the total amount or quantity used during the session). BRM applies the usage amount or quantity from the input flist.
2 specifies that the update amount or quantity passed in the input flist is incremental (that is, it represents the amount or quantity used since BRM last updated the /active_session object). BRM calculates the total usage amount or quantity by adding the value passed in the input flist to the value in the /active_session object.
PCM_OP_TCF_AAA_STOP_ACCOUNTING calls the helper opcodes specified in the /config/opcodemap/tcf object. For detailed information about ending sessions, see "How BRM Ends Prepaid Sessions".
To close all open sessions when the external network is being shut down or encounters problems, call the PCM_OP_TCF_AAA_ACCOUNTING_OFF opcode with the following information in the input flist:
Service type
Originating network ID (SCP name)
(Optional) Start or end time
(Optional) Status
(Optional) Termination cause
Sessions with a status of STARTED or UPDATED are automatically rated before they are closed. You specify how BRM handles sessions with a CREATED status by passing the optional PIN_FLD_ACC_FLAG input flist field:
When this flag is passed, CREATED sessions are rated before they are closed.
When the flag is not passed, CREATED sessions are cancelled.
This opcode calls the helper opcodes specified in the /config/opcodemap/tcf object. For detailed information about closing sessions, see "How BRM Closes Prepaid Sessions When the External Network Shuts Down".
To close all open prepaid sessions when the external network restarts, call the PCM_OP_TCF_AAA_ACCOUNTING_ON opcode with the following information in the input flist:
Service type
Originating network ID (SCP name)
(Optional) Start time
(Optional) Status
Sessions with a status of STARTED or UPDATED are automatically rated before they are closed. You specify how BRM handles sessions with a CREATED status by passing the optional PIN_FLD_ACC_FLAG input flist field:
When this flag is passed, CREATED sessions are rated before they are closed.
When the flag is not passed, CREATED sessions are cancelled.
This opcode calls the helper opcodes specified in the /config/opcodemap/tcf object. For detailed information about closing sessions, see "How BRM Closes Prepaid Sessions When the External Network Restarts".
Note:
PCM_OP_TCF_AAA_ACCOUNTING_ON and PCM_OP_TCF_AAA_ACCOUNTING_OFF opcodes use the default search criteria to search the active sessions. The default search criteria is based on the PIN_FLD_TELCO_INFO.PIN_FLD_ORIGIN_NETWORK field that is supported only for the /active_session/telco objects. For the non-telco service types, you must add a custom helper opcode for the ACC_ON_OFF_SEARCH processing stage to define the search criteria for the non-telco active session type.
For example, you can add a custom helper opcode for ACC_ON_OFF_SEARCH processing stage for a non-telco service type, say /active_session/ip object. This opcode defines the search criteria to find the list of active sessions from the same NAS. In the custom opcode, you can add name of the NAS as one of the search criteria.
To request an account's balance information, call the PCM_OP_TCF_AAA_QUERY_BALANCE opcode.
This opcode:
Calls the PCM_OP_ACT_FIND opcode to get the user's /account and /service object POIDs.
Calls the PCM_OP_BAL_GET_BALANCES opcode to get the user's account balance information.
To request the cost of a specific service, call the PCM_OP_TCF_AAA_SERVICE_PRICE_ENQUIRY opcode.
This opcode:
Calls the PCM_OP_ACT_FIND opcode to get the user's /service and /account object POIDs.
Calls the PCM_OP_ACT_USAGE opcode to get cost of the service.
By default, Services Framework AAA Manager uses these helper opcodes to prepare service-specific data.
Important:
Do not call these opcodes directly. You configure opcodes to call helper opcodes by using the "load_aaa_config_opcodemap_tcf". See "Configuring Services Framework to Call Helper Opcodes".To prepare input flists for authorization, use PCM_OP_TCF_AAA_AUTHORIZE_PREP_INPUT. See "Preparing Service-Specific Flists for Authorization".
To build service-specific search templates, use PCM_OP_TCF_AAA_ACCOUNTING_PREP_INPUT. See "Building Service-Specific Search Templates".
To generate service-specific flists for reauthorization, use PCM_OP_TCF_AAA_REAUTHORIZE_PREP_INPUT. See "Preparing Service-Specific Flists for Reauthorization".
To generate service-specific flists for ending sessions, use PCM_OP_TCF_AAA_STOP_ACCOUNTING_PREP_INPUT. See "Preparing Service-Specific Flists for Ending Accounting Sessions".
To generate service-specific flists for updating sessions, use PCM_OP_TCF_AAA_UPDATE_ACCOUNTING_PREP_INPUT. See "Preparing Service-Specific Flists for Updating Accounting Sessions".
To generate service-specific flists for activity events, use PCM_OP_TCF_AAA_ACCOUNTING_PREP_INPUT. See "Preparing Service-Specific Flists for Activity Events".
Use the PCM_OP_TCF_AAA_AUTHORIZE_PREP_INPUT helper opcode to aggregate service-specific data and then prepare an flist for authorizing a prepaid accounting session.
This opcode aggregates data by amount, duration, volume, or activity, depending on the value passed in the PIN_FLD_REQ_MODE flist field:
1 specifies to rate the amount.
2 specifies to rate the duration. This is the default.
4 specifies to rate the volume.
6 specifies to rate the duration and volume.
8 specifies to rate the occurrence. This applies to activity events only.
For Amount-Based Aggregation:
When aggregating the amount, the helper opcode prepares the PIN_FLD_BALANCES array in the PIN_FLD_RATING_INFO substruct, indexed by the currency type.
For Duration-Based Aggregation:
When aggregating the duration, the helper opcode performs the following:
Assigns a starting timestamp to the PIN_FLD_START_T field in the PIN_FLD_RATING_INFO.PIN_FLD_EVENT substruct. The opcode uses the starting timestamp from the input flist or, if one is not passed in, from "pin_virtual_time" (see BRM Developer's Guide).
Note:
This is a temporary starting timestamp only and is later replaced with the actual starting timestamp by the reauthorization or stop accounting opcodes.Assigns an ending timestamp to the PIN_FLD_END_T field in the PIN_FLD_RATING_INFO.PIN_FLD_EVENT substruct:
If PIN_FLD_END_T is supplied in the input flist, the opcode assigns the ending timestamp directly to the PIN_FLD_END_T field.
If PIN_FLD_QUANTITY is supplied in the input flist, the opcode calculates the ending timestamp by adding the quantity passed in the input flist to the starting timestamp.
If an ending timestamp or quantity is not passed in, the opcode retrieves the default authorization quantity from the /config/reserve object. The opcode calculates the ending timestamp by adding the default authorization quantity to the starting timestamp.
For Volume-Based Aggregation:
When aggregating the volume, the helper opcode adds the bytes uploaded and the bytes downloaded and assigns the value to the PIN_FLD_BYTES_UPLINK and PIN_FLD_BYTES_DOWNLINK fields in the PIN_FLD_RATING_INFO.PIN_FLD_EVENT.PIN_FLD_TELCO_INFO substruct.
Use the PCM_OP_TCF_AAA_SEARCH_SESSION helper opcode to build a search template for finding /active_session/telco objects or /event/session/telco objects. These search templates are used by the Services Framework AAA opcodes to look for duplicate session objects.
By default, this helper opcode sets the search criteria to the following, but you can customize it to use other criteria:
Authorization ID
APN name
GGSN address
SGSN address
Starting timestamp
For /active_session/telco objects, the authorization ID.
For /event/session/telco objects, the network session ID, MSISDN, and start time.
Use the PCM_OP_TCF_AAA_REAUTHORIZE_PREP_INPUT helper opcode to aggregate service-specific data and then prepare an flist for reauthorizing a prepaid accounting session.
This opcode aggregates data by amount, duration, volume, or activity, depending on the value passed in the PIN_FLD_REQ_MODE flist field:
1 specifies to rate the amount.
2 specifies to rate the duration. This is the default.
4 specifies to rate the volume.
6 specifies to rate the duration and volume.
8 specifies to rate the occurrence. This applies to activity events only.
For Amount-Based Aggregation:
When aggregating the amount, the helper opcode assigns a reauthorization amount to the PIN_FLD_AMOUNT field in the PIN_FLD_RATING_INFO substruct. The method the opcode uses to calculate the reauthorization amount depends on the value passed in the PIN_FLD_AGGREGATE_MODE field:
When PIN_FLD_AGGREGATE_MODE is set to 4, the opcode uses the amount passed in the input flist.
When PIN_FLD_AGGREGATE_MODE is set to 8, the opcode calculates the reauthorization amount based on the PIN_FLD_RATING_MODE field:
When PIN_FLD_RATING_MODE is 0, the opcode adds the amount passed in the input flist to the amount in the /active_session object.
When PIN_FLD_RATING_MODE is 1, the opcode adds the amount passed in the input flist to the amount in the /reservation/active object.
For Duration-Based Requests:
When aggregating the duration, the helper opcode assigns a starting timestamp and ending timestamp to the PIN_FLD_START_T and PIN_FLD_END_T fields in the PIN_FLD_RATING_INFO.PIN_FLD_EVENT substruct.
The opcode assigns a starting timestamp based on the following:
If PIN_FLD_START_T is passed in the input flist and the timestamp is earlier than the timestamp in the /active_session object, the opcode assigns the starting timestamp from the input flist.
If PIN_FLD_START_T is passed in the input flist and the /active_session object does not already exist, the opcode assigns the starting timestamp from the input flist.
If PIN_FLD_START_T is not passed in and the /active_session object does not already exist, the opcode assigns the starting timestamp from "pin_virtual_time" (see BRM Developer's Guide).
The opcode assigns an ending timestamp based on the following:
If PIN_FLD_END_T is passed in the input flist, the opcode assigns the ending timestamp from the input flist.
If PIN_FLD_QUANTITY is passed in the input flist, the opcode calculates the ending timestamp based on the values passed in the PIN_FLD_AGGREGATE_MODE field:
When PIN_FLD_AGGREGATE_MODE is 4, the opcode calculates the ending timestamp by adding the starting timestamp and the quantity.
When PIN_FLD_AGGREGATE_MODE is 8, the opcode populates the value based on the PIN_FLD_RATING_MODE field:
When PIN_FLD_RATING_MODE is 0, the opcode calculates the ending timestamp by adding together the ending timestamp from the /active_session object and the quantity from the input flist.
When PIN_FLD_RATING_MODE is 1, the opcode calculates the ending timestamp by adding together the starting timestamp, the reserved quantity from /reservation/active, and the quantity from the input flist.
If an ending timestamp or quantity is not passed in, the opcode retrieves the default reauthorization quantity from the /config/reserve/gprs object. The opcode calculates the ending timestamp by adding together the default reauthorization quantity and the starting timestamp.
For Volume-Based Requests:
When aggregating the volume, the helper opcode assigns the reauthorization volume to the PIN_FLD_BYTES_UPLINK and PIN_FLD_BYTES_DOWNLINK fields in the PIN_FLD_RATING_INFO substruct. The method the opcode uses to calculate the reauthorization volume depends on the value passed in the PIN_FLD_AGGREGATE_MODE field:
When PIN_FLD_AGGREGATE_MODE is set to 4, the opcode assigns the volume passed in the input flist.
When PIN_FLD_AGGREGATE_MODE is set to 8, the opcode calculates the reauthorization volume based on the PIN_FLD_RATING_MODE field:
When PIN_FLD_RATING_MODE is set to 0, the opcode adds the bytes uploaded or downloaded from the input flist to the value in the /active_session object.
When PIN_FLD_RATING_MODE is set to 1, the opcode adds the bytes uploaded or downloaded from the input flist to the value in the /reservation/active object.
Use the PCM_OP_TCF_AAA_STOP_ACCOUNTING_PREP_INPUT helper opcode to aggregate service-specific data and then prepare an input flist for ending a prepaid accounting session.
This opcode aggregates service-specific data based on the value passed in the PIN_FLD_SUBSESSION_MODE flist field:
1 specifies aggregate mode.
2 specifies rate immediately.
3 specifies deferred rate mode.
For more information about the rating modes, see "Specifying How to Rate Subsessions".
For aggregate mode:
When set to aggregate mode, the helper opcode reads the PIN_FLD_STOP_INDICATOR field to determine whether the session is still in progress (0) or has ended (1). When the field is set to 0, the helper opcode does nothing. When the field is set to 1, the helper opcode performs the following:
Aggregates the amount or quantity passed in the input flist with the amount or quantity in the /active_session object.
Aggregates the volume information from all of the subsession objects and records it in the master session object.
Determines the session's starting timestamp and ending timestamp by choosing the earliest and latest timestamps from all of the subsession objects and then records them in the master session object.
Sets the status of all subsession objects to Closed And Unrated, which indicates that the objects should be closed and the event should not be recorded.
If it is a master session object, the information is passed in the top level of the flist; if it is a subsession object, the information is passed in the PIN_FLD_SESSION_INFO array.
For Rate Immediately:
When set to rate immediately, the helper opcode reads the PIN_FLD_STOP_INDICATOR field to determine whether the session is still in progress (0) or has ended (1). When the field is set to 0, the helper opcode does nothing. When the field is set to 1, the helper opcode aggregates the amount or quantity passed in the input flist with the amount or quantity in the /active_session object and then passes the /active_session object with the status set to Closed. If it is a master session object, the information is passed in the top level of the flist; if it is a subsession object, the information is passed in the PIN_FLD_SESSION_INFO array.
For Deferred Rate Mode:
When set to deferred rate mode, the helper opcode reads the PIN_FLD_STOP_INDICATOR field to determine whether the session is still in progress (0) or has ended (1). When the field is set to 0, the helper opcode does nothing. When the field is set to 1, the helper opcode aggregates the amount or quantity passed in the input flist with the amount or quantity in the /active_session object and then passes all of the master and subsession objects with the status set to Closed, which indicates that all of the objects should be rated and recorded as events. If it is a master session object, the information is passed in the top level of the flist; if it is a subsession object, the information is passed in the PIN_FLD_SESSION_INFO array.
Use the PCM_OP_TCF_AAA_UPDATE_ACCOUNTING_PREP_INPUT helper opcode to aggregate data and then prepare an flist for updating an existing prepaid accounting session.
This opcode aggregates service-specific data by amount, duration, volume, or activity, depending on the value passed in the PIN_FLD_REQ_MODE flist field:
1 specifies to rate the amount.
2 specifies to rate the duration. This is the default.
4 specifies to rate the volume.
6 specifies to rate the duration and volume.
8 specifies to rate the occurrence. This applies to activity events only.
For Amount-Based Aggregation:
When aggregating the amount, the helper opcode prepares the PIN_FLD_BALANCES array in the PIN_FLD_RATING_INFO substruct, indexed by the currency type.
If PIN_FLD_AGGREGATE_MODE is 4, the opcode assigns the amount from the input flist.
If PIN_FLD_AGGREGATE_MODE is 8, the opcode calculates the amount by adding together the amount passed in the input flist and the amount from the /active_session object.
For Duration-Based Requests:
When aggregating the duration, the helper opcode assigns a starting timestamp and an ending timestamp to the PIN_FLD_START_T and PIN_FLD_END_T fields in the PIN_FLD_RATING_INFO.PIN_FLD_EVENT substruct.
For the starting timestamp, the helper opcode assigns the timestamp from either the /active_session object or the input flist, depending on which one has the earliest start time. If a starting timestamp is not present in the input flist or the /active_session object, the helper opcode does not modify the existing starting timestamp.
For the ending timestamp, the helper opcode assigns the timestamp from either the /active_session object or the input flist, depending on which one has the latest end time. If an ending timestamp is not present in the input flist or the /active_session object, the helper opcode does not modify the existing ending timestamp.
For Volume-Based Requests:
When aggregating the volume, the helper opcode assigns the volume uploaded or downloaded by the customer to the PIN_FLD_BYTES_UPLINK or PIN_FLD_BYTES_DOWNLINK field in the PIN_FLD_RATING_INFO.PIN_FLD_EVENT.PIN_FLD_TELCO_INFO substruct. The method the helper opcode uses to calculate the volume depends on the value passed in the PIN_FLD_AGGREGATE_MODE flist field:
When PIN_FLD_AGGREGATE_MODE is 4, the opcode uses the bytes passed in the input flist.
When PIN_FLD_AGGREGATE_MODE is 8, the opcode calculates the volume by adding together the bytes passed in the input flist and the bytes in the /active_session object.
Use the PCM_OP_TCF_AAA_ACCOUNTING_PREP_INPUT helper opcode to aggregate service-specific data and then prepare an flist for rating activity events.
The data returned by the helper depends on the information passed in the input flist:
When /active_session object details are passed in the input flist, the helper opcode merges the session information from the input flist and the /active_session object.
When neither PIN_FLD_START_T or PIN_FLD_END_T are passed in the input flist, the helper opcode sets the starting timestamp to "pin_virtual_time" in BRM Developer's Guide.
When the amount is passed in the input flist, the helper opcode prepares the PIN_FLD_BAL_IMPACTS array, indexed by currency type.