8 Using Lightweight Authorization

This chapter describes the Oracle Communications Billing and Revenue Management (BRM) lightweight authorization feature. This feature enables you to override the resource availability, reservation amount, and scaled delay time for the service of a particular account.

Before you read this chapter, you should be familiar with the following:

• How BRM performs authentication, authorization, and accounting (AAA) for prepaid services. See "How BRM Processes Prepaid AAA Requests".

• How lightweight authorization allows you to improve performance of prepaid AAA by bypassing the rating and discounting engines for authorization in certain cases.

About Lightweight Authorization

Lightweight authorization allows you to improve performance of prepaid AAA by bypassing the rating and discounting engines for authorization in certain cases. Lightweight authorization improves the performance of authorization and reauthorization requests by doing the following:

• Reducing authorization latencies.

  To reduce authorization latencies, you can authorize customers who have a prepaid balance that is above a threshold limit to access services without requiring BRM to make calls to the rating and discounting engines. You can also reauthorize customers without going through the rating process as long as their prepaid balance is above the threshold limit. You can also reject authorization and reauthorization requests without calling the rating engine when customers have no resources.

  See "About Reducing Authorization Latencies".

• Reducing network spikes during a tariff change.

  Network spikes occur when a tariff change triggers reauthorizations for customer accounts. BRM assigns a validity period when a customer logs in that expires when the rates change. At the end of the validity period, BRM forces a reauthorization with the new rates. Because these reauthorization requests occur at the tariff change, this causes a spike in the network traffic.

  The reauthorizations make sure customers have enough resources to cover the new peak or non-peak rates for the service they are using. To reduce network spikes during a tariff change, you can reauthorize customers who have more resources in their accounts at a later time than those with fewer resources. Because the delayed reauthorization time is based on the customer's resource balance, the reauthorization requests are more evenly distributed.

  See "About Reducing Network Spikes during a Tariff Change".

You can configure lightweight authorization differently for each service. For example, you might configure lightweight authorization for both authorizations and reauthorizations for the service /service/telco/gprs but configure it for only authorizations for the service /service/telco/gsm/telephony. The data you configure for each service type is stored in the /config/auth_reauth_info object in the BRM database.

For information on configuring lightweight authorization, see "Setting Up Lightweight Authorization".

Note:

Lightweight authorization supports branding.

About Traffic-Light Status

Lightweight authorization uses a green-, yellow-, and red-light status for requiring rating for authorization and reauthorization requests. Table 8-1 summarizes how BRM handles authorization or reauthorization requests for each traffic light status:

Table 8-1 BRM Actions and Traffic-Light Status

Traffic-Light Status	BRM Action
Green	BRM approves the authorization request without making calls to the rating and discounting engines. Note: For a green-light status, BRM can deduct a reservation amount from the customer's resource balance to act as a security deposit. See "About the Reservation Amount".
Yellow	BRM calls the rating and discounting engines in calc-only mode to determine if the authorization request should be approved or rejected.
Red	BRM rejects the authorization request without making calls to the rating and discounting engines.

BRM uses a threshold value called the upper threshold for each resource in a given service to determine if the request has a green or yellow status. BRM uses a credit limit for each resource in a given service to determine if the request has a yellow or red status.

• The upper threshold is the minimum account balance required for an authorization request to be automatically approved. See "About the Upper Threshold".

• The credit limit is the minimum account balance required to use a service. Credit limits are typically set to zero. When an account balance does not meet the minimum credit limit, BRM automatically rejects the authorization request.

How BRM Determines the Traffic-Light Status

Because prepaid balances are represented as a negative value, prepaid balances start at a negative number and go towards zero as the customer uses those resources. For example, when you credit a customer's account with $25, the prepaid balance is -25; when the customer spends $10, the prepaid balance changes to -15.

Upper threshold and credit limit values are set to negative numbers as well. For example, to have an upper threshold of $25, you set the upper threshold to -25. Likewise, to have a credit limit of $2, you set the credit limit to -2.

Table 8-2 summarizes how BRM sets the traffic-light status:

Table 8-2 How BRM Sets Traffic-Light Status

Traffic-Light Status	Description
Green	The customer's current resource balance is less than the upper threshold value you set for that resource. For example, the upper threshold is -10 and the current balance is -25. balance < upper threshold
Yellow	The customer's current resource balance is the same as or greater than the upper threshold value you set for that resource, but the resource balance has not exceeded its credit limit. For example, the upper threshold is -10, the current balance is -5, and the credit limit is 0. credit limit > balance => Upper threshold
Red	The customer's resource balance is equal to or greater than the credit limit for that service. For example, the current balance is 0 and the credit limit is 0. balance => credit limit

For example, if you set the upper threshold to -10 and the credit limit to 0 as shown in Figure 8-1, BRM handles authorizations as follows:

• A customer who has a resource balance of -13 is authorized with a green-light status. BRM approves the authorization without calling the rating and discounting engines.

• A customer who has a resource balance of -8 is authorized with a yellow-light status. BRM calls the rating and discounting engines.

