Balance State Update Components

A balance state update component implements the business logic that decides which balance state update profile to select during rating for a given set of normalization parameters. This enables the end date of a simple or periodic G/L balance (not virtual) to be modified according to the rules in the balance state update profile. A balance state update component can be applied during product offer purchase, during usage-triggered auto-renewal, or when scheduling suspend or resume operations.

The balance state update component contains one or more balance state update tables that use decision tables to map normalization parameters to result values. The result can be a balance state update profile or a SKIP value. When a SKIP value is selected, the next decision table in the component is examined. When a balance state update profile is selected, the Charging Server modifies the end time of the identified balance by using the rules defined in the profile to either extend an amount of time from the existing end time or from now. For example, you might have a decision table that uses a purchased quantity field in a custom PurchasedOffer MDC to select a balance state update profile:
  • If the purchased quantity is less than 50, select profile 1, extend 2 weeks from now.
  • If the purchased quantity is between 50 and 100, select profile 2, extend 4 weeks from now.
  • If the purchased quantity is between 100 and 200, select profile 3, extend 6 weeks from now.

The extension is performed before rating occurs, so the G/L balance instance can be impacted by the associated pricing if it has already expired. This also enables the balance quantity that was added at purchase time to be available for a longer period of time.

Note: If the balance state update profile calculates a date earlier than the current balance end time and the Reduction Policy in the balance state update component is set to Allow Reduction Up To Now, the current balance is adjusted to the new reduced end time (the end time cannot be set to the past). If the balance state update profile calculates a date earlier than the current balance end time and the Reduction Policy in the balance state update component is set to Deny Reduction, the current balance end time does not change.

Multiple balance state update components can be assigned to a product offer, including to the same balance (two or more updates to the same class, same template, or one or more updates to the class and template) and application (two or more updates for purchase or auto-renew). If one of the balance state update components in an offer cannot be successfully applied (for example, if none of the balance instances specified in the matrix is found, or no balance state update profile is selected), an error is returned, and the offer purchase is canceled. If the failed offer is part of a bundle, then the bundle purchase is canceled.

If the same balance instance is updated by multiple balance state update components, the final balance validity end time is not guaranteed because the order in which pricing components are applied is not fixed.

If the balance state update component is configured for auto-renew, the balance-state update is applied before auto-renew charges, discounts, and grants.

You limit the amount of extension by configuring a balance extension limit for balance state update components using the My MATRIXX interface. Note the following points about limiting the amount of extension that can be applied to a balance:
  • Balance state update components include an optional limit (cap) for balance instance end time, relative to the time the component is evaluated, for example, during a purchase or auto-renewal.
  • The relative time includes all currently supported period quantities (for example, 2 weeks, 30 days, and so on).
  • When the extension limit is exceeded, you can optionally choose to allow the operation to proceed with the limited extension quantity or fail the extension (which would fail a purchase and make an auto-renewal non-applicable).
  • The regularly calculated balance extension time and the evaluated extension limit time both utilize the TimeAdjustType policy from the balance state update profile. Consider the following example.

    A balance currently expires at a future time: 2020-10-12T20:00:00. During a one-time purchase or auto-renewal which is executed as the balance is expiring, a balance state update component is selected which features an extension limit of 1 day and allows restricted balance extension. It references a balance state update profile which extends 30 hours and has a TimeAdjustType policy of adjusting the end time to midnight. Without the balance state update component's limitation settings, the balance would have been extended to 2020-10-15T00:00:00. This includes the impact of the adjust to midnight policy. However, the limitation policy of 1 day on the balance state update component sets the extension limit as 2020-10-14T00:00:00, also utilizing the adjust to midnight TimeAdjustType policy from the selected balance state update profile, rather than setting the new balance end time to 2020-10-13T20:00:00, exactly one day from the time of extension.

If a product offer identifies a required tier balance, and that tier is specified as the target in a balance state update component, that balance instance is always selected for the balance class or template if one is associated with that offer. If a tier is not specified in a balance state update component, the group at the specified tier is selected and its local wallet is evaluated for possible balance class or template matches. For more information about required tier balances, see the discussion about product offer required tier balances in MATRIXX Pricing and Rating. For details about creating tiers, see the discussion about adding a field to a pricing plan.