Managing Granted Allowances

18 Managing Granted Allowances

You can configure how Oracle Communications Elastic Charging Engine (ECE) manages allowances granted to customers.

Topics in this chapter:

Processing Granted Allowances Before Applying Usage Charges

ECE processes a customer's granted allowances and usage charges in the order they appear in the product offerings defined in PDC. For example, assume you configure a product offering in Pricing Design Center (PDC) that grants 5 GB of free data per month and then charges $5 per additional GB of data. If a customer purchases the product offering and uses 8 GB of data in a month, ECE would first consume the 5 GB of free data and then apply a $15 charge for the remaining 3 GB of data usage.

To configure charges in PDC to process granted allowances before applying usage charges, see "Configuring Pricing to Consume Granted Allowances Before Charging" in PDC Creating Product Offerings.

About Automatically Renewing Granted Allowances

A renewable offer grants specific resource for a fixed period. For example, it could grant a data allowance for one month. Once the resource is fully consumed, it automatically renews according to predefined settings, if automatic renewals are enabled in PDC.

For example, you can create an auto-renewal offer that grants 2 GB of data for $10, which can automatically renew up to two times in a single day of usage. In this case, the data would be charged as follows:

The customer pays $10 and receives the first 2 GB of data.
After consuming the first 2 GB, the customer is charged another $10 and receives an additional 2 GB.
After consuming the second 2 GB, the customer is charged a further $10 and receives the final 2 GB.
If the customer consumes all 6 GB, no additional data is granted, and the customer is not charged further, as the maximum number of renewals has been reached.

For more information, see "Automatically Renewing Granted Allowances" in PDC Creating Product Offerings.

Note:

When you create a pricing tier in PDC, ensure that each tier is set to renew automatically. See "Automatically Renewing Granted Allowances" in PDC Online Help and "Configuring the Automatic Renewal of Allowances" in PDC Creating Product Offerings for more information.

About Allowance Renewals

The way ECE processes automatically renewable offers differs between online and offline charging. See the following:

About Allowance Renewals During Online Charging

ECE manages the automatic renewal of granted allowances during the authorization process for online charging as follows:

PDC shares the validity of renewalResource and replicates it across other impacts for renewable tiers.
When a customer purchases a package that includes an automatically renewable allowance, ECE creates a tracker balance for the current cycle. This tracker balance includes:
- The Consumption amount: The volume the user must consume before receiving a new allowance, such as 1 GB.
- The Renewal tracker amount: The number of times the allowance can be granted to the customer, such as three times.
During the charging process, ECE checks if the following conditions apply:
- The allowance is configured for automatic renewal.
- The customer consumed the granted amount during the session.
- The allowance can be granted to the customer again.
If all of these conditions are met, ECE automatically renews the granted allowance for the customer.

Note:

If the consumption amount is exceeded at the end of a session, ECE does not grant a new allowance within that session. Instead, the new allowance is granted at the start of the next session.

To configure ECE to perform automatic renewals during online charging:

Configure ECE to automatically grant allowances. See “Configuring Granted Allowances”.
(Optional) Configure ECE to generate notifications when automatic renewals occur. See “Enabling Notifications for Automatically Renewed Granted Allowances”.

About Allowance Renewals During Offline Charging

Oracle Communications Offline Mediation Controller processes CDRs from your network devices, converts them, and sends them as usage requests to ECE for rating. ECE then manages automatic renewals of granted allowances during usage rating as follows:

ECE determines the rating mode in the received usage request. If it is offline, ECE proceeds to the next step.
ECE returns the original quantity to rate and grant Renewal Free Units (RFUs). If the total amount consumed is greater than the granted allowance, ECE renews the allowance.
ECE sets the new allowance's validity start date to the requestStartTime and leaves the end time unchanged. The requestStartTime is pulled from the usageRequest. For example, if the usage request was received on April 30 at 15:00, the allowance's validity start time is set to 2025-04-30T15:00:00.
ECE generates the rated output, generating two TERMINATE events: one for the grant (and any associated charge) and one for the consumption. ECE only splits the rated events if it has granted any renewal, recurring, or non-counter grant when processing an offline usage request.
ECE completes rating and applies charges using the renewed balances.

Note:

Out-of-sequence CDRs can trigger duplicate reload attempts or fallback to PayGo, which can cause duplicate reloads or incorrect charging. To prevent this, implement ordering and ingestion controls.
You cannot re-rate events for offline allowance renewals.