• A customer who has a resource balance of 0 is denied authorization. BRM rejects the authorization without going through the rating process.

Figure 8-1 Traffic-Light Status

Description of ''Figure 8-1 Traffic-Light Status''

About Traffic-Light Status and Multiple Resources in a Service

If there are multiple resources for the given service, BRM checks the account balance for all resources for the service and compares the balance of each resource with the upper threshold value set for each corresponding resource. BRM applies the following rules for traffic light status when there are multiple resources:

• If any resources are green = green-light status

• If any resources are yellow and none are green = yellow-light status

• If all resources are red = red-light status

For example, if two resources have a red-light status (reached their credit limits) and one resource has a green-light status, the request is authorized with a green-light status.

Figure 8-2 illustrates how BRM handles authorization and reauthorization requests when lightweight authorization is configured for the /service/telco/gsm/telephony service that offers both dollar and minute resources. Prepaid balances are represented as negative values, where the upper threshold for dollars is -10 and the upper threshold for minutes is -5 (Table 8-3):

Table 8-3 Upper Thresholds for Resources

Resource	Upper Threshold
Dollars	-10
Minutes	-5

Figure 8-2 Lightweight Authorization Example

Description of ''Figure 8-2 Lightweight Authorization Example''

About Traffic-Light Status and Sponsored Accounts

If you offer sponsored accounts, a sponsor can have sufficient resources to cover the cost of a call when the sponsoree does not have resources. To avoid rejecting the authorization request of the sponsoree in this case, set the AllowQuickReject entry to 0. By setting this entry to 0, BRM uses a yellow-light status rather than a red-light status for a sponsoree that has no resources. See "Configuring Lightweight Authorization".

About Reducing Authorization Latencies

BRM puts every authorization and reauthorization request through the calc-only rating process by making calls to the rating and discounting engines to accurately determine if a customer call can be approved or rejected based on rating results. You can configure BRM to approve authorization or reauthorization requests without going through the rating process when prepaid customers have sufficient funds or resources for a given service. You can also reject customer authorization or reauthorization requests without going through the rating process when they have no resources. By avoiding the rating process, you increase the number of authorization and reauthorization requests BRM can process per second for prepaid accounts.

The traffic-light status of the authorization request is what determines whether the rating and discounting engines will be called. See "About Traffic-Light Status".

To configure BRM to reduce authorization latencies, see "Setting Up Lightweight Authorization".

About the Upper Threshold

The upper threshold is the amount of resource, set for each resource in a service, that determines if an authorization request has a green- or yellow-light traffic-light status.

Green-light authorizations pose the risk that customers will exceed their credit limits before reauthorizations are sent because a validity period has not been obtained from the rating engine. For customers who are on line for the same amount of time, a lower value for the upper threshold poses less risk of revenue loss because it provides more time in which a reauthorization can occur after the customer's resource balance crosses into a yellow-light status.

Example: An upper threshold of $10 is more conservative than an upper threshold of $5.

Fred and Wilma each intend to make a 10-minute call at a rate of $1 per minute.

Fred has an account balance of $12 when he is authorized. The upper threshold is $10, so he gets a green-light status. After 8 minutes, Fred is reauthorized. He now has an account balance of $4. He gets a yellow-light status, which calls the rating engine and sets his validity period to 4 minutes. He hangs up after 2 minutes, leaving $2 in his account. If he had continued to talk, his call would have been dropped after 2 minutes because his validity period was known.

Wilma has an account balance of $6. The upper threshold is $5, so she gets a green-light status. After 8 minutes, Wilma is reauthorized. She has exceeded her credit limit by $2. Her call is dropped after a revenue loss of $2. Because the upper threshold was set so close to the credit limit, the reauthorization did not occur in time to prevent revenue loss.

To specify the upper threshold, set the UpperThreshold entry in the pin_config_auth_reauth_info.xml file. See "Configuring Lightweight Authorization".

For more information on traffic-light status, see "About Traffic-Light Status".

About the Reservation Amount

Important:

Using a reservation amount decreases performance.

The reservation amount is the ”security deposit” you can deduct from a customer's resource balance during green-light authorization and each green-light reauthorization. The amount represents whatever resource you are setting the reservation for, such as minutes, dollars, or frequent flyer miles.

Note:

If you do not plan to use lightweight authorization for reauthorizations, you do not need to set a reservation amount.

This reservation is used specifically for lightweight authorization because the rating and discounting engines are not called for green-light authorizations. BRM can also set aside a reservation amount to prevent customers from applying resources to other services while a session is in progress through concurrent network sessions (see "About Reserving Resources for Prepaid Services"). If other reservations exist, this reservation adds on to them. BRM uses the amount you specify to extend the reservation amount of the /reservation object.

BRM releases this reservation when the customer reaches a yellow-light status (when the rating engine is called). When the reservation amount is released, unused resources are returned to the customer's prepaid account balance.

To specify the reservation amount, set the ReservedAmt entry in the pin_config_auth_reauth_info.xml file. See "Configuring Lightweight Authorization".

