24 Managing Sub-Balances

Learn how to manage sub-balances in Oracle Communications Billing and Revenue Management (BRM) product offerings.

Topics in this document:

• About Sub-Balances

• About Noncurrency Sub-Balances

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

• Restricting the Validity of Noncurrency Sub-Balances That Start on First Usage

• Configuring Custom Sub-Balances

• Specifying the Order in Which Sub-Balances Are Consumed

• Configuring Time-Stamp Rounding for Cycle Events

• Configuring Time-Stamp Rounding for Purchase Events

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. Figure 24-1 shows an account with two balance groups, one for each service. In the balance group for wireless minutes, there are balances with different expiration dates. Therefore, there are two sub-balances for wireless minutes.

Figure 24-1 Balance Group With Sub-balances

Description of "Figure 24-1 Balance Group With Sub-balances"

A currency sub-balance can store the balances for multiple services. For example, an account that owns two charge offers that cost $25.00 per offer 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 subscription renewal 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.

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

• The current amount of the sub-balance.
• 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 minutes for a phone call, the session object is specified. A separate sub-balance is kept for each unique contributor. .
• Rollover data such as the rollover period and the balance amount that is rolled over, if any. See "About Rollovers".
• The ID of the offer that granted the balance (referred to as the “grantor object.")

If the timestamp_rounding entry in the CM pin.conf file is enabled, the start time of the balances granted by cycle events is rounded to midnight. However, the start time of the balances granted by purchase events is not rounded to midnight.

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

About Noncurrency Sub-Balances

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

• Minutes

• Frequent flyer miles

• Loyalty points

• Number of emails or text messages

A noncurrency sub-balance can also keep track of the total balances 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 balance.

When granting a noncurrency balance, 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 "Configuring Custom Sub-Balances".

How Balances in Validity-Based Sub-Balances Are Updated

By default, BRM stores balances with the same validity periods in the same sub-balance, provided they are associated with the same balance group. BRM automatically creates a new sub-balance for balances with a unique validity period, if one does not already exist.

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

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

Note:

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

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

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

You can configure BRM to round time stamps to midnight for balances granted by cycle and purchase events. See the following:

• Configuring Time-Stamp Rounding for Cycle Events

• Configuring Time-Stamp Rounding for Purchase Events

For more information, see "Configuring Timestamp Rounding" in BRM Configuring and Running Billing.

Restricting the Validity of Noncurrency Sub-Balances That Start on First Usage

When a noncurrency balance is configured to start on first usage (when the customer first uses the service), BRM always creates a new sub-balance for that balance when it is granted. A new sub-balance is created for each balance even when a charge offer or discount offer grants multiple first-usage balances of the same type. A balance that has a first-usage start time will remain available for consumption for as long as the balance is not used.

Note:

If a balance is shared among accounts in a sharing group, the balance validity period is set when any account in the group first impacts the balance. Because the same balance is shared with all accounts in the group, the validity period of that balance applies to all accounts.

You can configure BRM to automatically restrict the validity period of granted noncurrency balances to end no later than the end time of the charge offer or discount offer that grants the balance. Restricting the balance end time to the offer's end time ensures that the balance cannot continue to be consumed after the offer expires.

Note:

When an offer is canceled, the validity period end time of balances granted by that charge offer or discount offer is set to the time of the cancellation.

To enable this feature, run the pin_bus_params utility to change the RestrictResourceValidityToOffer business parameter. See "pin_bus_params" in BRM Developer's Guide for more information.

To restrict balance validity end times to charge offer or discount offer end times:

1. Go to BRM_home/sys/data/config.

2. Create an XML file from the /config/business_params object:

   pin_bus_params -r BusParamsMultiBal bus_params_multi_bal.xml 
   

3. In the file, change FALSE to TRUE:

   <RestrictResourceValidityToOffer>TRUE</RestrictResourceValidityToOffer>
   

4. Save the file as bus_params_multi_bal.xml.

5. Load the XML file into the BRM database:

   pin_bus_params bus_params_multi_bal.xml
   

6. Stop and restart the CM.

7. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. See "pin_multidb" in BRM System Administrator's Guide for more information.

Configuring Custom Sub-Balances

As described in "About Sub-Balances", BRM automatically creates sub-balances when portions of the balance are valid at different times. You do not need to configure sub-balances based on validity times.

You can configure custom sub-balances to track balances based on other values. For example:

• Minutes per call session

• Frequent flyer miles per service instance

• Friends and family calls to specific locations

You configure custom sub-balances by editing and loading a configuration file.

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

• Balance element ID. This is the ID for the type of balance in the sub-balance, such as dollars or 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 from an object related to the charge, such as a service object or account object.

For example, you might configure a custom sub-balance to track balance impacts for:

• Dollars

• Charged by GPRS events

• Tracked by each GPRS session

Sub-balance contributors define how to track sub-balances. For example, if the contributor is a service object, sub-balances are tracked separately for each service instance.

Sub-balance contributors are specified by a field name from the event, or from an object related to the charge, such as a service object or account object. Some fields you might want to use as contributors include:

• The service object.

  Specify a service field to track sub-balances 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 balances. The other way is to create a balance group for the service when you create your packages in PDC.

• The session object.

  Specify a session field to track balances 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 charge offer object.

  When several charge offers in the same package have different rollover rules, tracking balances per charge offer permits BRM to update the minutes for each charge offer.

• The phone number field.

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

• The account object.

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

There are two types of contributors:

• Retrieving contributor. This is the field from which BRM retrieves the amount to add to the sub-balance. For example, if the retrieving contributor is the service for a GPRS event, a separate balance summary is retrieved from each unique GPRS service object.

  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. Whereas the retrieving contributor determines the balance amount to retrieve from a charge, the updating contributor specifies how to apply the amount to a sub-balance. For example, to add or deduct minutes for specific broadband sessions, specify the session object as the updating contributor.

Table 24-1 shows contributor configurations to track balances for GSM services; in this case, one sub-balance for dollars and one sub-balance for minutes.

Table 24-1 Contributor Configurations

Balance Element	Event Type	Retrieving Contributor	Updating Contributor
Dollars	/event/session/gsm	PIN_FLD_SERVICE_OBJ	PIN_FLD_SERVICE_OBJ
Minutes	/event/session/gsm	PIN_FLD_SERVICE_OBJ	PIN_FLD_SERVICE_OBJ

Each row in this example specifies a sub-balance:

• Dollars balance impact

  • 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 sub-balance.

  • PIN_FLD_SERVICE_OBJ is the retrieving contributor, so the dollars balance 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.

• Minutes balance impact

  • 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 minutes balance.

  • PIN_FLD_SERVICE_OBJ is the retrieving contributor, so the minutes balance 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, 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 minutes for every unique GSM service that includes minutes. Additional minutes and consumption of minutes are restricted to the GSM service instance.

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 balance consumption rules. See "Specifying the Order in Which 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 Custom Sub-Balances".

Defining and Loading Custom Sub-Balances

See "Configuring Custom Sub-Balances" for information.

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.

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:

balance_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 balance element ID for frequent flyer miles.

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

• 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 (balance element type 840) in a single sub-balance for all events with any contributor:

840:/event:*:*

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

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

After editing the file, you load it into the BRM database.

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.

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_contributors".

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.

Specifying the Order in Which Sub-Balances Are Consumed

In a balance group, balances for the same type of balance element are combined into a single balance. For example, an account that owns two charge offers that each include 300 minutes has a starting included minute balance of 600 minutes, providing the services are associated with the same balance group and have the same validity period for the included minutes.

When portions of a balance are valid at different times, however, BRM creates multiple sub-balances for that balance in the balance group. For example, a balance group might include 300 minutes that are valid only for the current billing cycle and 1000 minutes that never expire. Because the included minutes have different validity periods, they are tracked in different sub-balances.

When a customer uses a service, BRM must know which sub-balance to use first. To specify the order in which sub-balances are consumed, you use consumption rules. The rules are based on the start and end times of the sub-balances, for example consume the sub-balance with the earliest validity start time first.

For example, you can specify whether a subscriber with the following minute sub-balances uses the Anytime Minutes or the rollover Anytime Minutes first:

• 100 Anytime Minutes that are valid March 1 to April 30
• 50 rollover Anytime Minutes that are valid February 1 to March 30

If the minute balance is associated with a rule that says to consume the sub-balance that expires first, the 50 rollover Anytime Minutes are used first.

If the minute balance is associated with a rule that says to consume the sub-balance with the latest start time, the 100 Anytime Minutes are used first.

Table 24-2 lists the balance consumption rules that BRM supports.

Table 24-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.

As shown in Figure 24-2, you associate consumption rules with balances in packages.

Figure 24-2 Consumption Rules for Balance Groups

Description of "Figure 24-2 Consumption Rules for Balance Groups"

You can also set systemwide and default balance element 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. Package consumption rules. Your product offerings can include consumption rules for each service that you support, defined differently in each package. This enables you to have different consumption rules for the same balance based in the packages purchased by the customer. When a customer purchases a package, the package's balance element-to-consumption rule mapping is stored in the customer's /balance_group object. If there are any conflicting rules for the same balance element, BRM uses the rule from the most recently purchased package.
3. Systemwide service consumption rules. You can specify a systemwide consumption rule for each service that you support. BRM uses the systemwide settings only if a rule is not defined for the balance element in the customer's purchased packages. BRM stores systemwide settings in the /config/beid object.

   You define systemwide consumption rules for each balance element that you support by using the pin_beid file and load_pin_beid utility. See "load_pin_beid" in BRM Configuring Pipeline Rating and Discounting for more information.

4. Default consumption rule. You can specify a default consumption rule that applies to all balance elements. This setting is used only if a consumption rule is not defined for the balance element in the customer's purchased packages or if there is not a systemwide service rule. BRM stores the default balance element setting in the /config/business_params object.

   You define the default consumption rule in the /config/business_params object. See "Setting the Default Consumption Rule" for more information.

Setting the Default Consumption Rule

The default consumption rule applies to all balance elements in your system. The default setting is earliest start time and earliest expiration time (ESTEET). You can change this setting by running the pin_bus_params utility to change the SortValidityBy business parameter. See "pin_bus_params" in BRM Developer's Guide for more information.

To set the default balance element consumption rule:

1. Go to BRM_home/sys/data/config.

2. Create an XML file from the /config/business_params object:

   pin_bus_params -r BusParamsMultiBal bus_params_multi_bal.xml 
   

3. In the file, change ESTEET to one of the values listed in Table 24-2:

   <SortValidityBy>ESTEET</SortValidityBy>
   

4. Save the file as bus_params_multi_bal.xml.

5. Load the XML file into the BRM database:

   pin_bus_params bus_params_multi_bal.xml
   

6. Stop and restart the CM.

7. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. See "pin_multidb" in BRM System Administrator's Guide for more information.

Configuring the Default Consumption Rule in ECE

When ECE receives a usage request for which no consumption rules are configured, ECE applies its own systemwide default consumption rule for processing the usage request.

To configure the default consumption rule in ECE:

1. Access the ECE configuration MBeans:

   1. Log on to the driver machine.

   2. Start the ECE charging servers (if they are not started).

   3. Connect to the ECE charging server node enabled for JMX management.

      This is the charging server node set to start CohMgt = true in the ECE_home/oceceserver/config/eceTopology.conf file.

   4. Start a JMX editor that enables you to edit MBean attributes, such as JConsole.

   5. In the editor's MBean hierarchy, find the ECE configuration MBeans.

2. Expand the ECE Configuration node.

3. Expand charging.server.

4. Expand Attributes.

5. Set the systemConsumptionRule attribute to one of the following systemwide consumption rules:

   • EARLIEST_START

   • LATEST_START

   • EARLIEST_EXPIRATION

   • LATEST_EXPIRATION

   • EARLIEST_START_LATEST_EXPIRATION

   • EARLIEST_START_EARLIEST_EXPIRATION

   • LATEST_START_LATEST_EXPIRATION

   • LATEST_START_EARLIEST_EXPIRATION

   • EARLIEST_EXPIRATION_EARLIEST_START

   • EARLIEST_EXPIRATION_LATEST_START

   • LATEST_EXPIRATION_EARLIEST_START

   • LATEST_EXPIRATION_LATEST_START

   • NONE: When the attribute is set to NONE, the default consumption rule is not configured, and the order for consuming balances is undefined.

   By default, this attribute is set to EARLIEST_START_EARLIEST_EXPIRATION.

6. Save your changes.

Deleting Expired Sub-Balances

To delete expired sub-balances, use the pin_sub_balance_cleanup utility. See "pin_sub_balance_cleanup" in BRM System Administrator's Guide.

Configuring Time-Stamp Rounding for Cycle Events

You can configure BRM to round time stamps to midnight for balances granted by cycle events. For more information, see "Configuring Timestamp Rounding" in BRM Configuring and Running Billing.

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.

Note:

When a charge offer'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 end time stamp is rounded for the purpose of calculating the scale to determine the cycle fee amount to charge.

Configuring Time-Stamp Rounding for Purchase Events

You can configure BRM to round time stamps to midnight for balances granted by purchase events. For more information, see "Configuring Timestamp Rounding" in BRM Configuring and Running Billing.

To enable this feature, run the pin_bus_params utility to change the TimestampRoundingForPurchaseGrant business parameter. See "pin_bus_params" in BRM Developer's Guide for more information.

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 BRM_home/sys/data/config.

5. Create an XML file from the /config/business_params object:

   pin_bus_params -r BusParamsRating bus_params_rating.xml 
   

6. In the file, change disabled to enabled:

   <TimestampRoundingForPurchaseGrant>enabled</TimestampRoundingForPurchaseGrant>
   

7. Save the file as bus_params_rating.xml.

8. Load the XML file into the BRM database:

   pin_bus_params bus_params_rating.xml
   

9. Stop and restart the CM.

10. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. See "pin_multidb" in BRM System Administrator's Guide for more information.