CRD balance table definitions are pre-shipped (read only) as part of the Policy Builder configuration. For this, the "CRD Balance" feature (com.broadhop.balance.crdbalance.feature) needs to be installed. Enable this functionality by selecting the Enable Crd Balance Template Lookups check box. For more information, see Balance Configuration.

The following required tables include result columns that directly map to the corresponding fields in Balance and Quota Templates. For more information on individual field description, see Account Balance Templates.

• q_account_balance: Top Level Account Balance Template fields

• q_one_time_quota: One Time Quota Template definition

• q_recurring_quota: Recurring Quota Template definition

• q_rollover_quota: Rollover Quota Template definition

• q_threshold_definition: Threshold definitions

• q_threshold_balance_association: Balance to threshold association

• q_threshold_quota_association: Quota to threshold association

Recurring quota is refreshed periodically with a specific amount each refresh. It defaults to infinite duration meaning that it continues until the account is deleted from the system. However, it is possible to limit the duration of a recurring quota using the Recurrence Limit field. The most common time period is Monthly. Time periods defined in hours, days, weeks, months are possible. Initial credit and refreshed amounts by default expire at the end of the current time period.

The following parameters can be configured under Recurring Quota Templates:

Note	All the dates in Balance such as start, expiration, refresh, etc. have a time element. What is set for the time element affects expiration and refresh time on the given day.

Rollover quota templates are special quotas that store leftover amounts from a Recurring quota. Rollover occurs when the Recurring quota refreshes. Rollovers can also be triggered manually via API. The amount to rollover can be limited, and the total amount in the rollover quota can be limited.

Rollover quota templates behaves like One Time quota templates, but should not be provisioned directly. Unlike One Time quotas, Rollover quotas have no default/initial amount.

The following parameters can be configured under Rollover Quota Template:

Limitations and Restrictions

Rollover Quotas may experience undesirable behavior when used in conjunction with Recurring Quotas that have a recurrence frequency of less than 1 day.

The recurring quota and rollover quota involved in the rollover operation must be defined under the same Balance template. Rolling over from one Balance template to another Balance template is not supported.

Note

Do not provision rollover quotas using the Control Center. Even though Rollover quota is a special type of One Time quota, they are not designed for manual provisioning. They are designed to work with a Recurring quota and receive credits only based on the unused amounts rolled over from that Recurring quota to which they are linked.

Adjustments can be made to Rollover quota via the Credit or Debit APIs, but this is not a typical or common use case, and is not recommended by Cisco.

One Time quota templates are used for one time applications like TopUp or Bonus quota that has a finite duration (start and end date) and amount. One Time quota does not refresh automatically.

The following parameters can be configured under One Time Quota Template:

BillCycle quotas were introduced in Balance 2.3.0. BillCycle is a special type of Recurring quota that handles end of month refresh dates better than the typical Recurring quota template. The Bill Cycle functionality aligns better with some customers' billing cycles and removes the recommended limitation of only using days 1 - 28 for Recurring quota starts/ends.

Note

The “RFAmt ignored” hint that appears on BillCycle in Policy Builder is just a reminder that the Recurrence Frequency Amount field is ignored if you select a Recurrence Frequency of BillCycle. Refresh happens every 1 BillCycle regardless. The system cannot wait 2 or more BillCycles before refreshing.

Thresholds allow policy actions to be taken when a certain amount of quota has been used. Actions can be taken on threshold breach, unbreach, and continued breach status. Thresholds can be grouped to suppress past threshold breaches.

The threshold table in the Policy Builder sets thresholds that will be reported on when breached/unbreached and what their current amount is while breached. These messages are sent back to the policy engine from MsBM on Credit, Debit, Charge, and Provision functions so that policies can make decisions and take actions based on the threshold breach.

A typical action upon threshold breach is “Send a SMS notification”. To send an SMS notification, the Notifications feature must be installed and configured in the system.

The Depleted flag is set when isExhausted is set to true and the granted quota is zero on the OCSCreateReservationResponse from the Balance Manager.

IsExhausted is set whenever the full requested reservation amount cannot be fulfilled.