For more information on traffic-light status, see "About Traffic-Light Status".

About Enabling Lightweight Authorization for Reauthorization Requests

You can use lightweight authorization when you only authorize requests (default) or when you both authorize and reauthorize requests.

To enable lightweight authorization for reauthorization requests, set the ReauthFlag entry in the pin_config_auth_reauth_info.xml file to 1. See "Configuring Lightweight Authorization".

When this entry is set to 0 for the specified service, BRM sends a yellow-light status so that normal rating occurs for the reauthorization of that service.

Note:

BRM sends the scaled delay time for reducing network spikes during a tariff change even when the ReauthFlag entry is set to 0. Thus, you can use that feature even if you choose to disable lightweight authorization for reauthorization requests. See "About Reducing Network Spikes during a Tariff Change".

How BRM Reduces Authorization Latencies

BRM reduces authorization latencies for prepaid accounts by eliminating calls to the rating and discounting engines for authorizations and reauthorizations that have a green-light or red-light traffic-light status.

The PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD opcode, the policy opcode PCM_OP_ACT_POL_SET_RESOURCE_STATUS, and the BRM authorization and reauthorization opcodes work together to reduce prepaid authorization latencies as follows:

1. PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD takes in the account and its related services and reads the /config/auth_reauth_info object to obtain lightweight authorization threshold data for each service.

2. PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD does the following for each service:

   If a service is not found in the /config/auth_reauth_info object, sets its status to a yellow light.

   If a service is found in the /config/auth_reauth_info object, sets the prepaid-traffic light status as follows:

   • Sets a green-light status if the current resource balance is less than the upper threshold (for example, the resource balance is $20 and the upper threshold is $10).

   • Sets a red-light status if all resource balances are above (have exceeded) the credit limit, unless the PIN_FLD_ALLOW_QUICK_REJECT field has been set to 0 for the service (which sets a yellow-light status instead, see "About Traffic-Light Status and Sponsored Accounts").

   • Sets a yellow-light status for reauthorization requests when the REAUTH_FLAG flag is set to 0 (see "About Enabling Lightweight Authorization for Reauthorization Requests").

3. PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD calls the policy opcode PCM_OP_ACT_POL_SET_RESOURCE_STATUS. You can override the traffic-light status, reservation amount, and scaled delay time for the service of a particular account based on your custom requirements.

   Note:

   By default, the new policy opcode returns the same traffic-light status, reservation amount, and scaled delay time as calculated by the PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD opcode. However, depending on your business requirements and custom rules, this opcode can override the traffic-light status, reservation amount, and scaled delay time for the service of a particular account.

4. The following authorization and reauthorization opcodes call PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD to obtain the prepaid traffic-light status of the service:

   • PCM_OP_TCF_AAA_AUTHORIZE

   • PCM_OP_TCF_AAA_REAUTHORIZE

   • PCM_OP_ACT_AUTHORIZE

   • PCM_OP_ACT_REAUTHORIZE

   If an authorization request has a green-light status with no reservation amount or a red-light status, the PCM_OP_TCF_AAA_AUTHORIZE (for authorizations) and PCM_OP_TCF_AAA_REAUTHORIZE (for reauthorizations) opcodes immediately approve or reject the request accordingly without making calls to the rating and discounting engines.

   If an authorization request has a green-light status with a reservation amount, the PCM_OP_ACT_AUTHORIZE (for authorizations) and PCM_OP_ACT_REAUTHORIZE (for reauthorizations) opcodes approve the request immediately without making calls to the rating and discounting engines.

For detailed information on how BRM authorizes and reauthorizes users when lightweight authorization is configured, see the following:

• How BRM Authorizes Users to Access Services When Lightweight Authorization Is Configured

• How BRM Reauthorizes Prepaid Services When Lightweight Authorization Is Configured.

About Reducing Network Spikes during a Tariff Change

During a tariff change, network elements, such as Services Framework, request a reauthorization for non-duration-based services (volume-based services) to verify that the service contains sufficient resources to cover the new rates. BRM assigns a validity period when a customer logs in that expires when the rates change. At the end of the validity period, BRM forces a reauthorization with the new rates. Because these reauthorization requests occur at the tariff change, this causes a spike in the network traffic.

To evenly distribute these reauthorization requests, BRM calculates a scaled delay time based on the available resources in the given service, which you can use to delay the reauthorization.

BRM calculates the scaled delay time according to the values you configure for the maximum time delay and the lower threshold. For information on how the maximum time delay and the lower threshold affect the scaled delay time, see "About the Lower Threshold" and "About the Maximum Time Delay".

The scaled delay time is calculated as shown in Figure 8-3 by multiplying the maximum time delay by a scaling factor. The scaling factor is the credit limit (which is typically 0) minus the customer's resource balance divided by the credit limit minus the lower threshold:

Figure 8-3 Scaled Delay Time Calculation

Description of ''Figure 8-3 Scaled Delay Time Calculation''

To configure BRM to reduce network spikes during a tariff change, see "Setting Up Lightweight Authorization".

About the Lower Threshold

