On-Demand Periodic Balances

On-demand periodic balances, like standard periodic balances, contain a series of intervals, each of which is available for the same length of time. Unlike standard periodic balances, the next interval in the series is not created immediately when the current interval expires. Instead, it is created when charging subscriber usage or normalizing against the balance. This can result in intervals that overlap or that are days, weeks, months, or years apart.

When defining periodic or on-demand periodic balances, you cannot set the end time to the past. For more information, see the discussion about configuring periodic balances in My MATRIXX Help.

Important: Once an on-demand balance is in use, the balance period cannot be changed.
On-demand periodic balances share the following properties with standard periodic balances:
  • A template defines a sliding window containing a fixed number of intervals with lifetimes determined by low-water and high-water marks. The template defines a set of thresholds, including one credit limit, which a subscriber can customize. It also specifies a duration (such as 1 day or 6 hours) between the start time and end time of each interval.
  • Each balance and interval has a start time and an end time based on the time of its creation and on the template policy. Each interval ends the specified number of minutes, hours, days, weeks, months, or years (for example, 15 minutes, 24 hours, 7 days) after it starts. Each unit begins at the exact beginning of the unit. For example, hours start at xx:00:00 (23:00:00).
  • Each balance has a resource ID that uniquely identifies a balance throughout the lifetime of its wallet.
  • Each interval has an interval ID that uniquely identifies an interval throughout the lifetime of its balance.
  • Each balance or interval is considered expired for events at or after its end time.
  • Each balance can be defined as prepaid, with the initial credit of each interval provided by a first-usage grant to itself (after any applicable first-usage charges are met for that interval).
On-demand periodic balances have the following additional properties that standard periodic balances do not have:
  • Intervals can be created when usage or non-usage rating would use the balance amount or expiration of an interval to prioritize an offer, select a balance to impact, or determine the amount of the impact. Only a positive usage charge triggers first-usage components.
    Note: This can result in intervals that overlap or that are days, weeks, months, or years apart.
  • On-demand periodic balances create a new interval when no intervals exist or when any existing intervals have expired. In addition, they can be configured to create a new interval overlapping any existing intervals that have reached the credit limit. For renewable on-demand balances specifically, a new interval can be created if existing intervals have no credit to be charged. In this case, the start of the new interval is between the start and end of the latest existing interval.
    Note: An on-demand interval generally starts at the time of its creation and ends after the duration specified in the balance template. For example, an event could create a one-hour or one-day interval that starts at 24 January at 8:19 AM. A one-hour interval would end at 9:19 AM and a one-day interval would end on 25 January at 8:19 AM. Standard (not on-demand) hourly intervals start and end at the top of the hour and standard daily intervals start and end at midnight.
  • A charge, discount, or grant impact of zero can select an existing interval if one is available. Otherwise, a transient interval is created that will be destroyed at the end of rating. Impacts of zero to a transient interval are reported in the Event Detail Record (EDR) to the balance and not to the interval (no interval ID).
    Note: A $5.00 charge with a $5.00 discount is recorded as two nonzero impacts, even though the total impact is zero.
  • An older event (for example, from yesterday) can consume available credit in newer intervals (for example, from today). If the balance is renewable, each new interval can be created with a start time that is at the start time of the latest existing interval. If rating requires more intervals than are available, older intervals might be recycled and replaced by newer intervals. If the old intervals had obsolete quota reservations against them, the reserved amount is discarded so the reserved amount of a newer interval is not affected. When this occurs, trace messages are written to the mtx_debug.log file.

    This behavior indicates that reservations are lasting longer than the balance intervals. In such cases, you can either use balances with more intervals in them so that the intervals last longer, or use shorter quota validity times so that the reservations do not last as long.

  • SubMan balance requests, such as queries, balance adjustments, top-ups, or transfers, can reuse existing intervals but cannot create new intervals.
  • On-demand periodic balances cannot be aggregated balances (shared by a group). They exist as a single G/L balance and are generally only useful in a subscriber wallet.
  • If usage is charged to an on-demand interval for the first time, the amount available for the usage charge includes the result of first-usage processing.
When an interval is selected for a usage charge for the first time, first-usage processing occurs and the result is included in the amount available for the usage charge. This feature is unique to on-demand balances and can be used to model the concept of a prepaid balance.
Note: Prepaid simple balances can be initialized with purchase grants and periodic balances can be initialized with recurring grants. MATRIXX Support recommends that to apply a first-usage charge to an asset, the asset should be awarded using a first-usage grant when possible.

First-usage is processed only after all offer priority generators, balance filters, and balance normalizers that initiated the first-usage processing are evaluated. Multiple concurrent charges (such as a balance and a meter, or two different charge components) might be processed in any order, which might result in a normalizer on one charge seeing or not seeing the result of applying the other charge.

For information about cycle processing, see the discussion about cycle processing.

On-Demand Periodic Balance Intervals

The three types of intervals include:
  • Actual interval — Has had at least one actual charge or grant. An actual interval is destroyed when it slides out of the window.
  • Tentative interval — Has had reservations for usage charges only. A tentative interval is destroyed when the last reservation is released.

    Tentative intervals are identified by the IsTentative Boolean field in MtxBalancePeriodInfo returned in SubMan API wallet queries.

  • Transient interval — Any reference to a balance in a price component during rating (for example, an offer priority based on a primary balance, normalization on a balance, selection of a rate table in a price component, computation of a rating formula based on a balance amount) creates a transient (internal) interval if none exist or if all have expired. References related to charges create a new transient interval if unexpired intervals are at the credit limit and the balance is renewable. A transient interval is created even if the specific balance will not be impacted (for example, when normalizing on balance1 to determine how to charge balance2). A transient interval is committed to the database only when a nonzero charge, discount, or grant impact is applied to it. Otherwise, it is destroyed.
Note: Tentative intervals must be considered when determining an appropriate window size for the balance. The number of tentative intervals is limited by the amount and duration of outstanding reservations against them, which can be controlled using the maximum reservation amounts and time in the balance template and the quota validity time in the service configuration.

Intervals are created, selected, and maintained in chronological order. When rating an event against an on-demand balance, intervals are selected starting with the earliest unexpired interval below the balance credit limit. If an unexpired interval exists, it can be converted from one type to another. If there is no unexpired interval, a new one can be created.

A new interval might be created depending on the type of balance:
  • Non-renewing balance — A new interval might be created only if no intervals currently exist, or if all existing intervals have expired.
  • Auto-renewing balance — A new interval might be created if all unexpired intervals are at their credit limits.