15 Managing Sub-Balances

This document describes how to manage sub-balances in Oracle Communications Billing and Revenue Management (BRM) Pricing Center. It describes balance impacts, credit limits, and rollovers.

Topics in this document:

• About Sub-Balances

• About Noncurrency Sub-Balances

• How Resources in Validity-Based Sub-Balances Are Updated

• About Configuring Sub-Balances

• Configuring Sub-Balances

• Sub-Balance Configuration Example

• Specifying the Order in Which Resource Sub-Balances Are Consumed

• About Rollovers

• About Rolling Over Free Resources during Plan Transition

About Sub-Balances

Each balance in a balance group can include one or more sub-balances. A balance includes sub-balances when portions of the balance are valid at different times or when a portion of the balance is a loan. For example, a balance of minutes might include 300 minutes that are valid only for the current month and 1000 minutes that never expire.

A currency sub-balance can store the balances for multiple services. For example, an account that owns two products that cost $25.00 per product has a starting currency sub-balance of $50.00, providing the services are associated with the same balance group and have the same validity period.

A currency balance can also store sub-balances for loans. For example, if an account subscribed to a monthly package that costs $25.00 only has a balance of $15.00 at billing time, you can grant a loan for the remaining $10.00. The balance would then consist of two sub-balances; a $15 regular sub-balance and a $10 loan sub-balance.

Sub-balances include the following information:

• The sub-type. This indicates whether the sub-balance is a loan or not.
• The start time and end time for which the sub-balance is valid.

  Common resources with the same validity periods are stored in the same sub-balance. Resources with unique validity periods are stored in separate sub-balances. For more information, see "How Resources in Validity-Based Sub-Balances Are Updated".

  For information about rounding the start times of cycle and purchase grants to midnight, see "Configuring Time-Stamp Rounding for Validity Period Start Times".

• The current amount of the sub-balance.
• Consumed reservation (or active reserved amount) which tracks the consumed reservation and is used to set up notifications to the network.

  See the discussion on calculating reservation balances in BRM Telco Integration.

• The fields in the event record or object (referred to as “contributors") that contribute to how sub-balances are created, updated, and retrieved. For example, to retrieve the total available balance for a specific service, the service object is specified. To deduct free minutes for a phone call, the session object is specified. A separate sub-balance is kept for each unique contributor. See "About Sub-Balance Contributors".
• Rollover data such as the rollover period and the resource amount that is rolled over, if any. For more information, see "About Rollovers".
• The ID of the product or discount that granted the resource (referred to as “grantor object.")

You can configure sub-balances to track various types of resources and usage. See "About Configuring Sub-Balances".

About Noncurrency Sub-Balances

A noncurrency sub-balance typically has a limited validity period (for example, the period during which free minutes can be used). Noncurrency sub-balances can contain various types of resources, such as:

• Free minutes.

• Frequent flyer miles.

• Loyalty points.

• Number of emails or text messages.

A noncurrency sub-balance can also keep track of the total resources used for discounts that are shared among several accounts. In this case, the sub-balance acts as a counter to keep track of the total consumed resource.

When granting a noncurrency resource, if a sub-balance already exists, BRM compares the new balance data with the following data in the existing valid sub-balances:

• Contributor

• Grantor object

• Rollover data

• Valid-from date

• Valid-to date

If the data matches, BRM adds the amount to the existing sub-balance; otherwise, it creates a new sub-balance.

For information about configuring sub-balances, see "About Configuring Sub-Balances".

How Resources in Validity-Based Sub-Balances Are Updated

By default, BRM stores common resources with the same validity periods in the same sub-balance, provided they are associated with the same balance group. (You can create separate balance groups per service in Pricing Center. See "Tracking Resources by Service".) BRM automatically creates a new sub-balance for resources with a unique validity period, if one does not already exist.

For example, an account owns two services that each include 100 free minutes that are always valid. The account has a balance of 200 free minutes stored in a single sub-balance. When the customer uses free minutes from each service, the free minutes are consumed from the common sub-balance.

Common resources with different validity periods are tracked in separate sub-balances. For example, an account owns two services that each include 100 free minutes. Free minutes for service 1 expire at the end of the month, and free minutes for service 2 expire at the end of the year. Each set of free minutes is stored in a separate sub-balance.

Note:

When common, noncurrency resources are configured to start on first usage, BRM creates a new sub-balance for each resource whether or not they have the same validity period. See "About Noncurrency Sub-Balances That Start on First Usage".

You can specify the order in which sub-balances are consumed by setting up resource consumption rules. See "Specifying the Order in Which Resource Sub-Balances Are Consumed".

You can also limit how validity-based resources, such as free minutes, are consumed by configuring sub-balances. For example, you might want to limit usage of free minutes to a specific service or a specific call session. See "About Configuring Sub-Balances".

Configuring Time-Stamp Rounding for Validity Period Start Times

You can configure BRM to round time stamps to midnight for resources granted by cycle and purchase events.

See the following:

• Configuring Time-Stamp Rounding for Cycle Grants
• Configuring Time-Stamp Rounding for Purchase Grants

Note:

When the resource's purchase, cycle, and usage start and end units are set to 1 (seconds), 2 (minutes), or 3 (hours), and the validity period is less than 24 hours, time stamps are not rounded, regardless of your system configuration. If the validity is greater than 24 hours, the cycle, usage, and purchase end time stamps are rounded for the purpose of calculating the scale to determine the cycle fee amount to charge.

Configuring Time-Stamp Rounding for Cycle Grants

To configure BRM to round time stamps to midnight for the resources granted by cycle events:

1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf) in a text editor.

2. Set the timestamp_rounding entry to 1.

3. Save and close the file.

Configuring Time-Stamp Rounding for Purchase Grants

To configure BRM to round time stamps to midnight for the resources granted by purchase events:

1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf) in a text editor.