BRM uses the lower threshold in conjunction with the maximum time delay to calculate the scaled delay time. The value represents the resource for which it is configured.

BRM recommends you set the lower threshold to a lower value than the upper threshold (the entry that sets the threshold for a green-light status). For example, set an upper threshold of $10 and a lower threshold of $30.

For a given account balance and a given maximum time delay, the lower the value for the lower threshold, the shorter the scaled delay time and the earlier the reauthorization.

For example, if the maximum time delay is 20 minutes, a prepaid account authorized with a Dollar resource balance of $20 has a scaled delay time of 16 minutes if the lower threshold is $25 or 8 minutes if the lower threshold is $50.

About the Maximum Time Delay

The maximum time delay is the maximum delay that can be returned to the caller. The value is passed in as a number. You specify whether the value is in seconds or minutes in your custom code.

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

How BRM Uses a Scaled Delay Time to Reduce Network Spikes during a Tariff Change

BRM calculates a scaled delay time you can use to more evenly distribute reauthorizations during a tariff change as follows:

1. The PCM_OP_ACT_AUTHORIZE or PCM_OP_ACT_REAUTHORIZE opcode calls the PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD opcode to obtain the service's traffic-light status and the scaled delay time.

2. PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD calculates the scaled delay time (PIN_FLD_SCALED_DELAY_TIME). See "About Reducing Network Spikes during a Tariff Change".

3. PCM_OP_ACT_AUTHORIZE or PCM_OP_ACT_REAUTHORIZE passes the traffic-light status and the scaled delay time to the PCM_OP_ACT_POL_POST_AUTHORIZE and PCM_OP_ACT_POL_POST_REAUTHORIZE policy opcodes.

   Note:

   You can modify these policy opcodes to customize the scaled delay time if desired. See "Customizing the Scaled Delay Time".

4. PCM_OP_ACT_AUTHORIZE or PCM_OP_ACT_REAUTHORIZE passes the scaled delay time to the Services Framework opcodes.

   Note:

   The validity period (PIN_FLD_VALID_TO) is not modified. In the case of a yellow-light status when the rating engine is called, PCM_OP_ACT_AUTHORIZE and PCM_OP_ACT_REAUTHORIZE pass the validity period in addition to the scaled delay time to the Services Framework opcodes.

5. The Services Framework opcodes use the scaled delay time according to your custom code to calculate the delayed reauthorization time.

   For example, in the case of a yellow-light status, you might choose to add the scaled delay time to the validity period returned from the rating engine. In the case of a green-light status, when the rating engine is not called and the validity period is not returned, you might choose to add the scaled delay time to the current GMT time.

To configure BRM to reduce network spikes during a tariff change, see "Setting Up Lightweight Authorization".

How BRM Authorizes Users to Access Services When Lightweight Authorization Is Configured

The main opcode for authorizing prepaid services is PCM_OP_TCF_AAA_AUTHORIZE.

BRM authorizes prepaid services as follows when lightweight authorization is configured:

1. PCM_OP_TCF_AAA_AUTHORIZE calls the PCM_OP_ACT_FIND opcode to locate the customer's account information. The opcode returns the customer's /account and /service objects.

2. PCM_OP_TCF_AAA_AUTHORIZE calls PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD to obtain the traffic-light status of the service. For information on how the traffic-light status is set, see "How BRM Reduces Authorization Latencies".

3. PCM_OP_TCF_AAA_AUTHORIZE does the following:

   • For services with a green-light status that have no reservation amount, immediately approves the authorization request without making calls to the rating and discounting engines.

   • For services with a green-light status with a reservation amount, continues with step 4.

   • For services with a yellow-light status, continues with step 4.

   • For services with a red-light status, immediately rejects the authorization request without making calls to the rating and discounting engines.

     Note:

     If a sponsoree account has no resources (a red-light status), PCM_OP_TCF_AAA_AUTHORIZE does not reject the authorization if you set the AllowQuickReject entry to 0 for that service. See "About Traffic-Light Status and Sponsored Accounts".

4. At the SEARCH_SESSION stage, PCM_OP_TCF_AAA_AUTHORIZE calls the helper opcode specified in the /config/opcodemap/tcf object. The helper opcode returns a search template for finding session objects.

5. PCM_OP_TCF_AAA_AUTHORIZE uses the template to search for duplicate sessions. If the opcode finds a session with the same active session ID, authorization fails.

6. At the PREP_INPUT stage, PCM_OP_TCF_AAA_AUTHORIZE calls the helper opcode specified in the /config/opcodemap/tcf object to aggregate service-specific data. The helper opcode returns a service-specific input flist.

7. At the VALIDATE_LIFECYCLE stage, PCM_OP_TCF_AAA_AUTHORIZE 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, the authorization process continues. If validation fails, the request is denied.

8. PCM_OP_TCF_AAA_AUTHORIZE passes the service-specific input flist to PCM_OP_ACT_AUTHORIZE.

9. PCM_OP_ACT_AUTHORIZE calls PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD to obtain the traffic-light status of the service.