Note

Keep in mind that in both cases these conditions may not mean that the balance is completely exhausted permanently. If there is more than one reservation against the balance, one of those reservations may only be partially charged or released altogether (either through expiration or zero charge) which will release an amount of quota which will again become available for use.

The Balance Plug-in Configuration contains a field called Expired Reservations Purge Time, which when set allows the retention and charging of expired reservations. In some systems with significant lags in usage reporting, this option provides a mechanism to maintain more accurate accounting.

The Expired Reservations Purge Time is how long reservations can be charged after they expire as long as quota is not exhausted.

• A 0 value for Expired Reservations Purge Time means it doesn’t keep any expired reservations after they expire.

• A non-zero amount is the amount of time in minutes it will keep a reservation and allow charges against said expired reservation.

• There is not a recommended value other than zero which is the default for legacy reasons. The value depends on how the system is being used, what network device is being used, and how often and how late it reports usage.

Determining the next active credit to reserve against is done by the following logic:

• Credits belonging to the highest priority (lowest numerical priority value; priority 1 is highest) quotas are examined first.

• Credits that are next to expire are examined next. That is, credits with the soonest end date. If there are multiple credits with the same soonest end date, then the credit will be selected from that subset as the one with the oldest start date.

• If no credits with end dates are found, credits with no end date are examined, and the credit with the oldest start date is used first.

Note	This logic is restricted to a given quota code when a Debit is performed with a quota code specified as opposed to a Debit without a quota code which will check across all the quotas defined for the subscriber to find an applicable credit.

Tariff Times is the CPS nomenclature for defining rates and when to apply them. To determine the current TariffSwitchTime, Balance takes the current time (using the time zone specified on the tariff time reference data configuration) and checks each switch time in order top to bottom to see if the current time matches a TariffSwitchTime. The first tariff switch time that matches (including the associated valid dates OR a holiday date) will be used. The time of the tariff switch will be the end of the current tariff period. Then the next tariff switch time is calculated, by taking the end of the current tariff switch time, adding one second and searching each tariff switch time (top to bottom) to find the first one that matches.

• subscriberId (PK)

  • Key field to reference a given subscriber account. This account may be shared among multiple subscribers.

  • Value is also stored as _id which is a key field for the Mongo database document. These values were different in early versions of MsBM, but have been aligned to ensure greater system stability. The _id was originally a Mongo assigned UUID.

• The Subscriber Account contains all data structures related to a specific subscriber's account as it relates to MsBM. When you retrieve a Subscriber Account, you obtain all MsBM information for a given subscriber.

• accountBalanceCode (PK within the scope of a given subscriber account)

  • relates to the Account Balance Template reference data information defined in Policy Builder.

  • key for Policy Engine to access this balance's information for a selected subscriber account.

• An account balance, or simply a balance as it is often referred to, is essentially a group of quotas. The idea is that a customer could create a balance (quota grouping) called Data and within that have several quotas defined, like Monthly, Topup, and Bonus. Then when the subscriber uses account, usage is charged against their Data balance and MsBM determines which underlying quota should be debited based on rules set up in Policy Server (QNS). The intent here is to simplify charging so that specific “buckets” do not need to be specified and necessary business rules can be defined once in the Policy Engine.

• quotaCode (PK within the scope of a given subscriber account)

  • relates to the Quota Template reference data information defined in Policy Builder.

  • key for Policy Engine to access this quota's information for a selected subscriber account.

• A quota defines the actual amount or “bucket” that can be drawn from for tracking of usage. This value internally is unit-less and thus can be defined to be whatever is needed in the implementation. Some units are provided in reference data in Policy Builder to assist users. Common usages for quota amounts are bytes of volume, seconds of time, but other counts can also be tracked.

• A UUID (PK) is used as a key to the map containing all the credits for a given quota.

• A UUID was selected since the data structure was defined for transactional speed and stability and was not intended to be queried directly. MsBM records are intended to be accessed using the Policy Engine, the provided APIs, and the Reporting Engine. The intent in the design of this structure was transactional usage and performance, not queryability. A sequence concept or other more predictable key was not used since a sequence would most likely be rapidly exhausted and more difficult to manage since credits are regularly created and destroyed as part of the normal operation of MsBM. Uniqueness and assurance of avoidance of deadlocking is the primary concern.

