Thresholds

For many thresholds, the threshold is an amount at which a notification is triggered to alert group administrators or subscribers that a balance or meter has reached or exceeded a specific amount. These thresholds are called soft thresholds because they do not result in a denial of rating. Some thresholds, such as balance-floor thresholds, are hard thresholds in that any operation that exceeds its limit is denied.

The purpose of a threshold is to send an alert about how much has been spent so assets can be topped-up or a payment can be made before service is throttled or denied. As with credit limits, balances can have default, personal, and group thresholds set on them. Thresholds can be set for both prepaid and postpaid balances and meters, and simple and periodic balances and meters. For periodic balances and meters, each periodic entry in the series inherits the threshold values set on the first entry. Credit limits and notification thresholds do not fluctuate from entry to entry.

Note: For composite meters, thresholds apply only to the composite value, not to the component values.

When a subscriber or group purchases additional product offers for a recurring grant, the credit floor is increased by the sum of all grants to that periodic balance. The threshold limit is reset to match the absolute value of the credit floor. For example, if a balance has a recurring grant of 300 minutes and an additional product offer is purchased for that balance with a recurring grant of 200 minutes, the credit floor changes from -300 to -500 and the threshold limit is reset to 500.

If a subscriber or group cancels a product offer for a recurring grant, the credit floor is decreased by the amount of the product offer. The cancelation is either immediate, at the end of the billing cycle, at the end of the balance cycle, or at the end of purchased item cycle, as determined by the Offer Cancel Type value in the product offer. For example, if a balance has two recurring grants for a total of 500 minutes and a subscriber cancels a product offer for that balance with a recurring grant of 200 minutes, the credit floor changes from -500 to -300 and the threshold limit is reset to 200 minutes. The adjusted credit floor can be less than the canceled grant amount (credit floor can be less than or equal to 0). If the target of the product offer purchased by a subscriber or group is tier (not event initiator) and the tier of the parent group is the same as the purchased offer target tier, the credit floor of the parent group is increased by the granted amount. If the offer is canceled, the credit floor of the parent group is decreased by the canceled amount. If the target of the product offer purchased by a subscriber or group is event initiator, the credit floor of the subscriber or group is increased by the granted amount. If the offer is canceled, the credit floor of the subscriber or group is decreased by the canceled amount.

If notifications are enabled for balance thresholds, each time a usage or non-usage threshold is triggered, MATRIXX Engine generates a threshold notification (MtxBalanceThresholdNotification). To deliver notifications only when charging for usage, you can identify and filter out notifications of thresholds generated during non-usage rating using the ThresholdTrigger field in the MtxBalanceThresholdNotification MDC. For information about the ThresholdTrigger field, see the discussion about MtxBalanceThresholdNotification in MATRIXX Integration. To filter out non-usage events (for example, an offer cancelation), you can create a filter and add it to the notification type group_balance_threshold or subscriber_balance_threshold in My MATRIXX. For information about notification type filters, see the discussion about notification type filters in My MATRIXX Help. For information about adding a filter to a notification type, see the discussion about customizing a notification type in My MATRIXX Help.

If Report Highest Threshold Breaches Only is selected on a balance or meter template, only the highest threshold breach is reported in events and notifications.

The engine reports the highest threshold breach on a per-message basis. Therefore, a SubMan multi-request (MtxRequestMulti) might still evoke multiple recorded breaches, but only the highest for each individual component request is reported.

If multiple thresholds are triggered by the same message on the same balance amount, the last processed threshold is the one reported.

For example, if a prepaid balance of -100 units has the following thresholds:
  • A fixed threshold at -50
  • A percentage threshold at 50%
Then usage of 50 units triggers both thresholds, but only the last one processed is reported.

For more information, see the discussions about configuring balance template general properties and configuring meter template general properties in My MATRIXX Help.

Threshold Retriggering

A change to a threshold creates a change to the balance or meter on which it is set. In My MATRIXX, you can define how often you want threshold notifications and events for the same threshold to be triggered during a cycle:
  • No cycle (default)
  • Owning balance or meter cycle
  • Billing cycle
Threshold event and notification retriggering can be independently configured on a per-cycle basis. If you select Unlimited (the default value), notifications and events are triggered each time the threshold is crossed during a cycle. If you select Once Per Cycle, notifications and events are triggered the first time the threshold is crossed during a cycle. Subsequent threshold crossings do not trigger notifications and events. If Once Per Cycle is selected, select the period over which the notification/event is retriggered:
  • Balance Cycle Aligned — The cycle used for retriggering notifications/events is aligned with the balance cycle.
    Note: This option is not available on simple balances.
  • Billing Cycle Aligned — The cycle used for retriggering notifications/events is aligned with the billing cycle.
  • No Cycle — The Unlimited or Once Per Cycle selection in Threshold Cycle Notification Limit/Threshold Cycle Event Limit applies over the balance lifetime.

At purchase time, you can override and restore the threshold configuration by extending the SubMan Threshold Add/Remove APIs, for example, MtxRequestSubscriberAddThreshold.

