3 Setting Up Price List Data
This chapter describes how to set up the Oracle Communications Billing and Revenue Management (BRM) price list data. This data is used by both real-time rating and pipeline batch rating.
Before reading this chapter, read "About Creating a Price List".
About Configuring Price List Data
Before creating your price list, you must do the following tasks to configure price list data:
-
Create resources. See "Setting Up Resources".
-
Set up offer profiles. See "Setting Up Offer Profiles"
-
Create ratable usage metrics (RUMs). See "Setting Up Ratable Usage Metrics (RUMs)".
-
Map event types to RUMs. See "Mapping Event Types to RUMs".
-
Specify which events you must rate. See "Mapping Event Types to Services".
Setting Up Resources
For background information about resources, see "About Resources".
Real-time rate plans and pipeline rate plans each use a different set of resources. See the following topics:
-
Setting Up Pipeline Manager Resources
Important:
You must use the same resource names for real-time and batch pipeline resources.
Setting Up Resources for Real-Time Rating
Before you can create a price list, you must use the Resource Editor in Pricing Center to create resources. You can create currency and non-currency resources.
When you create resources, you define the following:
-
The resource name, such as US Dollars.
-
The resource ID, such as 840. Currency resource IDs are defined in an ISO standard.
-
The rounding value. For example, to round US dollars to cents, specify a rounding value of two places after the decimal point.
Note:
Resource Editor sets rounding only for A/R actions such as adjustments and refunds. To set rounding for rating, discounting, and taxation as well as A/R, configure rounding in the pin_beid file. See "About Resource Rounding". -
How to round additional numbers beyond the rounding value:
-
Up: For example, 10.151 rounds to 10.16.
-
Down: For example, 10.159 rounds to 10.15.
-
Nearest: If the additional digit is 0-4, the last significant digit remains the same. If the additional digit is 5-9, the last significant digit is rounded up. For example, 10.144 rounds to 10.14 and 10.145 rounds to 10.15.
-
Even: If the additional digit is 0-4, the last significant digit remains the same. If the additional digit is 6-9, the last significant digit is rounded up. If the additional digit is 5, the last significant digit is rounded to the nearest even digit. For example, if rounding is set to two significant digits, 10.155 rounds to 10.16 and 10.165 rounds to 10.16.
-
-
For currency resources, you also define the error tolerance and the abbreviations and symbols used for display, such as $.
-
The order in which to consume resource sub-balances. For example, if a customer's balance contains free minutes with different validity periods, you specify which minutes to use first, according to the starting validity date or ending validity date. See "Specifying the Order in Which Resource Sub-Balances Are Consumed".
Setting Up Pipeline Manager Resources
Pipeline Manager resource IDs must match real-time resource IDs. For example, when defining pipeline rate plans, you use BRM resource IDs, such as US Dollars (840). Pipeline Manager resources can be mapped to real-time resources. Pipeline Manager resources, which can be defined in a variety of ways, can be combined on the real-time side.
Defining Currencies
You must define all valid currencies before setting up currency resources.
You define Pipeline Manager currencies in Pricing Center.
You must also configure the DAT_Currency module. This module converts currency symbols to numeric values and retrieves resource rounding rules, using data from /config/beid objects in the BRM database.
Defining a Resource
Resources are arbitrary measurement values for which a separate charge can be calculated. You can define two types of resources: Money and Other. Money resources are based on a defined currency. Other resources are non-currency resources, such as duration or loyalty points.
You define Pipeline Manager resources in Pricing Center.
Defining Currency Exchange Rates
You must set up an exchange rate for each currency you support for rating. Exchange rates specify the rate for converting one currency into another.
Call details records (CDRs) can come from multiple networks in different countries, which use different currencies. When you use exchange rates, you can store up to three charge packets with different currencies in a single EDR. The currency types are:
-
Rating currency: The currency defined in the rate plan and price model.
-
Billing currency: The currency associated with a specific customer, network operator, and so forth for billing and invoicing.
-
Home currency: The Pipeline Manager systemwide currency.
You convert currencies from the rating currency to the billing currency, the home currency, or both.
You define exchange rates in Pricing Center. Each exchange rate includes the following data:
-
The currency to convert from.
-
The currency to convert to.
-
The conversion rate.
-
The date from which the conversion rate is valid.
To implement currency conversion, you configure the FCT_ExchangeRate module and the DAT_ExchangeRate module.
When you configure FCT_ExchangeRate, you specify the exchange rate conversion mode by setting the Mode entry to Normal or Reverse. In Normal mode, the exchange rate is the multiplier to convert the From Currency to the To Currency. In Reverse mode, the exchange rate is the multiplier to convert the From Currency to the To Currency and the divisor to convert the To Currency back to the From Currency.
For example, suppose the exchange rate to convert from EUR to USD is defined as 2.0. One pipeline converts EUR to USD with Mode set to Normal and the another pipeline converts USD to EUR with Mode set to Reverse. In Normal mode, the exchange rate 2.0 is the multiplier to convert from EUR to USD (EUR * 2.0 = USD). In Reverse mode, the exchange rate 2.0 is the divisor to convert from USD to EUR (USD / 2.0 = EUR). If Reverse mode was not used, you would define another exchange rate 0.50 to convert from USD to EUR.
To update conversion rates, you use the DAT_ExchangeRate module Reload semaphore. The new exchange rates overwrite the old rates.
About currency exchange validity dates
You can use the FCT_ExchangeRate module to configure how to define the validity date for currency conversion for two cases.
-
Use the RatingDateBilling registry entry to convert from the rating currency to the billing currency.
-
Use the RatingDateHome registry entry to convert from the rating currency to the home currency.
You can specify a different value for the conversion to the billing currency and the home currency. For example, the validity date for converting the rating currency to the billing currency is usually the system time. The validity date for converting the rating date to the home currency is usually the CDR date.
For both registry entries, the values are:
-
SYSTEM. The system time.
-
FILE. The time that the file that includes the CDR was created (the file header time stamp).
-
CDR. The time that the CDR was generated.
-
NONE. (default).
Note:
If you specify RatingDateBilling in addition to the RatingDateHome and HomeCurrency parameters, it converts the currency to the home currency only.
Mapping Pipeline Manager Currencies and Real-Time Rating Currencies
Currencies are stored as strings for Pipeline Manager and as numbers for real-time rating. You must map Pipeline Manager currency IDs to real-time rating currency names. To do so, you create a list of currencies in the FCT_BillingRecord module registry. See "About Consolidation for BRM Billing" in BRM Configuring Pipeline Rating and Discounting.
Setting Up Offer Profiles
Set up each offer profile in the following way:
-
Provide a unique name for the offer profile.
Important:
When setting up a product or a discount for an existing offer profile, use the offer profile name as the provision tag of the product or discount.Alternately, when you create an offer profile for an existing product or discount, use the provisioning tag of the product or discount as the name for the offer profile.
-
Configure a set of policy labels that define the currency or non-currency resource and the quality of service in rate tiers.
For example, you can define a policy label called Fair Usage for a non-currency resource (such as Megabytes Used, whose resource Id is 100009). Set profile status levels based on predefined quality of service. The gradation may be as follows:
-
Low QoS for usage between 0 and 2.5 Megabytes
-
Medium QoS for usage between 2.5 and 5 Megabytes
-
High QoS for usage above 5 Megabytes
Example 3-1 shows the contents of one sample policy label.
Example 3-1 Sample Policy Label
<policy_label> <label>Fair Usage</label> <resource_name>Megabytes Used</resource_name> <resource_id>100012</resource_id> <unit> 1 </unit> <tier> <tier_start_range>0</tier_start_range> <tier_end_range>2.5</tier_end_range> <status_label>High Qos</status_label> </tier> <tier> <tier_start_range>2.5</tier_start_range> <tier_end_range>5</tier_end_range> <status_label>Med Qos</status_label> </tier> <tier> <tier_start_range>5</tier_start_range> <status_label>Low Qos</status_label> </tier> </policy_label> -
About Resource Rounding
BRM enables you to create various rounding rules for different resources, events, and processes such as rating and discounting. You create rounding rules for several reasons:
-
To increase the accuracy of rating and discounting results.
-
To process usage fees more efficiently. For example, an infinite number such as 5.333... is more easily processed when it is rounded.
-
To round for various currencies that use a different number of digits to the right of the decimal (for example, 10.25 dollars and 10 yen).
-
To comply with currency conversion rules.
-
To bill customers an amount that they can actually pay.
You configure rounding by editing the pin_beid file and loading the contents of the file into the /config/beid object in the BRM database. For more information, see "Configuring Resource Rounding".
About Rounding Rules
You can configure resource rounding based on the following rounding criteria:
-
The rounding scale is the number of significant digits to the right of the decimal point. For example, a scale of 2 applied to 10.321111 rounds to 10.32.
-
The rounding mode defines whether the number is rounded up, down, or not at all, based on the value of the digit following the last significant digit. See "About Rounding Modes".
-
The process to which the rounding configuration applies. You can specify one of these processes: rating, discounting, taxation, and accounts receivable (A/R). A/R includes actions such as billing, payments, adjustments, cancellations, and G/L reporting.
Specifying the process enables you to round differently based on the operation. For example, you can round up using six decimal places for rating and round down using two decimal places for billing.
-
The event type to which the rounding configuration applies. This enables you to round differently for events that represent specific types of usage, cycle fees, discounts, and rollovers. For example, US dollars and purchase events (/event/purchase).
Table 3-1 show how a US dollars resource and purchase event combination can be rounded various ways for various processes:
Table 3-1 Currency Resource and Event Type
| For a US Dollars Resource | For This Process | Use This Rounding Scale | Use This Rounding Mode |
|---|---|---|---|
|
Event type = /event/billing/product/fee/purchase |
Rating |
6 |
Down |
|
Event type = /event/billing/product/fee/purchase |
Discounting |
6 |
Up |
|
Event type = /event/billing/product/fee/purchase |
A/R |
2 |
Nearest |
|
Event type = /event/billing/product/fee/purchase |
Taxation |
2 |
Nearest |
You can specify any combination of scale and mode for resource, event, and process combinations.
After each process that performs rounding (rating, discounting, and so forth), the balance impact of the event contains the rounded amount.
To configure rounding, you specify the rounding rules in the resource configuration file (BRM_Home/sys/data/pricing/example/pin_beid), and then you load the file by using the load_pin_beid utility. The pin_beid file contains default rounding rules that you can use. For more information, see "Configuring Resource Rounding".
Note:
To round non-currency aggregation counter balances for discounting purposes, use Pipeline Manager discount expressions. For more information, see "About Rounding Aggregation Counter Resources for Discounting".How BRM Applies Rounding
Rating, discounting, and taxation produce balance impacts, which are rounded and applied to the customer's account balance. The balance impacts are rounded to the scale and mode configured for the event, resource, and process combination.
Balance impacts for an account are stored in bill items, which are associated with the customer's bill. When you run billing, the item totals are rounded according to the A/R rounding rule. Item totals are rounded before being added to the bill so that the bill itself never needs rounding. Before billing, item totals are unrounded and their amounts reflect the scale configured for the associated events.
Figure 3-1 show the general process of balance impact rounding:
Both real-time rating and pipeline batch rating perform rounding. During pipeline rating, the pipeline rounds the amount in each charge and discount packet.
To round in a pipeline, you configure the Pipeline Manager rounding module. See "Setting Up Rounding in Pipeline Manager". To configure the rounding rules, see "Configuring Resource Rounding".
Assuming that rounding is configured for all events and all processes (rating, discounting, taxation, and A/R), rounding is performed in the following order:
-
Purchase and cycle fees. When a plan is purchased, the purchase and cycle fees are rounded, if necessary, and a balance impact is generated with the rounded amount. Purchase and cycle fees typically only need rounding when a user purchases or cancels a plan in the middle of the billing cycle. In this case, cycle fees and non-currency grant amounts are prorated, if necessary, and then rounded.
-
Usage fees. As customers use their services, the usage events are rated, the usage fees are rounded, and balance impacts are generated with the rounded amounts.
-
Discount fees. If a usage discount applies, the discount is calculated on the rounded usage fee, and then the discount is rounded and a discount balance impact is generated with the rounded amount. If there are multiple usage discounts, each discount is rounded in sequence.
-
Taxes. If tax should be applied to the event, the tax is calculated on the fee rounded from the previous stage, and then the tax is rounded and a balance impact is generated with the rounded amount.
-
Billing discounts. When you run billing, if a billing-time discount applies, it is applied to the total of the rounded usage items, and then the discount is rounded and a discount balance impact is generated with the rounded amount.
-
Bills. When the bill is generated, the total amount in each item is rounded, and then all item totals are summed and included in the bill.
-
Rollover. If there are any rollover amounts, the rollover is calculated on the total rounded usage, and then the rollover amount is rounded and applied to the next billing cycle. For example, if 100 minutes can be rolled over and the customer used 60.4 minutes, the unused amount of 39.6 minutes is rounded and then added to the account balance for the next cycle.
To round for rollover, you configure a rounding rule for the non-currency resource and cycle forward event combination. Rollover is typically rounded up.
About Rounding and A/R Actions
When entering amounts for A/R actions such as adjustments and refunds, customer service representatives (CSRs) typically use natural scale: that is, the scale commonly used in the marketplace for that resource. For example, a person who purchases a book using US dollars cannot make change smaller than one cent (.01 dollars), making 2 the natural scale for US dollars. However, if a CSR reverses or adjusts an event before billing, the scale used is the one in the event's balance impact. By default, this is the natural scale, unless you change this to use a scale other than natural.
About Rounding Billed and Unbilled Items
The balance impacts of events associated with items can have a high scale. Before billing, item totals reflect the scale of their associated events. During billing, item totals are rounded using the A/R rounding configuration so that customers' bills display the natural scale for the resource. However, the events associated with billed items still retain their pre-billing scale.
If any operation is performed on billed items: for example, event-level and item-level adjustments, BRM rounds the balance impact of the operation according to the A/R rounding rule to maintain G/L integrity. Because actions on billed items are rounded when they occur, only pending items are rounded when billing is run.
About Rounding for Specific Event Types
When you configure a rounding rule for a specific event type, such as cycle or session events, that rounding rule applies to those events only for the process specified. If you do not configure a rule for every process, all other processes for that event type use the default rounding rule defined in the pin_beid file. The default rounding rule specifies natural scale for all events and the rounding mode most commonly used for the process. A rule for all events is specified by using an asterisk (*) as the default event type.
For example, given the configuration in Table 3-2, during rating, session events are rounded down and have a scale of 6. During taxation, however, session events use the default rule of rounding to the nearest with a scale of 2:
About Rounding Aggregation Counter Resources for Discounting
For discount rounding, the rounding configurations in the pin_beid file are used to round only the balance impacts of discounting, not input balances such as aggregation counters. To round aggregation counter balances in a pipeline, you use pipeline discount expressions when you configure your discounts. To configure aggregation counter rounding, see "Configuring Rounding Rules for Aggregation Counter Resources".
About G/L Report Rounding
G/L report rounding uses the rounding rule configured for A/R actions. The rounded totals in G/L reports might differ slightly from the total of the rounded bills. This is because item totals are rounded for billing, and journal entries are rounded for G/L reports. Also, G/L reports are rounded differently before and after billing. For more information, see "About Rounding and G/L Reports" in BRM Collecting General Ledger Data.
If there is any difference between the rounded journal entries in G/L reports and the rounded bill items, BRM records the difference in the G/L. You configure a G/L ID for the rounding difference and configure BRM to record the differences. See "Configuring to Record Rounding Differences in the G/L".
About Rounding Modes
A rounding mode defines whether a number is rounded up, down, or not at all. The rounding mode rounds to the specified scale. For example, using a scale of 2, rounding up 10.2369 results in 10.24. If the scale is 3, rounding up results in 10.237.
The following rounding mode values that you can use in the pin_beid file are defined in the BRM_Home/include/pin_bill.h file:
-
0: PIN_BEID_ROUND_NEAREST
This mode rounds up or down depending on the value of the digit following the last significant digit. If the additional digit is 0-4, the last significant digit remains the same. If the additional digit is 5-9, the last significant digit is rounded up. For example, if the scale is 2, 10.144 rounds to 10.14 and 10.145 rounds to 10.15. This is the most common rounding method.
-
1: PIN_BEID_ROUND_UP
This mode rounds up when the digit following the last significant digit is greater than 0. For example, If the scale is 2, 10.151 rounds to 10.16. If the scale is 1, it rounds to 10.2.
-
2: PIN_BEID_ROUND_DOWN
This mode truncates all digits following the last significant digit. For example, if the scale is 2, 10.159 rounds to 10.15. If the scale is 1, it rounds to 10.1.
-
3: PIN_BEID_ROUND_EVEN
This mode rounds one of three ways depending on the value of the digit following the last significant digit:
-
If it is less than 5, truncate all digits following the last significant digit.
-
If it is greater than 5, round up.
-
If it is 5, round to the nearest even digit. For example, if the scale is 2, 10.155 and 10.165 both round to 10.16 because 6 is an even number.
-
-
4: PIN_BEID_ROUND_FLOOR
This mode rounds numbers toward a negative value (that is, the rounded number is always less than the unrounded number). This enables you to round balance impacts so that customers always benefit. For example, if the scale is 2, a credit to a customer of -7.999 is rounded to -8.00, and a debit of 7.999 is rounded to 7.99.
-
The following two modes perform the same rounding as their non-alternative counterparts (ROUND_FLOOR and ROUND_DOWN), except that they compensate for possible loss of precision when rounding down by first rounding with a mode of NEAREST using a scale that is two digits greater than the scale you configure.
-
5: PIN_BEID_ROUND_FLOOR_ALT
-
6: PIN_BEID_ROUND_DOWN_ALT
For more information, see "About Rounding Modes That Correct for Loss of Precision".
-
About Rounding Modes That Correct for Loss of Precision
Some calculations produce results that are slightly less than expected when a value is rounded down. For example, when BRM prorates a $60.00 cycle fee for 20 out of 30 active days, the calculation is (20/30) * $60.00. The expected result is a fee of $40.00. However, because 20/30 evaluates to 0.666..., when this is multiplied by 60 and rounded down, the actual result is a fee of $39.99.
BRM provides two alternative rounding modes that compensate for possible precision loss when rounding down: ROUND_DOWN_ALT and ROUND_FLOOR_ALT. These modes perform the same rounding as their non-alternative counterparts (ROUND_DOWN and ROUND_FLOOR) after first compensating for loss of precision.
Note:
ROUND_DOWN_ALT and ROUND_FLOOR_ALT are not supported in the BRM PCM Java API and in discount expressions.When these modes are used, if a decimal should be rounded down, BRM performs two rounding functions: The decimal is rounded by using the ROUND_NEAREST rounding mode and a scale that is two more than the scale that you request. It is then rounded down.
For example, if you configure the rounding mode as ROUND_DOWN_ALT and a rounding scale of 2, and the decimal to round is 7.999..., BRM truncates the infinite decimal to the system maximum and then rounds this decimal to the nearest using a scale of 4 (2 more than the configured scale of 2), which results in 8.0000. This decimal is then rounded down using the configured scale of 2, resulting in 8.00 as shown in Table 3-3:
Table 3-3 Rounding Modes That Correct for Precision
| Do This | Why |
|---|---|
|
7.999... |
Original decimal |
|
7.99999999999999 |
Truncated to the system max |
|
8.0000 |
ROUND_NEAREST, using requested scale + 2 |
|
8.00 |
ROUND_DOWN to the requested scale of 2 |
Had the original decimal of 7.999... not been rounded to the nearest first and only rounded down, the result would be 7.99.
To compensate for possible loss of precision, the alternative rounding modes consider two decimal places more than the non-alternative rounding modes. Therefore, the greatest amount that will be modified by using the alternative rounding modes, and still compensate for loss of precision, is less than the greatest amount that will be modified by using the non-alternative rounding modes.
When Rounding Is Not Applied
When the requested rounding scale is greater than the scale of the number being processed, rounding is not required. This occurs when:
-
You configure a rounding scale equal to or greater than the maximum number of digits allowed by the system. For example, if the system allows 15 digits and you set the rounding scale to 15 or greater, rounding has no effect.
-
You call a rounding function and request a scale that is equal to or greater than the current scale of the decimal: for example, when the decimal is 10.89766 and the scale requested is 5 or greater.
-
A computation or expression results in a decimal with a scale that is equal to or less than the configured or requested scale: for example, when a computation results in the decimal 1.98 and the configured scale is 2 or greater.
Configuring Resource Rounding
To set up rounding, perform the following tasks:
About Configuring Rounding Rules
You define rounding rules in the balance element ID (BEID) configuration file (BRM_Home/sys/data/pricing/example/pin_beid) and then run the load_pin_beid utility to load the contents of the file into the /config/beid object in the BRM database. See "Configuring Rounding Rules".
The pin_beid file contains default rounding rules based on the most commonly used rounding for the resource and operation. The default rules specify a configuration for all events by using an asterisk (*) as the default event type. For an explanation of the configuration syntax and fields, see the pin_beid file.
You configure rounding for resource and event type combinations (for example, US dollars and /event/session/telco/gsm events). For each resource and event combination, you specify a rounding scale, a rounding mode, and the process for which this rule applies. For the process, you specify one of these enumerated values in the pin_beid file:
-
Rating = 0
-
Discount = 1
-
Taxation = 2
-
A/R = 3
To configure an event and resource rule for every process, you add an entry for each process.
Important:
-
You do not need to configure rounding for all of the processes. However, you must configure rounding for every resource and event type that has a balance impact.
-
If you add resources that are not already in the pin_beid file, you should always include a default rounding configuration for that resource that applies to all event types. Any event type that is not explicitly specified for the resource uses this default rounding rule.
-
You can use a single asterisk (*) to denote a default value such as any event type. However, in combination with other characters, you must use valid regular expressions. For example, specifying /event/* is incorrect; specifying /event/(.)* is correct.
Tip:
You can use regular expressions in the rounding configurations. For example, /event/session/(.)* matches all session events.For more information, see "Configuring Rounding Rules".
Prioritizing Rounding Rules
BRM applies the first matching rounding rule in the /config/beid file. Therefore, if you have more than one rule that matches an event, resource, and process combination, add them in order of priority in the pin_beid file. For example, a configuration that matches a specific event type should be added before a configuration that matches all event types.
If there is no rounding rule in the /config/beid object that matches the resource, event, and process combination, and no default rule that applies to all events, the event is not rounded.
About Rounding Mode Values
The rounding modes you specify in the pin_beid file have corresponding modes in the following API components. However, their values are not all the same:
-
The BRM decimal data type functions. When BRM invokes a decimal data type function, it converts the rounding mode in the /config/beid object into the corresponding rounding parameter used by the decimal data type function. If you call decimal data type functions in custom applications, specify the function's rounding mode, not the BEID rounding mode.
-
The BAS Decimal class. The FCT_Rounding pipeline module converts the rounding mode in the /config/beid object into the corresponding rounding mode used by the BAS rounding method in Pipeline Manager. If you use the BAS Decimal rounding method in custom pipeline modules and iScripts, you should include the FCT_Rounding module in your pipeline. Otherwise, you will need to convert the rounding mode in the /config/beid object into the BAS rounding mode before calling the BAS rounding method.
Table 3-4 shows the BEID rounding modes and the corresponding rounding parameters for the decimal data type functions and the BAS rounding modes:
| BEID Rounding Mode (specified in pin_bill.h) | Rounding Mode Parameter for pbo_decimal functions | BAS Decimal Rounding Mode |
|---|---|---|
|
0: PIN_BEID_ROUND_NEAREST |
5: ROUND_HALF_UP |
0: PLAIN |
|
1: PIN_BEID_ROUND_UP |
1: ROUND_UP |
1: UP |
|
2: PIN_BEID_ROUND_DOWN |
2: ROUND_DOWN |
2: DOWN and TRUNCATE |
|
3: PIN_BEID_ROUND_EVEN |
7: ROUND_HALF_EVEN |
3: BANKERS |
|
4: PIN_BEID_ROUND_FLOOR |
4: ROUND_FLOOR |
101: FLOOR |
|
5: PIN_BEID_ROUND_FLOOR_ALT |
8: ROUND_FLOOR_ALT |
103: FLOOR_ALT |
|
6:PIN_BEID_ROUND_DOWN_ALT |
9: ROUND_DOWN_ALT |
102: DOWN_ALT |
|
N/A |
3: ROUND_CEILING |
N/A |
|
N/A |
6: ROUND_HALF_DOWN |
N/A |
|
N/A |
10: ROUND_UNNECESSARY |
N/A |
Configuring Rounding Rules
To configure rounding rules, you edit the BEID configuration file and then run the load_pin_beid utility to load the contents of the file into the /config/beid object in the BRM database.
Important:
The load_pin_beid utility needs a configuration (pin.conf) file in the directory from which you run the utility.To configure resource rounding:
-
Edit the pin_beid file in BRM_Home/sys/data/pricing/example. The pin_beid file includes instructions.
Caution:
The load_pin_beid utility overwrites the existing resources. If you are updating resources, you cannot load new resources only. You must load complete sets of resources each time you run the load_pin_beid utility. -
Save the pin_beid file.
-
Use the following command to run the load_pin_beid utility:
load_pin_beid pin_beid
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_beid BRM_Home/sys/data/pricing/example/pin_beid
Tip:
If you copy the pin_beid file to the directory from which you run the load_pin_beid utility, you do not have to specify the path or file name. The file must be named pin_beid.For more information, see "load_pin_beid".
-
Stop and restart the Connection Manager (CM).
To verify that the network elements were loaded, you can display the /config/beid object by using Object Browser, or use the robj command with the testnap utility.
After loading the pin_beid file, functions that calculate fees and discounts use the rounding rules in the /config/beid object.
Configuring Rounding Rules for Aggregation Counter Resources
You use Pricing Center to configure rounding rules for aggregation counter resources. When you set up your discount configurations, use discount expressions to specify how to round the resource. Use the following discount expression syntax:
round(expression, rounding_scale, rounding_mode)
where expression defines the resource balance to round. This can be any discount expression. To round an aggregation balance, use the Bal expression. For more information, see the discussion about setting up discounts in the Pricing Center Help.
For example, to round a balance down to two decimal places for an aggregation counter resource with ID 100099, use the following expression:
round( Bal(1000099), 2, ROUND_DOWN )
About Rounding Modes for Discount Expressions
Rounding modes for discount expressions are equivalent to those you specify in the pin_beid file, but they have slightly different names. Table 3-5 lists the rounding mode values you can specify in discount expressions and their pin_beid file counterpart.
Table 3-5 Rounding Modes for Discount Expressions
| Discount Expression Rounding Mode | Rounding Mode Used in the pin_beid File |
|---|---|
|
ROUND_PLAIN |
Nearest |
|
ROUND_UP |
Up |
|
ROUND_DOWN |
Down |
|
ROUND_BANKERS |
Even |
For a definition of what these modes represent, see "About Rounding Modes".
Configuring to Record Rounding Differences in the G/L
To record any difference between rounded bill items and the rounded total in the G/L, perform the following tasks:
For information about how rounding is performed in G/L reports, see "About Rounding and G/L Reports" in BRM Collecting General Ledger Data.
Defining a G/L ID for Rounding Differences
You define a G/L ID for rounding to include the rounding difference in G/L reports so that they can be accurately reconciled.
To define G/L IDs, you edit the G/L ID configuration file and then run the load_pin_glid utility to load the contents of the file into the /config/glid object in the BRM database.
Important:
The load_pin_glid utility needs a configuration (pin.conf) file in the directory from which you run the utility.To define a rounding G/L ID:
-
If necessary, edit the G/L ID configuration file in BRM_Home/sys/data/pricing/example/pin_glid. If the following entry is not present, add it:
#================================================================= # G/L ID for rounding adjustments #================================================================= glid id 1512 descr Rounding Epsilon gl_acct billed gross rounding.debit rounding.credit gl_acct billed net rounding.debit rounding.credit gl_acct billed disc rounding.credit rounding.debit gl_acct billed_earned gross rounding.debit rounding.credit gl_acct billed_earned net rounding.debit rounding.credit gl_acct billed_earned disc rounding.credit rounding.debit gl_acct unbilled gross rounding.debit rounding.credit gl_acct unbilled net rounding.debit rounding.credit gl_acct unbilled disc rounding.credit rounding.debit gl_acct unbilled_earned gross rounding.debit rounding.credit gl_acct unbilled_earned net rounding.debit rounding.credit gl_acct unbilled_earned disc rounding.credit rounding.debit )
Caution:
The load_pin_glid utility overwrites existing G/L IDs. If you are updating G/L IDs, you cannot load new G/L IDs only. You must load complete sets of G/L IDs each time you run the load_pin_glid utility. -
Save and close the file.
-
Use the following command to run the load_pin_glid utility:
load_pin_glid pin_glid_file
For more information, see "Loading General Ledger Configuration Data" in BRM Collecting General Ledger Data.
Mapping the Rounding G/L ID to an Event
Because the rounding difference is not a rated event, you must map the G/L ID to an event type. G/L ID mapping is defined in the reasons.locale file. You can find a sample of this file in the BRM_Home/sys/msgs/reasoncodes directory. The sample file is named reasons.en_US and contains the following default entry for the rounding G/L ID mapping:
DOMAIN = "Others" ;
STR
EVENT-GLID
. . .
/event/journal/epsilon" 1512 ;
EVENT-GLID-END
Note:
/event/journal/epsilon is a dummy event type used for reference only.To change the G/L ID for rounding, you must edit and reload the file. The G/L ID you define in the reasons.locale and pin_glid files must match. See "Configuring to Record Rounding Differences in the G/L".
To map the G/L ID for rounding to an event, you use the load_localized_strings utility to load the contents of the file into the /config/map_glid object. When you run the load_localized_strings utility, use this command:
load_localized_strings reasons.locale
Note:
If you are loading a localized version of this file, use the correct file extension for your locale.Caution:
The load_localized_strings utility overwrites the existing G/L ID maps. If you are updating this object, you cannot load new G/L ID maps only. You must load complete sets of G/L ID maps each time you run the load_localized_strings utility.For information on loading the reasons.locale file, see "Creating a Localized Version of BRM" in BRM Developer's Guide.
Configuring BRM to Record Rounding Differences
By default, rounding differences are not recorded in G/L reports. You can enable this feature by modifying a field in the billing instance of the /config/business_params object.
You modify the /config/business_params object using the pin_bus_params utility.
To enable BRM to record rounding differences:
-
Use the following command to create an editable XML file from the billing instance of the /config/business_params object:
pin_bus_params -r BusParamsBilling bus_params_billing.xmlThis command creates the XML file named bus_params_billing.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.
-
Search the XML file for the following line:
<GenerateJournalEpsilon>disabled</GenerateJournalEpsilon> -
Change disabled to enabled.
Caution:
BRM uses the XML in this file to overwrite the existing billing 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. -
Save and close the file.
-
Use the following command to load the change into the /config/business_params object:
pin_bus_params bus_params_billing.xmlYou should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility.
-
Read the object with the testnap utility or Object Browser to verify that all fields are correct.
-
Stop and restart the Connection Manager (CM).
-
(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.
Setting Up Rounding in Pipeline Manager
Pipeline Manager uses the rounding rules specified in the /config/beid object when applying rounding. To round balance impacts in Pipeline Manager, you configure the FCT_Rounding module. See "About Configuring the FCT_Rounding Module".
You can also set up separate rounding rules when defining a price model. See "About Rounding Rules in Price Models".
Rounding rules can conflict. For more information, see "Avoiding Rounding Conflicts in Pipeline Manager".
About Configuring the FCT_Rounding Module
The FCT_Rounding module finds the rounding rule in the /config/beid object based on the event, resource, and process (rating, discounting, or taxation) combination and then rounds the amount in the relevant EDR packet.
Add FCT_Rounding to the pipeline after the processing module for which it is rounding:
-
To round for rating, add this module after the FCT_RateAdjust module.
-
To round for taxation, add this module after the ISC_TaxCalc iScript module.
-
To round for real-time discounting, add this module after the FCT_Discount module.
-
To round for batch discounting, add this module after the FCT_Discount module and before the FCT_ApplyBalance module.
You specify the process for which this module is rounding in the Mode entry of the module registry:
-
Rating = Round the balance impact of rating.
-
Taxation = Round the balance impact of taxation.
-
Discounting = Round the balance impact of discounting.
For more information, see "Avoiding Rounding Conflicts in Pipeline Manager".
About Rounding Rules in Price Models
You specify one of these rounding methods when defining a price model:
-
None: Only the rounding rules configured in FCT_Rounding are used.
-
Plain: Round up if the last significant digit is 5 or greater.
-
Up: Always round up to the next highest digit.
-
Down: Always round down to the next lowest digit.
-
Bank: If the last significant digit is 5, make it even.
If you specify a rounding method other than None for a price model, Pipeline Manager will use that rounding method during rating.
For more information, see "Avoiding Rounding Conflicts in Pipeline Manager".
Avoiding Rounding Conflicts in Pipeline Manager
For Pipeline Manager, it is possible to specify rounding rules in two places that apply to the same event. Pipeline Manager uses different rounding rules at different points in the rating process:
-
The rounding method specified for the price model is used by the rating module.
-
The rounding method specified for the resource and event is used in the FCT_Rounding module, which is usually run after the FCT_RateAdjust and FCT_Discount modules in the pipeline.
Because rounding can take place at these different points in the pipeline, you can get unexpected results. To avoid conflicts between different rounding rules, you can do one of the following:
-
Choose None for the rounding method in the price model. If you do this, only the rounding rules configured in FCT_Rounding are used.
-
If you select a rounding method other than None in the price model, ensure that the selected method is consistent with the rounding method that FCT_Rounding will use.
Rounding Examples
Rounding is performed after rating, discounting, taxation, and A/R actions such as billing and adjustments.
Table 3-6 shows the resulting balance impacts of rounded charges for rating, discounting, taxation, and billing. This example rounds to the nearest mode and uses these scales:
-
2 for purchase events, taxation, and A/R
-
5 for rating and discounting
Action / Process Calculated Charge Rounded Charge & Balance Impact Account Balance Purchase plan
Rate cycle fee
9.95
9.95
9.95
Use service
Rate usage
5.23456789
5.23457
15.18456
Discount usage fee 10%
0.523456789
0.52346
14.66111
Tax usage event 3% (after discount)
0.1413333
= 3% * (rounded usage fee - rounded discount)
0.14
14.80111
Run billing
Apply billing-time discount of 5% off total usage
0.24250...
= 5% * usage item total after A/R rounding
(The usage total does not include the cycle fee.)
0.2425
14.55861
Create bill
14.55861
= Total of all items
14.56
(No balance impact)
14.56
Correcting for Precision Loss When Rounding Down
This example shows the results of rounding when you use the ROUND_DOWN_ALT and ROUND_FLOOR_ALT modes. For more information, see "About Rounding Modes That Correct for Loss of Precision".
The ROUND_DOWN_ALT and ROUND_FLOOR_ALT modes produce different results than ROUND_DOWN and ROUND_FLOOR only when the three digits following the last significant digit are 995 or greater. (The last significant digit is the digit in the decimal place corresponding to the scale: If the scale is 2, the last significant digit in the number 1.23456 is 3.)
For example:
Table 3-7 shows some rounding results of the ROUND_DOWN_ALT and ROUND_FLOOR_ALT modes as compared to their non-alternative rounding counterparts (ROUND_DOWN and ROUND_FLOOR) for various decimal values and rounding scales.
| Decimal | Scale | Rounding Mode | Rounding Mode | Rounding Mode | Rounding Mode |
|---|---|---|---|---|---|
| NA | NA | DOWN | DOWN_ALT | FLOOR | FLOOR_ALT |
|
1.5256 |
2 |
1.52 |
1.52 |
1.52 |
1.52 |
|
-1.5256 |
0 |
-1 |
-1 |
-2 |
-2 |
|
12.8999... |
0 |
12 |
12 |
12 |
12 |
|
12.8999... |
1 |
12.8 |
12.9 |
12.8 |
12.9 |
|
12.8999... |
2 |
12.89 |
12.90 |
12.89 |
12.90 |
|
-12.8999... |
1 |
-12.8 |
-12.9 |
-12.8 |
-12.9 |
|
-12.8999... |
2 |
-12.89 |
-12.900 |
-12.89 |
-12.90 |
|
-6.9990 |
2 |
-6.99 |
-6.99 |
-7.00 |
-7.00 |
|
-6.9990 |
3 |
-6.999 |
-6.999 |
-6.999 |
-6.999 |
|
7.999... |
0 |
7 |
8 |
7 |
8 |
|
7.999... |
1 |
7.9 |
8.0 |
7.9 |
8.0 |
|
7.999... |
2 |
7.99 |
8.00 |
7.99 |
8.00 |
|
-7.999... |
0 |
-7 |
-8 |
-8 |
-8 |
|
-7.999... |
2 |
-7.99 |
-8.00 |
-8.00 |
-8.00 |
Rounding Using Different Modes
The aggregated effects of rounding on the final balance impact is determined by the mode and scale that you configure. The higher the scale, the less effect the rounding mode has on the final balance impact.
For example, Table 3-8 shows the impact of various rounding mode combinations for rating a usage fee of $1.1234567 that includes a 10% discount. Both rating and discounting use a scale of 6:
| Processing Stage (Rating and Discounting) | Rating: Round DownDiscounting: Round Down | Rating: Round DownDiscounting: Round Up | Rating: Round UpDiscounting: Round Down | Rating: Round UpDiscounting: Round Up |
|---|---|---|---|---|
|
Round for rating |
1.123456 |
1.123456 |
1.123457 |
1.123457 |
|
Calculate 10% discount |
.1123456 |
.1123456 |
.1123457 |
.1123457 |
|
Round discounted amount |
.112345 |
.112346 |
.112345 |
.112346 |
|
Apply discount to usage fee to get final balance impact |
1.011111 |
1.011110 |
1.011112 |
1.011111 |
In this example, the difference in the final balance impacts is small because the scale is high and probably will not change the final amount on the bill. However, when many events are summed in an item, or the scale is small, such as 2 or 3, the differences become greater.
Tip:
If you calculate the discount without rounding the event, the configuration where rating is rounded down and discounting is rounded up returns the most accurate result. Therefore, this is the best mode configuration to use when you discount events.Modifying a Rounding Rule
To modify a rounding rule, you must change the rule in the pin_beid file and reload the file by running the load_pin_beid utility. See "Configuring Resource Rounding".
Setting Up Ratable Usage Metrics (RUMs)
For background information about RUMs, see "About Ratable Usage Metrics".
Real-time rate plans and pipeline rate plans each use a different set of RUMs. See the following topics:
About Setting Up Rums for Real-Time Rating
Before you create your price list, you must define the RUMs available for rating. When you define RUMs, you define the following RUM attributes:
-
The event type that can be rated by using the RUM (for example, Internet usage events). You can specify more than one RUM for an event type.
-
The unit of measurement. For example, to rate duration, you might specify seconds or minutes. To measure bytes, you might specify megabytes or kilobytes.
-
The RUM name (for example, ”Duration,” ”Pages,” or ”Bytes”). The RUM name is displayed in Pricing Center.
-
How to calculate the quantity. For example, to calculate the length of a session event, you subtract the time the event started from the time that the event ended:
Event start: 7:00 p.m.
Event end: 9:00 p.m.
Event end - Event start = 2 hours
This RUM is defined as follows:
/event/session : Duration : PIN_FLD_END_T-PIN_FLD_START_T : second
-
The RUM name ”Duration” appears in Pricing Center.
-
The duration is calculated by subtracting the start time from the end time.
-
The duration is calculated by using seconds.
-
To perform calculations, you can use simple arithmetic by using the following operators:
-
+
-
-
-
*
-
/
-
(
-
)
You can use three data types:
-
PIN_FLDT_INT
-
PIN_FLDT_DECIMAL
-
PIN_FLDT_TSTAMP
You can use fields in a substruct, but you cannot use arrays.
Note:
The data used for the quantity calculation is stored in event object fields. For example, the event start and end times are stored in PIN_FLD_START_T and PIN_FLD_END_T. You must be familiar with events and event fields to specify quantity calculations.To define the RUMs, you edit the pin_rum file and load it into the BRM database using the load_pin_rum utility. See "Creating Ratable Usage Metrics".
Creating Ratable Usage Metrics
To create RUMs, you edit the pin_rum file and then run the load_pin_rum utility to load the contents of the file into the /config/rum object in the BRM database.
Important:
The load_pin_rum utility needs a configuration (pin.conf) file in the directory from which you run the utility.To create ratable usage metrics:
-
Edit the pin_rum file in BRM_Home/sys/data/pricing/example. The pin_rum file includes examples and instructions.
Important:
A RUM name can include a maximum of 255 characters.Caution:
The load_pin_rum utility overwrites existing RUMs. If you are updating RUMs, you cannot load new RUMs only. You must load complete sets of RUMs each time you run the load_pin_rum utility. -
Save and close the pin_rum file.
-
Use the following command to run the load_pin_rum utility:
load_pin_rum pin_rum_fileIf 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_rum BRM_Home/sys/data/pricing/example/pin_rum_file
For more information, see "load_pin_rum".
-
Stop and restart the Connection Manager (CM). If necessary, stop and restart Pricing Center.
To verify that the pin_rum file was loaded, you can display the /config/rum object by using Object Browser, or use the robj command with the testnap utility.
Important:
Fold events cannot use custom RUMs; therefore, do not assign custom RUMs to fold events in any rate plans. Products configured with custom fold RUMs are rated incorrectly.Setting Up Pipeline Ratable Usage Metric (RUM) Groups
RUMs are ways in which you can measure events, such as how long they last or how big they are. When you create RUMs, you give them names, such as Duration or Volume, and assign them a type, such as Duration, Event, or Normal.
Units of measurement (UoMs) are the names you give to units you will use to measure events, such as seconds or bytes.
A RUM group associates two or more RUMs together and associates a UoM with each RUM in the group.
When you rate events by using a RUM group, a separate charge packet is created for each RUM.
About Defining Units of Measurement (UoMs)
UoMs are the names you give to units you will use to measure events, such as seconds or bytes.
About Defining Ratable Usage Metrics (RUMs)
RUMs are types of event measurements that you define, such as duration or volume.
About Defining a RUM Group
A RUM group groups two or more RUMs together and associates a UoM with each RUM in the group.
Converting Units of Measurement
The UoM of an incoming EDR can be converted into a UoM needed for rating a particular service. For example, an EDR might include the usage amount in seconds, but the service is configured to charge by minutes. The FCT_UoM_Map module converts seconds to minutes, using rounding rules.
To configure UoM mapping:
-
Use Pricing Center to create a UoM map to convert UoMs. When you convert UoMs, you specify the following:
-
The RUM that uses the UoM.
-
The UoM to convert from.
-
The UoM to convert to.
-
The conversion factor. For example, use a factor of 1024 to convert kilobytes into bytes.
-
The rounding rule. The options are:
-
Nearest (N)
-
Always up (U)
-
Always down (D)
-
-
-
Configure the FCT_UoM_Map module.
Mapping Event Types to RUMs
Normally, you map event types to RUMs by using Pricing Center. However, you can edit the pin_usage_map file and load its content into the BRM database by running the load_usage_map utility. By doing so, you update the /config/usage_map/system object.
For background information, see "About Different Types of Rates".
Important:
The load_usage_map utility requires a configuration (pin.conf) file in the directory from which you run the utility.-
Edit the pin_usage_map file in BRM_Home/sys/data/pricing/example. The pin_usage_map file includes examples and instructions.
Caution:
The load_usage_map utility overwrites existing usage maps. If you are updating a set of usage maps, you cannot load new usage maps only. You must load complete sets of usage maps each time you run the load_usage_map utility. -
Save the pin_usage_map file.
-
Use the following command to run the load_usage_map utility:
load_usage_map pin_usage_map_fileIf you are not in the same directory as the pin_usage_map file, include the complete path to the file. For example:
load_usage_map BRM_Home/sys/data/pricing/example/pin_usage_map_file
For more information, see "load_usage_map".
-
Stop and restart the Connection Manager (CM). If necessary, stop and restart Pricing Center.
To verify that the data loaded correctly, display the /config/usage_map/system object by using Object Browser, or use the robj command with the testnap utility.
Mapping Event Types to Services
To specify which events to rate, you edit the pin_event_map file and run the load_event_map utility to store the list of ratable events in your database.
For example, to rate a dialup session, the pin_event_map file includes this entry:
/service/ip: /event/session/dialup: IP Dialup Event start_t
This entry specifies that:
-
When you create a product for an IP service, you can rate dialup events.
-
The name of the event is displayed in Pricing Center as ”IP Dialup Event.”
-
The start time of the event determines which account sub-balance the event applies to. This field is optional and relevant only for session events in which the duration might overlap the sub-balance validity period.
For example, an account has two sub-balances:
-
A sub-balance with a resource of free minutes and a validity period that starts at 1:00 p.m. and ends at 2:00 p.m.
-
A sub-balance for dollars that is impacted by telephony usage.
The customer makes a call at 1:55 p.m. and ends the call at 2:10 p.m. If you specify the start time in the pin_event_map file for the usage event, the customer is allowed to use the free minutes because the call began after the validity start time, and the free minute sub-balance is impacted. However, if you specify the end time, the customer cannot use the free minutes because the call ended after the validity end time, so charges for the minutes used are applied to the dollars sub-balance.
If this field is not present, the start time is used by default. For more information about sub-balances, see "About Tracking Resources in Account Sub-Balances".
Important:
The load_event_map utility requires a configuration (pin.conf) file in the directory from which you run the utility. -
To map event types to services, you edit the pin_event_map file and then run the load_event_map utility to load the contents of the file into the /config/event_map object in the BRM database.
-
Edit the pin_event_map file in BRM_Home/sys/data/pricing/example. The pin_event_map file includes examples and instructions.
Caution:
The load_usage_map utility overwrites existing usage maps. If you are updating a set of usage maps, you cannot load new usage maps only. You must load complete sets of usage maps each time you run the load_usage_map utility. -
Save the pin_event_map file.
-
Use the following command to run the load_event_map utility:
load_event_map pin_event_map_fileIf you are not in the same directory as the pin_event_map file, include the complete path to the file, for example:
load_event_map BRM_Home/sys/data/pricing/example/pin_event_map_file
For more information, see "load_event_map".
-
Stop and restart the Connection Manager (CM). If necessary, stop and restart Pricing Center.
To verify that the pin_event_map file was loaded, you can display the /config/event_map object by using Object Browser, or use the robj command with the testnap utility.
About Tracking Resources in Account Sub-Balances
Your customers' account balances are stored in balance groups. A balance group contains a collection of balances for various resources such as currency, minutes, bytes, and frequent flyer miles. Accounts can have multiple balance groups.
Account balances are grouped by the type of resource they track. Each resource can include one or more sub-balances. A resource includes more than one sub-balance when portions of the resource are valid at different times. For example, a resource of free minutes might include 300 minutes that are valid only for the current month and 1000 free 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.
Account sub-balances include the following information:
-
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".
-
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 Non-Currency Sub-Balances
A non-currency sub-balance typically has a limited validity period (for example, the period during which free minutes can be used). Non-currency sub-balances can contain various types of resources, such as:
-
Free minutes.
-
Frequent flyer miles.
-
Loyalty points.
-
Number of emails or text messages.
A non-currency 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.
For information about creating discounts that can be shared, see "Discount Sharing Configuration Example" in BRM Configuring Pipeline Rating and Discounting.
When granting a non-currency 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, non-currency 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 Non-Currency 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 summed 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:
For more information, see "About Configuring Time-Stamp Rounding" in BRM Configuring and Running Billing.
Configuring Time-Stamp Rounding for Cycle Grants
To configure BRM to round time stamps to midnight for the resources granted by cycle events:
-
Open the CM configuration file (BRM_Home/sys/cm/pin.conf) in a text editor.
-
Set the timestamp_rounding entry to 1.
-
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:
-
Open the CM configuration file (BRM_Home/sys/cm/pin.conf) in a text editor.
-
Set the timestamp_rounding entry to 1.
-
Save and close the file.
-
Go to the BRM_Home/sys/data/config directory, where BRM_Home is the directory in which BRM is installed.
-
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.xmlThis 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.
-
Open the bus_params_rating.xml.out file.
-
Search for the following line:
<TimestampRoundingForPurchaseGrant>disabled</TimestampRoundingForPurchaseGrant> -
Change disabled to enabled.
-
Save the file as bus_params_rating.xml.
-
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. -
Read the object with the testnap utility or the Object Browser to verify that all fields are correct.
See "Using testnap" in BRM Developer's Guide for general instructions on using the testnap utility. See "Reading Objects by Using Object Browser" in BRM Developer's Guide for information on how to use Object Browser.
-
Stop and restart the CM.
-
(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.
About Non-Currency Sub-Balances That Start on First Usage
When a non-currency 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:
-
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".
-
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
Caution:
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.Important:
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 3-9 shows contributor configurations to track resources for GSM services. The resources are dollars and free minutes.
Table 3-9 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 non-currency 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 non-currency 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 is 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 Tracking Resources in Account 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.
BRM supports the resource consumption rules shown in Table 3-10:
Table 3-10 Supported Consumption Rules
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:
-
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.
-
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.
-
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:
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 Managing Customers.
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:
-
Use the following command to create an editable XML file for the multi_bal class:
pin_bus_params -r BusParamsMultiBal bus_params_multi_bal.xmlThis 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.
-
Search the XML file for following line:
<SortValidityBy>ESTEET</SortValidityBy> -
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".
Caution:
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. -
-
Use the following command to load the change into the /config/business_params object:
pin_bus_params bus_params_multi_bal.xmlYou should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility.
-
Read the object with the testnap utility or Object Browser to verify that all fields are correct.
-
Stop and restart the Connection Manager (CM).
-
(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.
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.
Important:
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" in BRM System Administrator's Guide.
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.
Important:
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 executes 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 expired 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.
-
-
On January 1, the customer is granted 500 free minutes for use during January as shown in Figure 3-2. The free minutes are maintained in a resource sub-balance.
Figure 3-2 Initial 500 Free Minutes Grant in January
Description of ''Figure 3-2 Initial 500 Free Minutes Grant in January''
-
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 3-3.
-
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 3-4.
Figure 3-4 January Free Minutes Rollover
Description of ''Figure 3-4 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 3-5.
Figure 3-5 February Total Free Minutes Available
Description of ''Figure 3-5 February Total Free Minutes Available''
-
-
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 3-6.
-
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 3-7. 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 3-7 February Free Minutes Rollover
Description of ''Figure 3-7 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 3-8.
Figure 3-8 Remaining January Free Minutes Rollover
Description of ''Figure 3-8 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 3-9.
Figure 3-9 March Total Free Minutes Available
Description of ''Figure 3-9 March Total Free Minutes Available''
-
-
During March, the customer consumes 620 minutes as shown in Figure 3-10. 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.
-
-
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 3-11.
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.
The customer has only 500 free minutes available for April.
Important:
-
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 3-12, 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 3-12 Grant and Rollover Balance Date Validity Example 1
Description of ''Figure 3-12 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 3-13, a monthly cycle event grants 300 free minutes that are valid for six week 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 3-13 Grant and Rollover Balance Date Validity Example 2
Description of ''Figure 3-13 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 3-11 describes the rollover proration options:
Table 3-11 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 3-14 to calculate the amount to rollover:
Figure 3-14 Calculation for Amount to Rollover
Description of ''Figure 3-14 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 3-12 describes how the rollover is handled, depending on the Purchase Mid-cycle Proration setting:
Table 3-12 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 non-currency 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.