2. Set the timestamp_rounding entry to 1.

3. Save and close the file.

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

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

   pin_bus_params -r BusParamsRating bus_params_rating.xml 
   

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

6. Open the bus_params_rating.xml.out file.

7. Search for the following line:

   <TimestampRoundingForPurchaseGrant>disabled</TimestampRoundingForPurchaseGrant>
   

8. Change disabled to enabled.

9. Save the file as bus_params_rating.xml.

10. Run the following command, which loads this change into the appropriate /config/business_params object.

    pin_bus_params PathToWorkingDirectory/bus_params_rating.xml
    

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

    Caution:

    BRM uses the XML in this file to overwrite the existing rating 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 BRM's rating configuration.

    Note:

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

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

12. Stop and restart the CM.

About Noncurrency Sub-Balances That Start on First Usage

When a noncurrency resource is configured to start on first usage (when the customer first consumes the resource balance), BRM always creates a new sub-balance for that resource when it is granted. A new sub-balance is created for each resource even when a product or discount grants multiple first-usage resources of the same type. (For more information about first-usage start times, see "About Balance Impacts That Become Valid on First Usage".)

For example, a product includes two grants of 100 free minutes. Each grant starts on first usage and ends at the end of the cycle. When the product is purchased, BRM adds two free-minute sub-balances to the account, one for each grant.

Keeping first-usage resources in separate sub-balances enables those balances to have unique validity periods, which are set individually when each resource is consumed. For example, if there are two balances of 100 free minutes each and the customer makes a 30-minute phone call, the validity period of only the balance that was consumed is set when the call is made.

A resource balance that has a first-usage start time will remain available for consumption for as long as the balance is not used. For example, on January 1, a customer purchases a deal that includes 30 free text messages that are valid for 30 days from first usage. The text message balance remains unused in the account until April 18, when the customer sends the first text message. The validity period of the text message balance is then set to start on April 18 and end 30 days later, on May 17.

About Configuring Sub-Balances

You can optionally configure sub-balances to track resources for more specific types of usage such as:

• Free minutes per call session.

• Frequent flyer miles per service instance.

• Friends and family calls to specific locations.

• Discount amounts shared with sponsored accounts.

You configure sub-balances for the entire BRM system by editing and loading a configuration file.

By default, common resources for all services owned by an account are placed in the same sub-balance if they have the same validity period and are associated with the same balance group. (You can create separate balance groups per service in Pricing Center. See "Tracking Resources by Service".)

To limit the allocation and consumption of resources, you configure sub-balances by specifying the following values:

• Resource ID. This is the ID for the type of resource in the sub-balance, such as dollars or free minutes.

• Event type. This is the type of event that impacts the sub-balance, such as GSM usage events (/event/session/telco/gsm).

• Contributors. Contributors can be any field in the event record or object. There are two types of contributors:

  • Retrieving contributor. All sub-balances with common retrieving contributors are summed when sub-balances are retrieved. For example, to retrieve the total balance for specific services, specify the service object as the retrieving contributor.

  • Updating contributor. A sub-balance is created or updated by balance impacts for each unique updating contributor. For example, to add or deduct free minutes for specific dialup sessions, specify the session object as the updating contributor.

About Sub-Balance Contributors

Sub-balance contributors are specified by a field name from the event record or object. The value in the field you specify is used to retrieve and update the sub-balances. Some fields you might want to use as contributors include:

• The service object.

  Specify a service field to track resources for specific service instances such as fax, telephony, and text messaging.

  Note:

  Specifying the service object in the configuration is one way of creating service-level balances. The other way is to create a balance group for the service when you define your plans in Pricing Center. See "Tracking Resources by Service".

• The session object.

  Specify a session field to track resources per session instance. This is useful when you offer discounts for certain levels of usage (for example, 10 frequent flyer miles per hour of phone calls).

• The product object.

  When several products in the same plan have different rollover rules, tracking resources per product permits BRM to update the free minutes for each product.

• The phone number field.

  Specify a phone number field to track resources for called telephone numbers.

• The account object.

  Specify the account field to track resources that are shared among several accounts, such as earned free minutes. When free minutes are distributed, they can be divided based on each account's usage level.

Retrieving and Updating Sub-Balances

Sub-balances are retrieved for a given resource. For example, when CSRs use Customer Center to view an account's current cash balance, all valid cash sub-balances (sub-balances with current validity periods and matching contributors) are summed to provide the current resource balance.

Sub-balances are updated by a balance impact. When a balance impact affects more than one sub-balance, the sub-balances are updated in the following order:

1. By validity period. By default, sub-balances are updated in chronological order based on the validity start date or end date. You specify the order in which sub-balances are used by setting up resource consumption rules. See "Specifying the Order in Which Resource Sub-Balances Are Consumed".

2. By contributor. Sub-balances with specific field contributors are impacted before sub-balances that accept all contributors (with an asterisk or empty contributor values). See "Configuring Sub-Balances".

Configuring Sub-Balances

To configure sub-balances, you edit the sub-balance configuration file and then run the load_pin_sub_bal_contributor utility to load the contents of the file into the /config/sub_bal_contributor object in the BRM database.

Editing the pin_sub_bal_contributor File

Each line in the pin_sub_bal_contributor file defines the usage for which a sub-balance is created. The configurations apply to all sub-balances in the BRM database, but they are implemented at the balance group level. That is, when a usage event occurs, if the account has more than one balance group, only the sub-balances within the specified balance groups are impacted.

To add sub-balance configurations, use this syntax:

resource_type:event_type:retrieving_contributor:updating_contributor

For example:

1000003:/event/session/gprs:PIN_FLD_SESSION_OBJ:PIN_FLD_SESSION_OBJ

where:

• 1000003 is the resource type for frequent flyer miles.

• /event/session/gprs is the event type that impacts the frequent flyer miles resource.

• PIN_FLD_SESSION_OBJ is the retrieving contributor. Therefore, a separate balance summary is retrieved for each unique GPRS session.

• PIN_FLD_SESSION_OBJ is the updating contributor. Therefore, separate sub-balances are created or updated for each unique GPRS session.

The contributors can be a specific field or an asterisk (*) to indicate any contributor. For example, the following entry retrieves and tracks dollars (resource type 840) in a single sub-balance for all events with any contributor:

840:/event:*:*

To configure several sub-balances for one resource type, leave subsequent resource fields empty. If no resource is specified, the previous resource specified is used. For example, the next two configurations use the same resource (100002):

100002 : /event/session/telco/gsm : PIN_FLD_SESSION_OBJ : PIN_FLD_SESSION_OBJ
       : /event/session/dialup : PIN_FLD_SERVICE_OBJ : PIN_FLD_SERVICE_OBJ

Running the load_pin_sub_bal_contributor Utility

Note:

When you run the load_pin_sub_bal_contributor utility, it replaces the existing sub-balance configurations. If you are updating a set of sub-balance configurations, you cannot load new configurations only. You load complete sets of sub-balance configurations each time you run the load_pin_sub_bal_contributor utility.

Note:

The resources specified in the pin_sub_bal_contributor file must exist in the BRM database before the load_pin_sub_bal_contributor utility is run. Therefore, you must first load the pin_beid file by running the load_pin_beid utility. See "load_pin_beid".

Use the following command to run the load_pin_sub_bal_contributor utility:

load_pin_sub_bal_contributor pin_sub_bal_contributor

If you are not in the same directory as the pin_sub_bal_contributor file, include the complete path to the file. For example:

load_pin_sub_bal_contributor BRM_Home/sys/data/pricing/example/pin_sub_bal_contributor

For more information, see "load_pin_sub_bal_contributor".

To verify that the sub-balance configurations loaded correctly, display the /config/sub_bal_contributor object by using Object Browser, or use the robj command with the testnap utility.

Sub-Balance Configuration Example

The following examples show how sub-balances can be configured for various business needs.

Sub-Balances per Service Example

There are two ways to track resources per service instance:

• By creating a balance group for the service. See "Tracking Resources by Service".

• By specifying the service object as a contributor in the pin_sub_bal_contributor file.

Table 15-1 shows contributor configurations to track resources for GSM services. The resources are dollars and free minutes.

Table 15-1 Contributor Configurations

Resource	Event Type	Retrieving Contributor	Updating Contributor
Dollars	/event/session/gsm	PIN_FLD_SERVICE_OBJ	PIN_FLD_SERVICE_OBJ
Free minutes	/event/session/gsm	PIN_FLD_SERVICE_OBJ	PIN_FLD_SERVICE_OBJ
Free minutes	/event/cycle_forward	PIN_FLD_SERVICE_OBJ	PIN_FLD_SERVICE_OBJ
Free minutes	/event/cycle_forward	PIN_FLD_SERVICE_OBJ	PIN_FLD_SERVICE_OBJ

Each line in the above example specifies a configuration.

• Dollars is a currency sub-balance that is created in the account balance group.

• /event/session/gsm is the event type that will impact the dollars resource.

• PIN_FLD_SERVICE_OBJ is the retrieving contributor, so the dollars resource for each unique GSM service is summed when retrieving balance information.

  If you specify an asterisk instead of PIN_FLD_SERVICE_OBJ for the retrieving contributor, dollars for all GSM services owned by the account would be summed when retrieving balance information.

• PIN_FLD_SERVICE_OBJ is the updating contributor, so a separate sub-balance is created to track dollars for every unique GSM service that the account owns, such as telephony, fax, and SMS.

• Free minutes is a noncurrency sub-balance that is created in the account balance group.

• /event/session/gsm is the event type that will impact the free minutes resource.

