Status Conditions

Transition conditions determine when an automatic transition to a new status occurs. For example, after 30 days without activity, cause a transition to the Inactive status.

For transitions caused by user activity (balance transfer, balance top-up, balance adjust), a balance transition condition can include a balance class and optionally a balance. For balance transition conditions, the following rules apply:
  • If you only specify a balance class, any balance belonging to that balance class can trigger the condition.
  • If you specify a balance class and a balance, only balances that match the balance template can trigger the condition.
For transitions with the following conditions that impact product offers and bundles, you must specify a product offer or bundle. If you specify a catalog item, pricing validation fails.
  • MtxStatusConditionPurchase
  • MtxStatusConditionInactivityPurchase

Multiple conditions can be defined for the same transition. If any of the status transition's conditions are true, the transition occurs. For example, the transition from status New to status Active includes both the MtxStatusConditionBalanceTopup and MtxStatusConditionBalanceTransferFrom conditions. If either of these conditions are true, the transition occurs.

The following sections describe the transition conditions.
Note: Only the MtxStatusConditionInactivity condition applies to users.

MtxStatusConditionBalanceAdjust

The MtxStatusConditionBalanceAdjust condition triggers when a balance adjustment occurs. The MtxStatusConditionBalanceAdjust condition is defined with the fields in MtxStatusConditionBalanceAdjust Options.
Table 1. MtxStatusConditionBalanceAdjust Options
Field Description
Balance Class Specifies a balance class to track. The default is United States dollar.
Balance Specifies a balance to track. If this field is not set, then the condition applies to all balance templates associated with the defined Balance Class.

MtxStatusConditionBalanceExpiration

The MtxStatusConditionBalanceExpiration condition is triggered both when balances are becoming expired and if they are already expired. For both simple and periodic balances, the balance's EndTime is checked to decide if the condition should be triggered. If multiple instances of a balance exists, the balance instance with the latest EndTime is selected (the transition occurs when all matching balances have expired).

If multiple MtxStatusConditionBalanceExpiration conditions are specified (with different delay periods), the following algorithm is used:
  1. The Charging Server evaluates all the MtxStatusConditionBalanceExpiration conditions defined within one single status transition. The MtxStatusConditionBalanceExpiration condition that has latest (maximum) EndTime is used as the calculated transition time per status transition object.
  2. The calculated transition time (as determined by Step 1) for each status transition object defined for an object status are compared. The earliest (minimum) transition time is used for the object.
Note: This algorithm is stateless with respect to previous state transitions. Therefore, if an object transitions from Status A to Status B due to balance expiration condition, transitioning back to Status A will result in a transition back to Status B unless the EndTimes of the balance instances in the balance expiration condition are updated such that they are no longer expired.
For example:
  1. Status A has two transitions, one to Status B and another to Status C.
    • The transition to Status B has two balance expiration conditions: when Balance 1 expires and when Balance 2 expires.
    • The transition to Status C has one balance expiration condition: when Balance 3 expires.

    No transition takes place until all the balances within a single transition have expired.

  2. The balances expire as follows:
    • Balance 1: 2021-01-01
    • Balance 2: 2021-02-01
    • Balance 3: 2021-03-01
  3. All the balance expiration conditions are compared within each status transition object. For the transition to Status B, which has two balance expiration conditions, the latest (maximum) EndTime is 2021-02-01.
  4. For each status transition object defined for an object status, the calculated transition times are compared.
    • The calculated transition time for transitioning to Status B is 2021-02-01.
    • The calculated transition time for transitioning to Status C is 2021-03-01.
    Therefore, the object transition to Status B because it has the earliest (minimum) transition time.

Balance auto expiration can be used to trigger status life cycle transitions and send notifications when the balance amount is gone. You configure auto expiration by setting a property in the balance template.

Auto expiration can occur on any operation that debits a balance. For example:
  • Usage charges
  • Balance adjustments
  • Balance forfeitures
  • Non-usage charges