10. PCM_OP_ACT_AUTHORIZE does the following:

    • For services with a green-light status with a reservation amount, reserves the reservation amount and approves the authorization request without making calls to the rating and discounting engines.

      To reserve the reservation amount, calls the PCM_OP_RESERVE_CREATE opcode with an amount-based request to create the reservation amount specific to lightweight authorization in the /reservation object. See "About the Reservation Amount".

    • For services with a yellow-light status, makes calls to the rating and discounting engines to see whether the authorization request should be approved or rejected (calls the PCM_OP_ACT_POL_PRE_AUTHORIZE policy opcode).

11. PCM_OP_ACT_AUTHORIZE calls the PCM_OP_ACT_POL_POST_AUTHORIZE policy opcode to make any specified customizations to its output flist before returning the flist to the calling opcode. By default, the policy opcode drops the PIN_FLD_RESULTS field from the flist.

For information on how BRM authorizes prepaid services when lightweight authorization is not configured, see "How BRM Authorizes Users to Access Prepaid Services".

For more information about prepaid authorization, see "About Authorizing Prepaid Usage".

How BRM Reauthorizes Prepaid Services When Lightweight Authorization Is Configured

The main opcode for reauthorizing prepaid services is PCM_OP_TCF_AAA_REAUTHORIZE.

BRM reauthorizes prepaid sessions as follows when lightweight authorization is configured:

1. PCM_OP_TCF_AAA_REAUTHORIZE calls PCM_OP_ACT_FIND to locate the customer's account information. The opcode returns the customer's /account and /service objects.

2. PCM_OP_TCF_AAA_REAUTHORIZE calls PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD to obtain the traffic-light status of the service. For information on how the traffic-light status is set, see "How BRM Reduces Authorization Latencies".

3. PCM_OP_TCF_AAA_REAUTHORIZE does the following:

   • For services with a green-light status that have no reservation amount, immediately approves the reauthorization request without making calls to the rating and discounting engines.

   • For services with a green-light status with a reservation amount, continues with step 4.

   • For services with a yellow-light status, continues with step 4.

   • For services with a red-light status, immediately rejects the reauthorization request without making calls to the rating and discounting engines.

     Note:

     If a sponsoree account has no resources (a red-light status), PCM_OP_TCF_AAA_AUTHORIZE does not reject the authorization if you set the Allow Quick Reject entry to 0 for that service. For more information, see "About Traffic-Light Status and Sponsored Accounts".

4. At the SEARCH_SESSION stage, PCM_OP_TCF_AAA_REAUTHORIZE calls the helper opcode specified in the /config/opcodemap/tcf object. The helper opcode returns a search template for finding session objects.

5. PCM_OP_TCF_AAA_REAUTHORIZE uses the template to search for the /active_session object.

   • If the object is found, the opcode calls the appropriate PREP_INPUT helper opcode to prepare a service-specific input flist and then passes the input flist to PCM_OP_ACT_REAUTHORIZE to reauthorize the call.

   • If the object is not found, the opcode calls the appropriate PREP_INPUT helper opcode to prepare a service-specific input flist and then passes the input flist to PCM_OP_ACT_AUTHORIZE to authorize the session with the given information.

6. PCM_OP_ACT_REAUTHORIZE determines whether the session's /active_session object (PIN_FLD_POID in the input flist) and /reservation_active object (PIN_FLD_RESERVATION_OBJ in the input flist) exist.

   • If the objects exist, the opcode continues with step 7.

   • If the objects do not exist, the opcode calls PCM_OP_ACT_AUTHORIZE to perform a session authorization.

     Note:

     If IMDB Cache shuts down after a prepaid session begins, the session's /active_session and /reservation_active objects will no longer exist.

7. PCM_OP_ACT_REAUTHORIZE calls PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD to obtain the traffic-light status of the service.

8. PCM_OP_ACT_REAUTHORIZE does the following:

   • For services with a green-light status with a reservation amount, reserves the reservation amount and approves the reauthorization request without making calls to the rating and discounting engines.

     To reserve the reservation amount, calls the PCM_OP_RESERVE_EXTEND opcode with an amount-based request to extend the reservation amount specific to lightweight authorization in the /reservation object. For more information, see "About the Reservation Amount".

     PCM_OP_ACT_REAUTHORIZE calls the PCM_OP_RESERVE_EXTEND opcode with the PIN_RESERVE_INCREMENTAL_AMOUNT mode.

   • For services with a yellow-light status, makes calls to the rating and discounting engines to see whether the reauthorization request should be approved or rejected (calls the PCM_OP_ACT_POL_PRE_REAUTHORIZE policy opcode).

9. PCM_OP_ACT_REAUTHORIZE calls the PCM_OP_ACT_POL_POST_REAUTHORIZE policy opcode to make any specified customizations to its output flist before returning the flist to the calling opcode. By default, the policy opcode drops the PIN_FLD_RESULTS field from the flist.

   Note:

   If a reauthorization request has a green-light status with no reservation amount or a red-light status, PCM_OP_TCF_AAA_REAUTHORIZE approves or rejects the request respectively without calling PCM_OP_ACT_REAUTHORIZE.

   If a reauthorization request has a green-light status with a reservation amount or a yellow-light status, PCM_OP_TCF_AAA_REAUTHORIZE calls PCM_OP_ACT_REAUTHORIZE to handle the request.