• PIN_FLD_SERVICE_OBJ is the retrieving contributor, so the free minutes resource for each unique GSM service is summed when retrieving balance information.

  If you specify an asterisk instead of PIN_FLD_SERVICE_OBJ for the retrieving contributor, free minutes for all GSM services owned by the account would be summed when retrieving balance information.

• PIN_FLD_SERVICE_OBJ is the updating contributor, so a separate sub-balance is created to track free minutes for every unique GSM service that includes free minutes. Additional free minutes and consumption of free minutes are restricted to the GSM service instance.

  If you specify an asterisk instead of PIN_FLD_SERVICE_OBJ as the updating contributor, free minutes granted by every GSM service owned by the account would be shared by all the GSM services.

• Free minutes is a noncurrency sub-balance that is created in the account balance group.

• /event/cycle_forward is the event type that will impact the free minutes resource.

• PIN_FLD_SERVICE_OBJ is the retrieving contributor, so free minutes granted by cycle forward events are summed for each unique service when retrieving balance information.

• PIN_FLD_SERVICE_OBJ is the updating contributor, so a separate sub-balance is created to track free minutes granted by cycle forward events for each unique service that grants free minutes. Consumption of free minutes granted at the beginning of the cycle is restricted to the service that granted them.

Specifying the Order in Which Resource Sub-Balances Are Consumed

Customers are sometimes granted multiple sub-balances of a particular resource, such as minutes. For example, a customer's balance might include minutes granted at the start of the accounting cycle and rollover minutes from the previous month. Because the minutes have different validity periods, they are grouped into different resource sub-balances. See "About Noncurrency Sub-Balances".

When the customer uses a service, BRM needs to know which minutes (or sub-balance) to use first. You use resource consumption rules to specify the order in which resource sub-balances are consumed, according to the validity start time and end time.

For example, to use rollover minutes first, you configure BRM to consume sub-balances based on the earliest validity start time. To use the minutes that expire first, you configure BRM to consume sub-balances based on the earliest validity end time.

Consumption rule descriptions

BRM supports the resource consumption rules shown in Table 15-2:

Table 15-2 Supported Consumption Rules

Consumption Rule	Description
Earliest start time (EST)	Consume the sub-balance with the earliest validity start time first.
Latest start time (LST)	Consume the sub-balance with the latest validity start time first.
Earliest expiration time (EET)	Consume the sub-balance with the earliest validity end time first.
Latest expiration time (LET)	Consume the sub-balance with the latest validity end time first.
Earliest start time and latest expiration time (ESTLET)	Consume the sub-balance with the earliest validity start time first. If multiple sub-balances have the same start time, use the one with the latest end time first.
Earliest start time and earliest expiration time (ESTEET)	Consume the sub-balance with the earliest validity start time first. If multiple sub-balances have the same start time, use the one with the earliest validity end time first.
Latest start time and earliest expiration time (LSTEET)	Consume the sub-balance with the latest validity start time first. If multiple sub-balances have the same validity start time, use the one with the earliest validity end time first.
Latest start time and latest expiration time (LSTLET)	Consume the sub-balance with the latest validity start time first. If multiple sub-balances have the same validity start time, use the one with the latest validity end time first.
Earliest expiration time and earliest start time (EETEST)	Consume the sub-balance with the earliest validity end time first. If multiple sub-balances have the same validity end time, use the one with the earliest validity start time first.
Earliest expiration time and latest start time (EETLST)	Consume the sub-balance with the earliest validity end time first. If multiple sub-balances have the same validity end time, use the one with the latest validity start time first.
Latest expiration time and earliest start time (LETEST)	Consume the sub-balance with the latest validity end time first. If multiple sub-balances have the same validity end time, use the one with the earliest validity start time first.
Latest expiration time and latest start time (LETLST)	Consume the sub-balance with the latest validity end time first. If multiple sub-balances have the same validity end time, use the one with the latest validity start time first.

For example, if a customer's balance includes the following minutes and the customer makes a phone call on February 10, the consumption rules specify which group of minutes are impacted first:

• 100 Anytime Minutes with a validity period of February 1 to February 28.
• 50 rollover Anytime Minutes with a validity period of January 1 to February 28.
• 200 bonus Anytime Minutes with a validity period of January 15 to June 15.

If the consumption rule is set to earliest start time (EST), BRM applies the balance impact to the 50 rollover Anytime Minutes first. Likewise, if the rule is set to earliest expiration time and latest start time (EETLST), BRM applies the balance impact to the 100 Anytime Minutes first.

You specify the order in which resource sub-balances are consumed in your price plans. You can also set systemwide and default resource settings. BRM reads and uses the consumption rule settings in the order shown below:

1. Loan consumption rules. If a loan sub-balance is present, it will be consumed first. If there are multiple loan sub-balances, they are consumed according to the existing consumption rules.
2. Price plan setting. Your price plans can include resource-to-consumption rule mappings for each service that you support. This enables you to have different consumption rules for the same resource based on the plans owned by the customer. When a customer purchases a plan, the plan's resource-to-consumption rule mapping is stored in the customer's /balance_group object. If there are any conflicting rules for the same resource, BRM uses the rule from the most recently purchased plan.
3. Systemwide resource setting. You can specify a systemwide resource-to-consumption rule mapping for each service that you support. BRM uses the systemwide settings only if a rule is not defined for the resource in the customer's purchased plans. BRM stores systemwide settings in the /config/beid object.
4. Default resource setting. You can specify a default setting that applies to all resources. This setting is used only if a consumption rule is not defined for the resource in the customer's purchased plans or if there is not a systemwide resource setting. BRM stores the default resource setting in the /config/business_params object.