For simple, prepaid G/L balances, a balance instance can be configured to expire immediately when the balance amount has been completely consumed, rather than waiting until the balance end date expires. For example, balances can auto expire when a balance is fully consumed by a balance transfer operation. This feature can be used with automatic life cycle transitions at balance expiration time to transition a device, subscription, or group to a new status. This status transition will take place during the next recurring processing scan. The Balance Auto Expires field must be selected in the balance template. For more information about balance templates, see the discussion about balance templates in My MATRIXX Help.
The MtxStatusConditionBalanceExpiration condition is defined with the fields in MtxStatusConditionBalanceExpiration Options.
Table 2. MtxStatusConditionBalanceExpiration Options
Field Description
Balance Class Specifies a balance class to track. The default is United States dollar.
Balance Specifies a balance to track. If this field is not set, then the condition applies to all balance templates associated with the defined Balance Class.
Delay Period Count Indicates the number of delay period units for the time interval between recurring failure and the state transition. The transition is delayed from the time of the failure.
Important: If recurring processing succeeds before the delay time expires, the transition does not occur.
Delay Period Unit Indicates the unit for the Delay Period Count. Possible units are:
  • days (1, default)
  • weeks (2)
  • months (3)
  • years (4)
  • hours (5)
  • minutes (6)

MtxStatusConditionBalanceTopup

The MtxStatusConditionBalanceTopup triggers when a balance topup occurs. The MtxStatusConditionBalanceTopup condition is defined with the fields in MtxStatusConditionBalanceTopup Options.
Table 3. MtxStatusConditionBalanceTopup Options
Field Description
Balance Class Specifies a balance class to track. The default is United States dollar.
Balance Specifies a balance to track. If this field is not set, then the condition applies to all balance templates associated with the defined Balance Class.

MtxStatusConditionBalanceTransferFrom

The MtxStatusConditionBalanceTransferFrom condition triggers when a balance transfer occurs from the specified balance template or balance class. The MtxStatusConditionBalanceTransferFrom condition is defined with the fields in MtxStatusConditionBalanceTransferFrom Options.
Table 4. MtxStatusConditionBalanceTransferFrom Options
Field Description
Balance Class Specifies a balance class to track. The default is United States dollar.
Balance Specifies a balance to track. If this field is not set, then the condition applies to all balance templates associated with the defined Balance Class.

MtxStatusConditionFirstActivity

The MtxStatusConditionFirstActivity conditions is triggered when the specified first activity occurs.

If the specified first activity is offer_purchase, then the condition triggers after the offer is purchased.

The MtxStatusConditionFirstActivity condition is defined with the fields in MtxStatusConditionFirstActivity Options.
Table 5. MtxStatusConditionFirstActivity Options
Field Description
Status Activity Type Operations that are considered activity. Select the type of activity to trigger automatic transition.
Note: The usage activity is only an option for devices.
For more information about the Status Activity Type, see the discussion about status activities.

MtxStatusConditionInactivity

The MtxStatusConditionInactivity condition is triggered by the absence of specified actions within a specified inactivity period. The inactivity period is compared to the difference between the LastActivityTime and the current time. If the difference is greater that the inactivity period, the state transition occurs. The LastActivityTime is updated each time a defined status activity is occurs. The StatusConditionInactivity condition is defined with the fields in MtxStatusConditionInactivity Options.
Table 6. MtxStatusConditionInactivity Options
Field Description
Inactivity Count Indicates the number of units of inactivity before the condition automatically triggers the transition. The Inactivity Count is exact and is never rounded up.
Important: Currently, for device objects, transitions due to inactivity require that the device is associated with a subscription.
Inactivity Unit Indicates the unit for the Inactivity Count. Possible units are:
  • days — 1 (default)
  • weeks — 2
  • months — 3
  • years — 4
  • hours — 5
  • minutes — 6

An object that has been inactive for the period of time defined in the Inactivity Unit transitions to the defined status and any actions allowed for that status are applied.

Status Activity Type Operations that are considered activity. Select the type of activity to trigger automatic transition.
Note: The usage activity is only an option for devices.
For more information about the Status Activity Type, see the discussion about status activities.

MtxStatusConditionInactivityPurchase

The MtxStatusConditionInactivityPurchase condition is triggered by the absence of an offer or bundle purchase within a specified inactivity period. The inactivity period is compared to the difference between the LastActivityTime and the current time. If the difference is greater that the inactivity period, the state transition occurs. If an offer or bundle is not defined, all purchases qualify as an activity which updates the LastActivityTime. A single LastActivityTime value is tracked for all inactivity triggers on all transitions. For example, if a status life cycle is defined to transition an object to Suspended if a recharge does not occur within 30 days and to transition to Terminated if a purchase does not occur within 60 days, the object will never transition to Terminated because Suspended will always occur first.