Configuring Automatic Renewals

Use the following process to set up automated renewals:

(Offline only) Configure Offline Mediation Controller to automatically renew granted allowances. See "Setting Up Automatic Renewals for Offline Charging".
Configure ECE to automatically grant allowances. See “Configuring Granted Allowances”.
(Optional) Configure ECE to generate notifications when automatic renewals occur. See “Enabling Notifications for Automatically Renewed Granted Allowances”.

Setting Up Automatic Renewals for Offline Charging

To set up your system to automatically renew granted allowances during offline charging, in Offline Mediation Controller, indicate the CDR is for offline charging by setting REQUEST_MODE_TYPE to OFFLINE. in your NPL rule file.

You do not have to set up configurations to automatically renew granted allowances during online charging.

Configuring Granted Allowances

To configure ECE to automatically renew granted allowances for online and offline charging, set the following ECE Configuration MBeans. You can set these attributes using the charging-settings.xml file, a JMX editor, or your override-values.yaml file for oc-cn-ece-helm-chart.

nonLinearRating = true
tariffTimeChangeSupported = true
checkUsedUnitsAfterFUI = false
enableFuiForInitiate = true
alignRecurringImpactsToOffer = true
reverseRateUseAllBalances = false
failBalanceUpdatesOnCreditCeilingBreach = true
remainingBalanceCalcMode = CURRENT_BALANCE
grantRenewalDuringAuthorization = true
rolloverConsumptionRule = ALWAYS_FIRST
saveNonCounterGrantDuringOngoingSession = true
rateZeroQuantity = false

Enabling Notifications for Automatically Renewed Granted Allowances

You can configure ECE to send notifications when an allowance is automatically renewed or fully consumed. This keeps downstream systems updated in real time. For example, ECE may send a notification such as "Renewal 3 of 5 triggered" with relevant details. When all renewals are used, another notification is sent summarizing the total renewals consumed.

To enable these notifications for both online and offline charging, set the following ECE Configuration MBeans using the charging-settings.xml file, a JMX editor, or your override-values.yaml file for oc-cn-ece-helm-chart:

Set renewalGrantActivationNotificationMode to ASYNCHRONOUS. See "Enabling Specific Notification Types".
Set enableFuiForInitiate to true.

By default, the notification includes the message "Reload x out of y", where x is the number of reloads that have been granted and y is the maximum number of renewals allowed. You can customize the message included in the notification by using the ECE post-charging extension. You can use the ECE_home/ocecesdk/source/oracle/communication/brm/charging/sdk/extensions/SamplePostChargingExtension ECE SDK sample program as a starting point. For more information, see "Post-Charging Extension – Modifying the Renewal Message".

The following shows a sample renewable grant notification:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Notification version="1.0.0.0.0">
   <RenewalGrantActivationNotification>
      <NotificationType>RENEWAL_GRANT_ACTIVATION_NOTIFICATION_EVENT</NotificationType>
      <BalanceId>12345678</BalanceId>
      <BalanceElementCode>RenewalResource</BalanceElementCode>
      <ActiveReservation>20.00</ActiveReservation>
      <ConsumedReservation>0</ConsumedReservation>
      <CurrentBalance>-40.00</CurrentBalance>
      <OriginalNumberOfReloadAvailable>5.0</OriginalNumberOfReloadAvailable>
      <CurrentNumberOfReloadAvailable>4.00</CurrentNumberOfReloadAvailable>
      <ValidFrom>2015-01-05T18:34:00Z</ValidFrom>
      <ValidTo>2015-02-01T08:00:00Z</ValidTo>
      <TotalGrantedAmount>-40.00</TotalGrantedAmount>
      <ReloadCharge>10.00</ReloadCharge>
      <DateOfGrant>2015-01-05T10:34-08:00</DateOfGrant>
      <OfferName>Renewable_Bundle_1</OfferName>
      <OfferId>3a914eeb-f330-4dcb-881f-12e351bfd8d3</OfferId>
      <PublicUserIdentity>123456789012</PublicUserIdentity>
      <ExtensionData>
         <Message>Reload 1.00 out of 5.0</Message>
      </ExtensionData>
   </RenewalGrantActivationNotification>
</Notification>

In the sample notification, <OriginalNumberOfReloadAvailable> is the maximum number of renewals allowed and <CurrentNumberOfReloadAvailable> is the number of renewals remaining for the customer.