How BRM Applies Consumption Rules

To apply resource consumption rules, BRM automatically orders an account's resource sub-balances whenever the account adds or changes a resource. For example, if you modify a resource with a consumption rule of EET, BRM orders the resource sub-balances based on the validity end time, starting with the earliest expiration time first. When the account has a balance impact, BRM searches through the account sub-balances, in order, and applies the balance impact to the first sub-balance that matches the following criteria:

• Has a validity period that matches the event's time stamp.

• Has a balance to consume.

If there is any remaining balance impact, BRM applies it to the next sub-balance that matches the criteria. This process continues until all of the sub-balances have been depleted. BRM then restarts the search from the beginning and applies any remaining balance impact to the first sub-balance that matches the validity period.

For example, assume that an account with the following resource sub-balances makes a 30-minute phone call on June 4. If the consumption rule is set to LSTEET, BRM first consumes the 5 minutes from sub-balance A and then consumes the 10 minutes from sub-balance C. Because the account's sub-balances have been depleted, BRM charges the remaining 15 minutes to sub-balance A.

• Sub-balance A has a balance of 5 minutes with a validity period of June 1 to June 15.

• Sub-balance B has a balance of 0 minutes with a validity period of June 1 to June 30.

• Sub-balance C has a balance of 10 minutes with a validity period of May 1 to July 15.

• Sub-balance D has a balance of 0 minutes with a validity period of January 1 to December 30.

The method BRM uses to implement resource consumption rules is different for batch rating and real-time rating.

How Batch Rating Applies Consumption Rules

In batch rating, resource consumption rules are applied by the DAT_BalanceBatch module. The DAT_BalanceBatch module orders resource sub-balances when Pipeline Manager starts and when an account adds or modifies a resource. When processing CDRs, FCT_ApplyBalance uses the DAT_BalanceBatch module to search through an account's resource sub-balances, in order, and find the first sub-balance that matches the CDR time stamp and has a balance to consume.

By default, Pipeline Manager supports all of your price plan, systemwide, and default consumption rule settings. However, you can configure Pipeline Manager to use the default setting only by using the UseFlexibleConsumptionRule registry entry in the DAT_BalanceBatch module:

• True: Uses the consumption rules defined for each resource in a balance group. If a consumption rule is not defined, it uses the rules defined in the /config/beid object. If a consumption rule is not defined in a balance group or in the /config/beid object, the module uses the rule defined in the multi_bal instance of the /config/business_params object.

• False: Uses the systemwide consumption rule defined in the multi_bal instance of the /config/business_params object only.

How Real-Time Rating Applies Consumption Rules

In real-time rating, consumption rules are applied by the Balance FM opcodes. When an account is created or modified, the Balance FM opcodes read the consumption rule for each resource and order the resource sub-balances appropriately. When a customer has a balance impact, the Balance FM opcodes search through the customer's resource sub-balances, in order, and apply the balance impact to the first sub-balance that matches the event time stamp and has a balance to consume.

Setting Resource Consumption Rules

To assign resource consumption rules, perform one or more of these tasks:

• Setting Consumption Rules in Your Price Plans

• Setting Systemwide Consumption Rules for Each Resource

• Setting the Default Consumption Rule

For information about changing your consumption rule settings, see "Modifying Resource Consumption Rules".

Setting Consumption Rules in Your Price Plans

You set resource consumption rules in your price plans by using Pricing Center. See the Pricing Center Help for more information.

Note:

You can also use the "loadpricelist" utility to assign resource consumption rules in your price plans. You specify the rules in the price_list.xml file's consumption_rule field and then load the file into the database by using the loadpricelist utility. See "Using the XML Pricing Interface to Create a Price List".

Pricing Center and loadpricelist store your price lists and consumption rule settings in /plan objects in the BRM database. When a customer purchases a product, the plan's resource-to-consumption rule mapping is stored in the customer's /balance_group object.

If you use a custom client application to create price lists, you must modify your application to pass consumption rule settings to the Pricing FM opcodes. For more information, see "Customizing Credit Limits and Resource Consumption Rules" in BRM Opcode Guide.

Setting Systemwide Consumption Rules for Each Resource

You define systemwide consumption rules for each resource that you support by using Resource Editor. See the Resource Editor Help for more information.

Note:

You can also use the pin_beid configuration file to assign systemwide resource consumption rules. You specify the rules in the file's con_rule_id column and then load the file into the database by using the load_pin_beid utility. See "load_pin_beid" for more information.

Resource Editor and load_pin_beid store the systemwide consumption rule setting for each resource in the /config/beid object.

Setting the Default Consumption Rule

The default consumption rule applies to all resources in your system. The default setting is earliest start time and earliest expiration time (ESTEET). You can change this setting by modifying a field in the multi_bal instance of the /config/business_params object created during BRM installation.

You modify the /config/business_params object by using the pin_bus_params utility.

To set the default resource consumption rule:

1. Use the following command to create an editable XML file for the multi_bal class:

   pin_bus_params -r BusParamsMultiBal bus_params_multi_bal.xml 
   

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

2. Search the XML file for following line:

   <SortValidityBy>ESTEET</SortValidityBy>
   

3. Change ESTEET to the appropriate value:

   • Earliest start time (EST)

   • Latest start time (LST)

   • Earliest expiration time (EET)

   • Latest expiration time (LET)

   • Earliest start time and latest expiration time (ESTLET)

   • Earliest start time and earliest expiration time (ESTEET)

   • Latest start time and earliest expiration time (LSTEET)

   • Latest start time and latest expiration time (LSTLET)

   • Earliest expiration time and earliest start time (EETEST)

   • Earliest expiration time and latest start time (EETLST)

   • Latest expiration time and earliest start time (LETEST)

   • Latest expiration time and latest start time (LETLST)

   For a description of each setting, see "Consumption rule descriptions".

   Note:

   BRM uses the XML in this file to overwrite the existing multi_bal 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 billing configuration.

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

   pin_bus_params bus_params_multi_bal.xml
   

   You should run this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility.

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

6. Stop and restart the Connection Manager (CM).

Modifying Resource Consumption Rules

You can modify the resource consumption rules that you set in your price plans, in your /config/beid object, and in your /config/business_params object at any time. However, the new and changed settings apply to new customers only. Your existing customers will continue to use the previous settings:

• Changes to plan-level consumption rules do not trigger any update to existing customers that own the changed plan. Existing plan owners continue to use the plan's previous settings.

• Changes to the /config/beid object do not trigger changes to existing customers. Existing customers continue to use the previous systemwide settings.

• Changes to the /config/business_params object do not trigger changes to existing customers. Existing customers continue to use the previous default setting.

  Note:

  Pipeline Manager cannot use the new or modified /config/beid or /config/business_params consumption rule settings until they are loaded into pipeline memory. See "Reloading Data into a Pipeline Manager Module".

About Rollovers

Use the rollover feature to specify the quantity of unused resources that can be rolled over into subsequent cycles.

For example, you can configure a product so that a portion of unused free minutes from each cycle can be rolled over for use in the following cycle or cycles.

Note:

Rollover resources are distinct from resources issued through one-time grants, such as those issued by a CSR or a discount product. One-time grants are valid between two specific dates.

You set up rollovers in a product's event map in Pricing Center.

By default, rollover events are included in the pin_event_map file.

About Rollover Resource Sub-Balances

BRM maintains each rollover resource as a sub-balance. Each sub-balance specifies a resource balance that is valid (available for use) between valid-from and valid-to dates stored in BRM. The total amount of a resource available to a customer for each cycle is equal to the sum of all resource sub-balances that are valid during the cycle.

BRM validates whether a sub-balance can be rolled over by checking the rules that govern rollover (such as the amount to roll over, the maximum rollover amount allowed, the maximum number of cycles to roll over, and so on).

When a rollover event occurs, one of three things happens to the balance in a currently valid resource sub-balance:

• If the full amount is eligible for rollover, BRM does one of the following:

  • Creates a new rollover sub-balance for the rolled over amount. The rollover sub-balance validity period has the same valid-from date as the original sub-balance, and its valid-to date is extended to the end of the new cycle.

  • Adds the rolled over amount to an existing sub-balance if the existing sub-balance has the same data as would the new rollover sub-balance (such as the resource type, rollover rules, valid-from and valid-to dates, sub-balance contributors, and so on).

• If only a portion of the resources is eligible for rollover, the amount in the sub-balance is divided into a non-rollover sub-balance and a rollover sub-balance. The non-rollover sub-balance has the same valid-to date as the original sub-balance. Its resource balance is used for late-arriving usage events. The valid-to date for the rollover sub-balance is extended to the end of the new cycle. Its resources are available for the customer to use in the new cycle.

• If none of the resource is eligible for rollover, the sub-balance is not changed. This condition occurs when the sub-balance has already been rolled over the maximum number of times allowed. Amounts in this sub-balance are available only for late-arriving usage events.

  Note:

  Your system's memory limits might limit the number of months you can roll over a sub-balance. The number of resource sub-balances that BRM must maintain varies according to the number of rollover cycles allowed. You set the maximum allowed rollover cycles when configuring the rollover balance impact in Pricing Center.

CSRs can view rollover resource balances by using Customer Center.

When Rollover Events Occur

Resource sub-balances can be rolled over to another cycle as soon as they surpass the valid-to date (expire). Most resource sub-balances expire on the account's billing day of month (DOM). However, some sub-balances may expire in the middle of a cycle due to a product or service cancellation or due to flexible cycles.

Because many BRM features depend on sub-balances being rolled over the day after they expire, BRM rolls over resources at the following times:

• At the end of the billing cycle: BRM automatically rolls over all eligible resource sub-balances to the next cycle as part of the billing process. This catches all resource sub-balances that expire on the account's billing DOM.

• When you run the pin_bill_day script: The pin_bill_day script automatically runs the pin_rollover utility as part of the billing process. The pin_rollover utility rolls over any resource sub-balances that have expired but have not been rolled over to the next cycle. This catches any resource sub-balances that expire in the middle of the cycle.