The MtxStatusConditionInactivityPurchase condition is defined with the fields in MtxStatusConditionInactivityPurchase Options.

Table 7. MtxStatusConditionInactivityPurchase Options
Field Description
Offer/Bundle A list of offer or bundle IDs. Select an offer or bundle ID to track from the drop-down menu and click Add.
Inactivity Count Indicates the number of units of inactivity before the condition automatically triggers the transition. The Inactivity Count is exact and is never rounded up.
Important: Currently, for device objects, transitions due to inactivity require that the device is associated with a subscription.
Inactivity Unit Indicates the unit for the Inactivity Count. Possible units are:
  • days — 1 (default)
  • weeks — 2
  • months — 3
  • years — 4
  • hours — 5
  • minutes — 6

An object that has been inactive for the period of time defined in the Inactivity Unit transitions to the defined status and any actions allowed for that status are applied.

MtxStatusConditionPayment

The MtxStatusConditionPayment triggers when a payment is made to a subscription or group postpaid main balance. The MtxStatusConditionPayment condition is defined with the fields in MtxStatusConditionPayment Options.
Table 8. MtxStatusConditionPayment Options
Field Description
Balance Class Specifies a balance class to track. The default is United States dollar.
Balance Specifies a balance to track. If this field is not set, then the condition applies to all balance templates associated with the defined Balance Class.

MtxStatusConditionPeriodExpiration

The MtxStatusConditionPeriodExpiration triggers when a specific date and time occurs that is defined as when to transition to a new status. When the Charging Server estimates the next status transition time, notifications before and after the status change are sent, and the automatic status transition is performed.
Note: This condition is only valid when the specified date/time value is greater than the status object's CurrentStatusTransitionTime.
The MtxStatusConditionPeriodExpiration is defined with the fields in MtxStatusConditionPeriodExpiration Options.
Table 9. MtxStatusConditionPeriodExpiration Options
Field Description
Container Indicates the name of the MDC containing the field where the date/time to transition to the new status is stored. 
Field Indicates the custom MDC field that contains the date/time to transition to the new status. The specified MDC field must have a data type of DATETIME. This field can be modified by either calling the subscription, group, or device Modify SubMan APIs or by using object state update profiles and offer owner state update components. For more information, see the discussion about object state update profiles and offer owner state update components. For more information about product offer REST APIs, see MATRIXX Subscriber Management API.

MtxStatusConditionPurchase

The MtxStatusConditionPurchase condition triggers after an offer or bundle is purchased. If the purchased offer or bundle matches the offer or bundle defined in the status condition, the status transitions after the defined offer or bundle is purchased. If no offer or bundle is defined in the status condition, the status transitions after any offer or bundle is purchased.

Filters specified for this condition have access to the fields of the purchased offer/bundle. If any of these filter checks pass, the status condition is met. The status condition filters are checked against each purchased offer/bundle as follows:
  • When an offer/bundle is specified, the system only checks against the specified item.
  • When an offer/bundle is not specified, the system checks against items that are directly purchased as part of the transaction. Offers that are purchased resulting from a purchased bundle are not checked.
The MtxStatusConditionPurchase condition is defined with the field in MtxStatusConditionPurchase Options.
Table 10. MtxStatusConditionPurchase Options
Field Description
Offer/Bundle The offer or bundle that triggers the condition when purchased. Select an offer or bundle from the drop-down menu and click Add.

MtxStatusConditionRecharge

The MtxStatusConditionRecharge triggers when a recharge is made to a subscription or group prepaid main balance. The MtxStatusConditionRecharge condition is defined with the fields in MtxStatusConditionRecharge Options.
Table 11. MtxStatusConditionRecharge Options
Field Description
Balance Class Specifies a balance class to track. The default is United States dollar.
Balance Specifies a balance to track. If this field is not set, then the condition applies to all balance templates associated with the defined Balance Class.

MtxStatusConditionRecurringFailure

In My MATRIXX, you can specify that the trigger for a recurring component is a balance cycle, billing cycle, or purchased item cycle. Purchased item recurring processing succeeds if all the components in the product offer or bundle that are triggered by a purchased item cycle can be applied. For information about recurring price components, see the discussion about price components in My MATRIXX Help.