For information on how BRM reauthorizes prepaid services when lightweight authorization is not configured, see "How BRM Reauthorizes Prepaid Services".

For more information about prepaid reauthorization, see "About Reauthorizing Prepaid Usage".

About Setting the Reauthorization Amount

Reauthorizations are supported only in the cumulative mode (that is, the reauthorization amount or quantity represents the original authorization amount plus a requested extension amount). For example, if you authorize a customer for 10 minutes and want to reauthorize for another 10 minutes, the time sent must be 20 minutes.

You must do the following when using lightweight authorization:

• Pass the full reauthorization amount or quantity to PCM_OP_TCF_AAA_REAUTHORIZE.

• Set the PCM_OP_TCF_AAA_REAUTHORIZE opcode's PIN_FLD_AGGREGATE_MODE input flist field to 4 to specify that the reauthorization amount or quantity is cumulative.

Setting Up Lightweight Authorization

To configure lightweight authorization data, edit the pin_config_auth_reauth_info.xml file and load the contents of the file into the BRM database by using the load_pin_config_auth_reauth_info utility. The data is stored in the /config/auth_reauth_info object.

By default, the /config/auth_reauth_info object contains lightweight authorization data for default service types and resources only. You can configure data for additional services and resources in the /config/auth_reauth_info object during customization, as well as modify the data for the default service types and resources.

Note:

This procedure configures both of these lightweight authorization features:

• Reducing authorization latencies. See "About Reducing Authorization Latencies".

• Reducing network spikes during a tariff change. See "About Reducing Network Spikes during a Tariff Change".

To configure lightweight authorization, do the following:

1. Enable lightweight authorization in the business_params object. See "Enabling Lightweight Authorization in BRM".

2. Configure lightweight authorization. See "Configuring Lightweight Authorization".

3. Edit the prepaid traffic-light configuration file. See "Editing the Lightweight Authorization Configuration File".

Enabling Lightweight Authorization in BRM

To enable lightweight authorization, update the activity parameter instance in the /config/business_params object by using the pin_bus_params utility.

1. Create an editable XML file for the activity parameter instance by using the following command:

   pin_bus_params -r BusParamsActivity bus_params_act.xml
   

   This command creates the XML file named bus_params_act.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.

2. Search the XML file for the following line:

   <LightWeightAuthorization>disabled</LightWeightAuthorization>
   

3. Changed disabled (default) to enabled.

   Caution:

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

4. Save the file and change the file name from bus_params_act.xml.out to bus_params_act.xml.

5. Use the following command to load the change into the /config/business_params object:

   pin_bus_params bus_params_act.xml
   

   Run this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To run it from a different directory, see "pin_bus_params" in BRM Developer's Guide.

6. Read the object with the testnap utility or Object Browser to verify that all fields are correct. See "Reading an Object and Fields" in BRM Developer's Guide.

7. Stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

8. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in BRM System Administrator's Guide.

Configuring Lightweight Authorization

To configure authorization and reauthorization threshold data for lightweight authorization (the /config/auth_reauth_info object), edit the lightweight authorization configuration file (pin_config_auth_reauth_info.xml) and then load its contents into the BRM database:

1. Open the pin_config_auth_reauth_info.xml file in an XML editor or a text editor.

   By default, the file is in the BRM_Home/sys/data/config directory.

2. Enter the appropriate information into the file. See "Editing the Lightweight Authorization Configuration File".

3. Save the edited file.

4. Use this command to load the pin_config_auth_reauth_info.xml file by running the load_pin_config_auth_reauth_info utility from the directory in which the pin_config_auth_reauth_info.xml file is located:

   load_pin_config_auth_reauth_info pin_config_auth_reauth_info.xml
   

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

   load_pin_config_auth_reauth_info BRM_Home/sys/data/config/pin_config_auth_reauth_info.xml
   

   Caution:

   The load_pin_config_auth_reauth_info utility overwrites existing authorization and reauthorization threshold data for lightweight authorization. If you are updating data, you cannot load new data only. You must load complete sets of data each time you run the load_pin_config_auth_reauth_info utility.

   Important:

   • The BRM database must be up and running.

   • To connect to the BRM database, the load_pin_config_auth_reauth_info utility needs a configuration (pin.conf) file in the directory from which you run the utility. For more information on creating configuration files for BRM utilities, see "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

   Note:

   • You can run this utility to configure lightweight authorization for different brands. The utility loads the /config/auth_reauth_info object to the current brand in which it logs in. For information on running utilities with a branded database, see "Configuring a Branded Database" in BRM Managing Customers.

   • If you copy the pin_config_auth_reauth_info.xml file to the directory from which you run the load_pin_config_auth_reauth_info utility, you do not have to specify the path or file name. By default, the file is named pin_config_auth_reauth_info.xml. You can change this name.

   For more information, see "Services Framework AAA Utilities".