Deleting Expired Sub-Balances

To delete expired sub-balances, use the pin_sub_balance_cleanup utility.

Rollover Example

The following example demonstrates:

• Granting resources (free minutes) at the start of each cycle (calendar month).

• Rolling over unused free minutes from previous months at the start of each month.

  Note:

  For information about rolling over resources that expire in the middle of a cycle, see "About Rolling Over Resources That Expire in Midcycle".

• Dividing an initial resource grant into rollover and non-rollover sub-balances.

• Limiting the total number of free minutes that can be rolled over from previous months.

• Dividing a rollover balance into rollover and non-rollover sub-balances when the Maximum Cumulative Rollover Total value is reached.

• The default order in which free minutes are consumed from the valid resource sub-balances.

• Expiration of free minutes in a sub-balance when the sub-balance has been rolled over the number of cycles specified by the Maximum Number of Rollover Cycles value.

In this example, the customer's product includes:

• 500 free minutes granted at the beginning of each usage cycle.

• A rollover specifying that:

  • Up to 100 unused free minutes from each month can be rolled over.

  • The maximum number of rollover cycles is 2.

  • A limit of 150 total rollover minutes from previous months can be rolled over into a new month.

Other assumptions:

• Cycles are monthly and start on the first day of each calendar month.

• The product with the rollover is valid starting January 1.

• The customer consumes no free minutes until March.

  Note:

  In this example:

  • New sub-balances, or those that have a change in their validity period, are highlighted in gray.

  • New grant resource values or changes to current resource amounts within the sub-balances are in bold black.

  • Components of available resource totals are in blue.

  • Components of used resource totals are in red.

1. On January 1, the customer is granted 500 free minutes for use during January as shown in Figure 15-1. The free minutes are maintained in a resource sub-balance.

   Figure 15-1 Initial 500 Free Minutes Grant in January

   
   Description of "Figure 15-1 Initial 500 Free Minutes Grant in January"

2. On February 1:

   • The cycle forward event creates a new resource sub-balance to track the grant of 500 free minutes for use during February as shown in Figure 15-2.

     Figure 15-2 February Free Minutes Grant

     
     Description of "Figure 15-2 February Free Minutes Grant"

   • The cycle rollover event creates a new resource sub-balance for tracking unused January free minutes that roll over into February. 100 minutes are put in the new sub-balance, and they are valid until March 1. The original sub-balance for January is decremented 100 minutes, leaving 400 minutes available for late-arriving January events as shown in Figure 15-3.

     Figure 15-3 January Free Minutes Rollover

     
     Description of "Figure 15-3 January Free Minutes Rollover"

     The customer now has 600 free minutes (500 granted February 1 plus 100 rolled over from January) available for use during February as shown in Figure 15-4.

     Figure 15-4 February Total Free Minutes Available

     
     Description of "Figure 15-4 February Total Free Minutes Available"

3. On March 1:

   • The cycle forward event creates a new resource sub-balance to track the grant of 500 free minutes for use during March as shown in Figure 15-5.

     Figure 15-5 March Free Minutes Grant

     
     Description of "Figure 15-5 March Free Minutes Grant"

   • The cycle rollover event creates a new resource sub-balance for tracking unused February free minutes that roll over into March as shown in Figure 15-6. 100 minutes are put in the new sub-balance, and they are valid until April 1. The original sub-balance for February is decremented by 100 minutes, leaving 400 minutes available for late-arriving February events.

     Figure 15-6 February Free Minutes Rollover

     
     Description of "Figure 15-6 February Free Minutes Rollover"

   • The cycle rollover event divides the January rollover minutes into two sub-balances to enforce the rule that only 150 total rollover minutes for a resource can carry forward into a new month. Because 100 free February minutes are already rolled over, only 50 minutes can be rolled over from the January rollover sub-balance for use in March.

     One new sub-balance contains 50 minutes available for use for late-arriving February and January events. The other contains 50 rollover minutes that the customer can use in March. The resource balances for each month are shown in Figure 15-7.

     Figure 15-7 Remaining January Free Minutes Rollover

     
     Description of "Figure 15-7 Remaining January Free Minutes Rollover"

     The customer now has 650 free minutes (500 granted March 1 plus 100 rolled over from February plus 50 rolled over from January) available for use during March as shown in Figure 15-8.

     Figure 15-8 March Total Free Minutes Available

     
     Description of "Figure 15-8 March Total Free Minutes Available"

4. During March, the customer consumes 620 minutes as shown in Figure 15-9. Sub-balance resources are used starting with the newest sub-balance, as indicated by the sub-balance valid-from dates:

   • All 500 free minutes from the March grant are consumed, leaving a zero balance.

   • All 100 February rollover minutes are consumed, leaving a zero balance.

   • 20 of the 50 January rollover minutes are consumed, leaving 30.

     Figure 15-9 March Free Minutes Usage

     
     Description of "Figure 15-9 March Free Minutes Usage"