The MtxStatusConditionRecurringFailure triggers when recurring processing fails for a billing cycle, balance cycle, or purchased item cycle.
  • For billing and balance cycles, recurring failure only works with subscriptions and groups.
  • For purchased item cycles, recurring failure works with the owner of the offer. If a subscription owns the offer, the subscription's status is updated. If a group owns the offer, the group's status is updated. If a device owns the offer, the device's status is updated.
The MtxStatusConditionRecurringFailure is defined with the fields in MtxStatusConditionRecurringFailure Options.
Table 12. MtxStatusConditionRecurringFailure Options
Field Description
Cycle Type Specifies whether the condition is for the billing cycle, a set of balance cycles, or a purchased item cycle. The values are:
  • 1 — balance_cycle

    If balance cycle is specified, the condition includes an array of one or more balance types. The condition is true if any of the balance cycles that failed matches a balance type in the array. Each element in the array can be a single balance template, or can specify an entire balance class.

  • 2 — billing_cycle
  • 3 — purchased_item_cycle
    Note: If defining a device life cycle, only purchased_item_cycle is available for selection.

    If purchased item cycle is specified, the condition can include a product offer or bundle specified by Offer/Bundle.

Balance Class This is set only if the cycle type is balance cycle. Specifies a balance class to track. The default is United States dollar.
Balance This is set only if the cycle type is balance cycle. Specifies a balance to track. If this field is not set, then the condition applies to all balance templates associated with the defined Balance Class.
Offer/Bundle This is set only if the cycle type is purchased item cycle. The product offer or bundle name. If this field is set, the condition applies only to purchased catalog items that directly reference the product offer or bundle name. If not set, the condition applies to all purchased items with cycles.
Delay Period Count Indicates the number of delay period units for the time interval between recurring failure and the state transition. The transition is delayed from the time of the failure.
Important: If recurring processing succeeds before the delay time expires, the transition does not occur.
Delay Period Unit Indicates the unit for the Delay Period Count. Possible units are:
  • days (1, default)
  • weeks (2)
  • months (3)
  • years (4)
  • hours (5)
  • minutes (6)

MtxStatusConditionRecurringSuccess

The MtxStatusConditionRecurringSuccess triggers when recurring processing is successful.
  • For billing and balance cycles, recurring success only works with subscriptions and groups.
  • For purchased item cycles, recurring success works with the owner of the offer. If a subscription owns the offer, the subscription's status is updated. If a group owns the offer, the group's status is updated. If a device owns the offer, the device's status is updated.
The MtxStatusConditionRecurringSuccess is defined with the fields in MtxStatusConditionRecurringSuccess Options.
Table 13. MtxStatusConditionRecurringSuccess Options
Field Description
Cycle Type Specifies whether the condition is for the billing cycle, a set of balance cycles, or a purchased item cycle. The values are:
  • 1 — balance_cycle

    If balance cycle is specified, the condition includes an array of one or more balance types. The condition is true if any of the balance cycles that succeeded led matches a balance type in the array. Each element in the array can be a single balance template, or can specify an entire balance class.

  • 2 — billing_cycle
  • 3 — purchased_item_cycle
    Note: If defining a device life cycle, only purchased_item_cycle is available for selection.

    If purchased item cycle is specified, the condition can include a product offer or bundle specified by Offer/Bundle.

Balance Class This is set only if the cycle type is balance cycle. Specifies a balance class to track. The default is United States dollar.
Balance This is set only if the cycle type is balance cycle. Specifies a balance to track. If this field is not set, then the condition applies to all balance templates associated with the defined Balance Class.
Offer/Bundle This is set only if the cycle type is purchased item cycle. The product offer or bundle name. If this field is set, the condition applies only to purchased catalog items that directly reference the product offer or bundle name. If not set, the condition applies to all purchased items with cycles.

MtxStatusConditionUsage

The MtxStatusConditionUsage triggers when there is usage. The MtxStatusConditionUsage is defined with the fields in MtxStatusConditionUsage Options.
Table 14. MtxStatusConditionUsage Options
Option Description
TriggerIfNoQuotaRequest The transition is triggered when no usage is reported, and no quota is requested (such as when a Gy CCR-I is received with no contexts).
Note: If the transition is not triggered, the charging session is still created.
TriggerIfNoQuotaGrant The transition is triggered when no usage is reported, quota is requested, and no quota is granted because there is no credit.
Note: If any amount of quota can be granted for any MSCC context in the request, then the transition proceeds regardless of whether the full amount is granted for all contexts.