• Credits can be viewed as positive entries on an accounting balance sheet.

• A UUID (PK) is used as a key to the map containing all the debits for a given credit.

• The reasoning for selection of the UUID is the same as discussed under Credit.

• Debits can be viewed as negative entries on an accounting balance sheet for a specific credit. Debits under a given parent credit cannot exceed the amount of the parent credit.

• reservationId (PK)

  • Also a UUID and was selected for similar reasons as discussed under Credit.

• Reservations describe an amount of conditional debiting of quota that is reserved until a network device reports that the quota has actually been utilized.

• reservationDebitId(PK)

  • Also a UUID and was selected for similar reasons as discussed under Credit.

• reservationId (FK)

• debitId (FK)

• Reservation debits serve the purpose of providing a link between a reservation and an actual debit entry. When a reservation is charged, the reservation and associated reservation debits are removed and the debit linked to those reservation debits are made permanent. That is, as long as a debit has a linked reservation debit, that debit is not permanent, but only reserved in a non-committed state.

The Thresholds collection contains any reference data thresholds (defined in Policy Builder) that are currently breached or any user-defined thresholds that are specific to a given subscriber account.

The thresholds map is not utilized and may not appear in all implementations. It will only appear as needed if the related functionality in Policy Server (QNS) is active.

An identical structure as Reservations is used for Expired Reservations, except that Reservation Debits do not have a link to Debits. Functionality for charging expired reservations, that is, creating debits, is handled in a different fashion.

The expired reservations map is not utilized and may not appear in all implementations. It will only appear as needed if the related functionality in Policy Server (QNS) is active.

There will be two Balance accounts associated with a subscriber that is participating in a shared quota but also needs a per user limit on said shared quota. The first Balance account is the subscriber's personal account. This account will contain any balances/quotas that are only available to the subscriber. This account will also contain one balance that will be used for tracking the per user limit. The second Balance account is not owned by the subscriber and contains the shared balance/quotas.

Note	The two Balance accounts need to be provisioned separately.

The shared balance template contains a field called Limit Balance that links the shared balance to a limit balance (the personal account), so that the Balance module knows which two balance codes it needs to reserve/charge against in the shared per user limit case. Since the per use limit is tied to a quota template, only discrete per user limits are supported. The number of balance/quota templates defined is not limited, but the templates must be defined for each per use limit level. The limit quotas must be defined in a balance/quota template.

The subscriber must be provisioned with the limit balance and an associated quota with a valid amount for the per user limit to be enforced. An AVP must added to the subscriber profile in SPR indicating the Balance account record and the Balance template name of the shared quota. This is done currently for some deployments. The subscriber must have the AVP set up prior to per user limits being available.

If the subscriber does not have the limit balance provisioned, then the subscriber will draw from the shared balance with no per user limit enforced.

Hard thresholds (meaning the subscriber cannot use more than a certain amount of the shared quota) will be enforced by the amount provisioned in the limit balance.

Soft thresholds (meaning the subscriber can continue to use more up to the hard threshold, but something should happen when the soft threshold is crossed) will be supported using the threshold mechanism defined on the limit balance.

The charge and reserve function of the Balance module were enhanced with conditional logic to make new calls to handle the shared per user limit reservations. The new calls allow charges or reservations against two Balance accounts at the same time. The two Balance accounts are the shared account, as indicated by the AVP, and the subscriber's personal balance account (the limit balance).

A subscriber has 5 GB on the first plan and has used 3 GB of it. The subscriber then switches to a different plan with 2 GB. The subscriber will start with 2 GB of available quota UNLESS the CreateBalance API overrides the initial amount. Setting the override amount is a manual step that is handled by the calling system, i.e. customer portal or OSS/BSS application.

The Sy server uses the CPS balance manager for volume/quota definition, and association to subscriber and threshold configuration. For configuration information, refer to Quota Templates.