5. Restart the CM.

6. To verify that the authorization and reauthorization threshold data was loaded, you can display the /config/auth_reauth_info object by using the Object Browser application in Developer Center, or using the robj command with the testnap utility.

Editing the Lightweight Authorization Configuration File

You configure the authorization and reauthorization threshold data (/config/auth_reauth_info object) for lightweight authorization in your BRM system in the BRM_Home/sys/data/config/pin_config_auth_reauth_info.xml file.

You edit this prepaid traffic-light configuration file to configure both of these prepaid-traffic light authorization features:

• Reducing authorization latencies. See "Editing the File to Reduce Authorization Latencies".

• Reducing network spikes during a tariff change. See "Editing the File to Reduce Network Spikes during a Tariff Change".

Editing the File to Reduce Authorization Latencies

To reduce authorization latencies, perform these tasks:

1. Open the pin_config_auth_reauth_info.xml file in an XML editor or text editor.

2. Set the following entries for each service that uses lightweight authorization:

   • Set the UpperThreshold entry for each resource in the service. See "About Reducing Authorization Latencies".

   • Set the ReservedAmt entry for each resource in the service. See "About the Reservation Amount".

   • Set the ReauthFlag entry. See "About Enabling Lightweight Authorization for Reauthorization Requests".

   • Set the AllowQuickReject entry. See "About Traffic-Light Status and Sponsored Accounts".

Editing the File to Reduce Network Spikes during a Tariff Change

To reduce network spikes during tariff changes, perform these tasks:

1. Open the pin_config_auth_reauth_info.xml file in an XML editor or text editor.

2. Set the following entries for each service that uses lightweight authorization:

   • Edit the LowerThreshold entry for each resource in the service. See "About the Lower Threshold" and "How BRM Uses a Scaled Delay Time to Reduce Network Spikes during a Tariff Change".

   • Edit the MaxTimeDelay entry. See "About the Maximum Time Delay" and "How BRM Uses a Scaled Delay Time to Reduce Network Spikes during a Tariff Change".

   • (Optional) Customize the calculation of the scaled delay time. See "Customizing the Scaled Delay Time".

Format of the Prepaid Traffic-Light Configuration File

The format of the pin_config_auth_reauth_info.xml file is as follows:

<AuthReauthInfoConfiguration>
   <ServiceConfig>
      <ServiceType>service_type_name</ServiceType>
         <ReauthFlag>reauthorization_flag</ReauthFlag>
         <MaxTimeDelay>max_time_delay</MaxTimeDelay>
          <ResourceType>
            <ResourceID>resource_id</ResourceID>
               <OnCondition> 
                  <UpperThreshold>threshold_upper</UpperThreshold>
                  <LowerThreshold>threshold_lower</LowerThreshold>
                  <ReservedAmt>reservation_amt</ReservedAmt>
               </OnCondition>
          </ResourceType>
            <!-Can repeat other ResourceType>
      …
   </ServiceConfig>
   …
   <!-Can repeat other ServiceConfigs>
</AuthReauthInfoConfiguration>

Sample Prepaid Traffic-Light Configuration File

The following sample pin_config_auth_reauth_info.xml file shows a different prepaid traffic-light configuration for two services:

<AuthReauthInfoConfiguration
         xmlns="http://www.portal.com/schemas/BusinessConfig"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.portal.com/schemas/BusinessConfig
pin_config_auth_reauth_info.xsd">
  
   <ServiceConfig>
      <ServiceType>/service/gsm/telephony</ServiceType>
      <ReauthFlag>1</ReauthFlag>
      <MaxTimeDelay>600</MaxTimeDelay>
      <AllowQuickReject>1</AllowQuickReject>
      <ResourceConfig ResourceId="978">
         <UpperThreshold>-10</UpperThreshold>
         <LowerThreshold>-5</LowerThreshold>
         <ReservedAmt>3</ReservedAmt>
      </ResourceConfig>
      <ResourceConfig ResourceId="250">
         <UpperThreshold>-60</UpperThreshold>
         <LowerThreshold>-30</LowerThreshold>
         <ReservedAmt>18</ReservedAmt>
      </ResourceConfig>
   </ServiceConfig>
  
   <ServiceConfig>
      <ServiceType>/service/telco/gsm</ServiceType>
      <ReauthFlag>1</ReauthFlag>
      <MaxTimeDelay>800</MaxTimeDelay>
      <AllowQuickReject>0</AllowQuickReject>
      <ResourceConfig ResourceId="978">
         <UpperThreshold>-15</UpperThreshold>
         <LowerThreshold>-7</LowerThreshold>
         <ReservedAmt>2</ReservedAmt>
      </ResourceConfig>
      <ResourceConfig ResourceId="250">
         <UpperThreshold>-90</UpperThreshold>
         <LowerThreshold>-48</LowerThreshold>
         <ReservedAmt>12</ReservedAmt>
      </ResourceConfig>
   </ServiceConfig>
  