For more information about threshold notification and event options, see the discussions about balance template threshold properties and meter template threshold properties in My MATRIXX Help.
Note: Notification and event history is only recorded when the frequency selection is Once Per Cycle in Threshold Cycle Notification Limit/Threshold Cycle Event Limit. Therefore, if a mid-cycle SubMan API override changes the Unlimited setting to Once Per Cycle, then one further notification/event for the threshold might be generated during the cycle; this is recorded to suppress further notifications and events for that threshold in the cycle.

Thresholds Based on Consumed and Available Amounts

In addition to defining a threshold based on a balance amount (Balance Amount threshold type), you can also define a threshold based on a consumed or available amount.

  • Consumed Amount threshold type — The threshold is based on the quantity of a balance or meter being used from the credit floor towards the credit limit.
  • Available Amount threshold type — The threshold is based on the quantity of a balance or meter remaining from the credit limit towards the credit floor.

Similar to the balance amount threshold type, the consumed amount and available amount threshold types can be expressed as a single value, a range, or a percentage.

Thresholds for Prepaid G/L Balances

The thresholds set on a prepaid G/L balance can be absolute values or percentages, and the amount represents the remaining balance-amount before the credit limit is reached. For example, you can set an absolute threshold of -50 to warn subscribers they only have 50 credits left or at 5% when they only have 5% of their balance amount remaining. Pricing administrators must set absolute thresholds on prepaid G/L balances as negative numbers and percentage thresholds on prepaid G/L balances as positive numbers. The percentage threshold is calculated by using the sum of all grants to that balance (the credit floor) and taking the percentage from that value. So, if a prepaid periodic G/L balance is granted 300 minutes per month, that month's balance entry starts from the credit floor of -300. If there is a 10% threshold on that balance entry, it is triggered at 30 minutes remaining (balance amount is 30). The threshold limit is always the absolute value of the credit floor. For example, if a balance is granted 300 minutes, the credit floor is -300. Therefore, the threshold limit is set at 300.
Note: Threshold notifications are triggered when the threshold is crossed. Prepaid percentage-based thresholds are a percentage of the credit floor, so when the credit floor hits zero (0), the threshold is skipped; because the credit floor is equal to the credit limit (0), there can be no percentage threshold.

Pricing administrators must set percentage thresholds on prepaid G/L balances as positive numbers in My MATRIXX.

Thresholds for Postpaid G/L Balances, Virtual Balances, and Meters

The thresholds set on a postpaid G/L balance, virtual balance, or meter can be absolute values or percentages, and the amount represents the used balance amount before the credit limit is reached. For example, you can set a threshold of 90% on a meter tracking a group balance to alert administrators the group usage is nearing the limit. If the credit limit on the group's postpaid meter is 300, when the balance amount equals $270, a notification is sent.

For virtual balances, the threshold limit is the minimum of all threshold limits set in the aggregation hierarchy, from the point of query to the root of the group. For example, if a group member has a threshold limit of infinity, its parent group has a threshold limit of 500, and the root group has a threshold limit of 600, the group member's threshold limit is set to 500. For prepaid group G/L balances, the virtual balances (which are always postpaid) are created with an unlimited credit limit, and for postpaid group G/L balances the virtual balances are created with the same credit limit as the group's G/L balance. Administrators can change the credit limit on a virtual balance.

If Event Enabled is selected on a balance template threshold, each time a threshold is reached or crossed, an MtxBalanceThresholdEvent event is generated. To override the Event Enabled attribute, use the following SubMan APIs:
  • MtxRequestSubscriberAddThreshold
  • MtxRequestGroupAddThreshold

Whenever an AddThreshold or RemoveThreshold SubMan API is called to add, modify, or remove a threshold for a subscriber or group, an MtxBalanceThresholdModifyEvent event is generated.

You can use the MtxRequestSubscriberAddThreshold and MtxRequestGroupAddThreshold SubMan APIs to override new threshold history configuration data details in My MATRIXX for a subscriber or group addressed by the SubMan request. These requests contain the MDC structure MtxThresholdData.

For more information about configuring a balance template threshold and overriding the threshold history configuration data details, see the discussion about configuring balance template thresholds in My MATRIXX Help. For more information about the Event Enabled attribute, see the discussions about MtxThresholdData and MtxThresholdInfo in MATRIXX Subscriber Management API. For more information about the AddThreshold and RemoveThreshold SubMan APIs, see the discussions about MtxRequestSubscriberAddThreshold, MtxRequestGroupAddThreshold, MtxRequestSubscriberRemoveThreshold, and MtxRequestGroupRemoveThreshold in MATRIXX Subscriber Management API.

Threshold-Triggered Auto Recharge

Using the SubMan APIs, you can configure a balance instance with a threshold that triggers an auto recharge request. For example, when a subscriber's prepaid main balance with a $5 threshold is triggered (the prepaid main balance drops below $5), a $50 recharge to the prepaid main balance is requested. For more information about threshold-triggered auto recharge, see the discussion about threshold-triggered auto recharge in MATRIXX Pay Now.