5. On April 1, the cycle forward event creates a new resource sub-balance to track the grant of 500 free minutes for use during April as shown in Figure 15-10.

   No free minutes roll over into April from the March and February rollovers because these resources were consumed in March. The 30 free minutes remaining from the January rollover are not rolled over into April because the maximum number of cycles a grant can be rolled over is set to 2.

   Figure 15-10 April Free Minutes Grant

   
   Description of "Figure 15-10 April Free Minutes Grant"

   The customer has only 500 free minutes available for April.

Note:

• Rollover sub-balances are not truncated or prorated when the corresponding product is canceled.

• If two products contributing to the same balance group have rollover rateplans configured for the same resource with the same rollover frequency, either of the products can be used to roll over the resources. In this case, rollover results may vary depending on the product that is selected first.

About Rolling Over Resources That Expire in Midcycle

A resource balance can expire in the middle of a cycle: for example, when the resource is valid for only minutes, hours, or days or when the resource is valid for one or more months and starts in the middle of a month.

If a resource's validity period does not end when the cycle ends, the rollover sub-balance is valid for the entire cycle in which the resource is granted and for the whole of the next cycle.

In Figure 15-11, a monthly cycle event grants 60 free minutes that are valid for two weeks from the grant date. The free minutes are granted on January 1. On January 14, when the balance of free minutes expires, any remaining resources that can be rolled over are added to a new sub-balance, which is valid from January 1 to March 1:

Figure 15-11 Grant and Rollover Balance Date Validity Example 1

Description of "Figure 15-11 Grant and Rollover Balance Date Validity Example 1"

The same rollover period applies when the validity period of the free minutes ends after the cycle in which they are granted. In Figure 15-12, a monthly cycle event grants 300 free minutes that are valid for six weeks from the grant date. The free minutes are granted on January 1. On February 11, when the balance expires, any remaining resources that can be rolled over are added to a new sub-balance, which is valid from January 1 to March 1:

If the resource's validity period does not start at the beginning of the last cycle, the resources are rolled over for one entire cycle.

Figure 15-12 Grant and Rollover Balance Date Validity Example 2

Description of "Figure 15-12 Grant and Rollover Balance Date Validity Example 2"

Prorating Rollover Resources

Customers typically purchase and cancel products at some point in the middle of a cycle. When you set up a rollover in Pricing Center, you can specify whether rollover resources are prorated for the first and last cycles based on the number of days in the cycles that the product is owned.

Table 15-3 describes the rollover proration options:

Table 15-3 Rollover Proration Options

Proration Option	Description
Rollover entire amount	Roll over the available monthly rollover resources.
No rollover	Do not roll over any available monthly rollover resources.
Prorate rollover amount	Calculate the rollover resources based on the percentage of the cycle that the customer owned the rollover.

If you choose to prorate the rollover amount, BRM uses the equation in Figure 15-13 to calculate the amount to rollover:

Figure 15-13 Calculation for Amount to Rollover

Description of "Figure 15-13 Calculation for Amount to Rollover"

where:

• ValidFrom is the validity period's starting date. For example, if the validity period is from March 15 to April 14, ValidFrom is March 15.

• ValidTo is the validity period's ending date. For example, if the validity period is from March 15 to April 14, ValidTo is April 14.

• DaysInCycle is the number of days in the current cycle. For example, if the validity period is from March 15 to April 14, DaysInCycle is 31.

• Rollover is the available monthly rollover resource, such as 100 minutes.

For example, suppose:

• A customer buys a product on January 15 that grants 500 free minutes of use during each cycle.

• A rollover is set up so that up to 200 unused free minutes roll over into the following cycle.

• The usage cycle is a calendar month.

• The customer does not use any minutes during the first cycle.

Table 15-4 describes how the rollover is handled, depending on the Purchase Mid-cycle Proration setting:

Table 15-4 Impact of Proration Options

Proration Option	Amount Rolled Over into February
Rollover entire amount	200 free minutes are rolled over from January into February. In February, the customer has 700 free minutes (200 rolled over plus the 500 free minutes February grant).
No rollover	No free minutes are rolled over from January into February. In February, the customer has only the February grant of 500 free minutes.
Prorate rollover amount	Approximately 110 free minutes are rolled over from January into February: (17/31) * 200 = 109.67 In February, the customer has about 610 free minutes (110 rolled over plus the 500 free minutes February grant).

A similar set of results applies to the last-month proration calculation specified in the Cancel Mid-cycle Proration setting.

About Rolling Over Free Resources during Plan Transition

When your customers transition from one plan to another, you can specify that free noncurrency resources be rolled over from one plan to another if both plans belong together to at least one plan list.

For more information on plan transitions, see "Transitioning between Plans".

To specify free resources rollover between plans during plan transition, you must perform these tasks:

• If you use a custom application for customer management, provide the trigger for controlled rollover in the input flist to the PCM_OP_SUBSCRIPTION_TRANSITION_PLAN opcode.

• When you create your plan lists, ensure that plans between which you want to allow rollovers are in at least one plan list together.

  For more information, see "About Plan Lists".

These general rules apply to controlled rollovers:

• Controlled rollovers are not affected by the product cycle rollover settings.

  For more information on cycle rollovers, see "About Rollovers".

• A controlled rollover does not count as a rollover and hence is not restricted to the maximum rollover quantity and the rollover units per period settings for the cycle rollover.

• The cycle grants of free resources that have been prorated during the plan transition are rolled over to the next plan.