</AuthReauthInfoConfiguration>
  

Table 8-4 summarizes the configuration entries in the pin_config_auth_reauth_info.xml file:

Table 8-4 Entries in pin_config_auth_reauth_info.xml File

XML File Entry	Description
ServiceType	The service type for which lightweight authorization needs to be enabled, in the format /service/ name or /service/name/name. Enter the name of a service defined in your BRM system. You can have a different prepaid traffic-light configuration for each service.
ReauthFlag	(Optional) Enables (1) or disables (0, the default) lightweight authorization for the reauthorization for the given service. See "About Enabling Lightweight Authorization for Reauthorization Requests".
MaxTimeDelay	Maximum delay time that can be returned to the caller. See "About the Maximum Time Delay".
AllowQuickReject	Disallows (0) a red-light status for sponsoree accounts and returns a yellow-light status instead. See "About Traffic-Light Status and Sponsored Accounts".
ResourceConfig	List of all resources for the given service for which you want to use lightweight authorization. Note: The UpperThreshold, LowerThreshold, and ReservedAmt entries must be configured for each resource in a service.
UpperThreshold	Upper threshold value to identify cases for green-light authorization. See "About the Upper Threshold". Set this entry for each resource in the service. The value represents whatever resource you are configuring, such as minutes, dollars, or frequent flyer miles. Note: This entry is not related to the LowerThreshold entry for identifying a green-light status.
LowerThreshold	Lower threshold value to calculate the time delay. It is mandatory if MaxTimeDelay is set. See "About the Lower Threshold". Set this entry for each resource in the service. The value represents whatever resource you are configuring, such as minutes, dollars, or frequent flyer miles. BRM recommends you use a lower value for the lower threshold than the upper threshold (for example, if the upper threshold is -20, the lower threshold is -30). Note: This entry is not related to the UpperThreshold entry for identifying a green-light status.
ReservedAmt	In case of green-light authorization, the amount of resource to be reserved. See "About the Reservation Amount". Set this entry for each resource in the service. Note: If you set ReauthFlag to 0 to disable lightweight authorization for the reauthorization for the given service, you do not need to set a reservation amount.

Customizing the Scaled Delay Time

To customize the calculation of the scaled delay time, modify the PCM_OP_ACT_POL_POST_AUTHORIZE policy opcode or the PCM_OP_ACT_POL_POST_REAUTHORIZE policy opcode. Use the PIN_FLD_RESOURCE_STATUS and PIN_FLD_SCALED_DELAY_TIME fields in these policy opcodes to revert the scaled delay time, to apply a new scale, or both.

PCM_OP_ACT_AUTHORIZE calls the following opcodes before returning values to the Services Framework:

• PCM_OP_ACT_PRE_AUTHORIZE

• PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD, which returns the scaled delay time

• PCM_OP_ACT_POL_POST_AUTHORIZE or PCM_OP_ACT_POL_POST_REAUTHORIZE

Use the PCM_OP_ACT_POL_POST_AUTHORIZE policy opcode or the PCM_OP_ACT_POL_POST_REAUTHORIZE policy opcode to modify the scaled delay time that is passed in from PCM_OP_ACT_CHECK_RESOURCE_THRESHOLD so that PCM_OP_ACT_AUTHORIZE will send back your version of the scaled delay to the Services Framework.

Overriding the Traffic-Light Status, Reservation Amount, and Scaled Delay Time

You can override the traffic-light status, reservation amount, and scaled delay time by using the PCM_OP_ACT_POL_SET_RESOURCE_STATUS opcode.

The PCM_OP_ACT_POL_SET_RESOURCE_STATUS opcode includes the following fields in the output:

• PIN_FLD_RESULT specifies the resource availability status.

• PIN_FLD_SCALED_DELAY_TIME specifies the delay time in seconds. The value can be any decimal number.

• PIN_FLD_BALANCES specifies the balance amount to be reserved during a quick authorization, namely, the green traffic-light status.

  Note:

  BRM does not validate the values set for the resource availability status, reservation amount, and scaled delay time for the service of a particular account in the PCM_OP_ACT_POL_SET_RESOURCE_STATUS policy opcode. To avoid potential problems such as revenue leakage, it is important that you set the appropriate values.

Consider the following examples:

• A case where BRM returns a yellow-light status and you want to override it to green. Based on the customer's current resource balance, you can do so by setting the resource availability status to green and the balance amount to be reserved in the output flist of the PCM_OP_ACT_ POL_SET_RESOURCE_STATUS policy opcode.

• A case where BRM returns a red-light status and you want to override it to green. You can do so by setting the resource availability status to green and the balance amount to be reserved to zero in the output flist of the PCM_OP_ACT_ POL_SET_RESOURCE_STATUS policy opcode. In this case, the call will be authorized even though the customer has insufficient resource balance.

  Note:

  Oracle does not ship the source code files for policy opcodes. You must create your own source code for the new policy opcode. For more information about customizing policy opcodes, see "Adding and Modifying Policy Facilities Modules" in BRM Developer's Guide.