Customizing Rating

22 Customizing Rating

You can use the Oracle Communications Elastic Charging Engine (ECE) extensions to customize BRM Gateway, Diameter Gateway, HTTP Gateway, RADIUS Gateway, pre-rating, post-rating, post-charging, and post-update processes. ECE extensions include sample implementations that guide you in implementing your custom business logic.

Caution:

Deploying charging for 5G with HTTP Gateway (5G CHF) requires a cloud native deployment of ECE and BRM components. The HTTP Gateway can be used only on an ECE cloud native system.

Topics in this document:

Operational Considerations

All pre-rating, post-rating, post-charging, and post-update extensions must be implemented in a single class respectively. This class can delegate to additional implementations if multiple extensions are being implemented.

Extensions data is loaded into a replicate cache in Coherence and the amount of data loaded into the cache must be taken into consideration when sizing for Java.

Configuring Extensions

You configure implementation classes for the diameter-request processing, HTTP-request processing, and usage-request processing extension points through JMX management by using a JMX editor.

To configure the implementation classes for the diameter-request processing, HTTP-request processing, and usage-request processing extension points:

Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the ECE Configuration node.
Expand charging.extensions.
Expand Attributes.
Specify values for the following attributes as needed:
- brmGwExtension
- diameterGyExtension
- diameterSyExtension
- httpExtension
- ocsBypassExtension
- postChargingExtension
- postRatingExtension
- postRatingMidSessionExtension
- postUpdateExtension
- preRatingExtension
- preRatingMidSessionExtension
- radiusAccountingExtension
- radiusAuthExtension
- ratingExtension

About Performance with Extensions

If extensions are activated, they are called for during every usage request. Always consider performance for the code you run in the extensions.

The extensions framework provides an extensions cache mechanism that provides the lowest latency access to the extensions data. It is recommended that you use the extensions cache mechanism rather than external data sources.

You can use the PerformanceMonitor MBean to monitor CPU usage of server nodes and client nodes. When building your charging extensions, the methods of the PerformanceMonitor MBean enable you to monitor the performance impacts of your extensions. For example, you can run ECE without your extensions and use the methods to see how much CPU time is used. You can then run ECE with your extensions, and use the methods again to see how much CPU time is used. By comparing the CPU times, you can derive the additional time spent by your extension.

About Logging in Extensions

Logging is available in your extensions. You use the Log4j logger to write messages to the server node log file. For example:

extensionContext.getLogger().debug("Hello World!" + extensionContext);

About Extension Exceptions

If ECE needs to reject a usage request, an ExtensionsException error can be thrown to reject the usage request and report a "CUSTOM_EXTENSION_ERROR" reason code in the response.

For details about ExtensionsException, see Elastic Charging Engine Java API Reference.

About Extension Security

To ensure security for the extension, follow these best practices:

Enable JMX security
Enable ECE cluster node security
Ensure strict governance of OS accounts
Follow secure Java coding practices
Implement string code review processes
Run latency-sensitive performance tests on the extensions hooks
Use JAR signing

Extension Points

You customize BRM Gateway, Diameter Gateway, HTTP Gateway, RADIUS Gateway, pre-rating, rating, post-rating, post-charging, and post-update processes with these extension points:

BRM Gateway Request Processing Extension Points

You use BRM Gateway request processing extension points to update an external notification that is bound for the BRM Gateway. It adds data for calling a specific BRM opcode. This allows you to update attributes in the ECE cache through the BRM-ECE synchronization process. See "About Synchronizing Data Between BRM and ECE".

ECE publishes the external notification to the ECE Notification topic, where it is retrieved by BRM Gateway. BRM Gateway uses the information in the notification to call the specified opcode, which in turn updates customer data in the BRM database. BRM then resynchronizes the customer data with the ECE cache.

BRM Gateway provides these extension points for external notification flows that are targeted for the BRM Gateway:

PostCharging extension. The role of the PostCharging extension is to retrieve data for a specific opcode.
BRMCustomOpCodeCall extension. The role of the BRMCustomOpCodeCall extension is to enrich external notifications with an input flist for a specific BRM opcode. This extension is called before the external notification is published to the ECE Notification topic.

Diameter-Request Processing Extension Points

Diameter Gateway provides extension points for Credit Control Request (CCR) and Credit Control Answer (CCA) flows:

RequestReceived extension. The role of the RequestReceived extension is to manipulate the CCR attribute-value pair (AVP) before the usage request is processed by Diameter Gateway and to provide an immediate response that bypasses the online charging system (OCS) completely.
PreProcessor extension. The role of the PreProcessor extension is to add or remove any AVP in the custom response before the usage request is processed by Diameter Gateway and to provide an immediate response that bypasses the OCS completely.
PreOCS extension. The role of the PreOCS extension is to manipulate the mapped ECE usage request payload and perform enrichment that is not possible in the RequestReceived extension.
PostOCS extension. The role of the PostOCS extension is to manipulate the CCA AVPs before the diameter response is returned to the diameter client.
OCSBypass extension. The role of the OCSBypass extension is to bypass the rating of Diameter CCRs received during a planned maintenance or an unplanned downtime of ECE and persist them to Oracle NoSQL.

Figure 22-1 shows the diameter-request processing extension points.

Figure 22-1 Diameter-Request Processing Extension Points

Description of "Figure 22-1 Diameter-Request Processing Extension Points"

HTTP Gateway Request Processing Extension Points

HTTP Gateway provides extension points for 5G flows:

RequestReceived extension. The role of the RequestReceived extension is to manipulate the charging data before the usage request is processed by HTTP Gateway and to provide an immediate response that bypasses the online charging system (OCS) completely.
PreOCS extension. The role of the PreOCS extension is to manipulate the mapped ECE usage request payload to perform enrichments that are not possible in the RequestReceived extension.
PostOCS extension. The role of the PostOCS extension is to manipulate the ECE usage request before the HTTP Gateway response is returned to the 5G client.
PostOCSBalanceQuery extension. The role of the PostOCSBalanceQuery extension is to manipulate the ECE usage response before the HTTP Gateway response is returned to the 5G client.

Figure 22-2 shows the HTTP Gateway request processing extension points.

Figure 22-2 HTTP Gateway Processing Extension Points

Description of "Figure 22-2 HTTP Gateway Processing Extension Points"

RADIUS-Request Processing Extension Points

RADIUS Gateway provides extension points for authentication and accounting flows.

Authentication Extension Points

RADIUS Gateway provides extension points for the authentication flow:

RequestReceived extension. The role of the RequestReceived extension is to add or update a custom AVP before the authentication request is processed by RADIUS Gateway and to provide an immediate response that bypasses the OCS completely.
CustomEAPChallenge extension. The role of the CustomEAPChallenge extension is to send custom access-challenge request to the RADIUS client when the Extensible Authentication Protocol (EAP) is used for authentication.
PreOCS extension. The role of the PreOCS extension is to perform any actions related to authentication that are required before the RADIUS request is sent to ECE.
CustomAuth extension. The role of the CustomAuth extension is to implement the custom EAP authentication methods.
CustomEncode extension. The role of the CustomEncode extension is to implement the custom hashing algorithm that is used on passwords during authentication when the Password Authentication Protocol (PAP) is used for authentication.
PostOCS extension. The role of the PostOCS extension is to add or update a custom AVP before the authentication response is returned to the RADIUS client.

Figure 22-3 shows the RADIUS-request processing extension points for EAP authentication.

Figure 22-3 Extension Points for EAP Authentication

Description of "Figure 22-3 Extension Points for EAP Authentication"

Figure 22-4 shows the RADIUS-request processing extension points for PAP and Challenge-Handshake Authentication Protocol (CHAP) authentication. The solid line depicts PAP authentication and the dotted line depicts CHAP authentication in this figure.

Figure 22-4 Extension Points for PAP and CHAP Authentication

Description of "Figure 22-4 Extension Points for PAP and CHAP Authentication"

Accounting Extension Points

RADIUS Gateway provides extension points for accounting flow:

RequestReceived extension. The role of the RequestReceived extension is to add or update a custom AVP before the accounting request is processed by RADIUS Gateway and to provide an immediate response that bypasses the OCS completely.
PreOCS extension. The role of the PreOCS extension is to enrich the usage request before the usage request is sent to ECE for accounting purposes.
PostOCS extension. The role of the PostOCS extension is to add or update a custom AVP before the accounting response is returned to the RADIUS client.

Figure 22-5 shows the RADIUS-request processing extension points for accounting.

Figure 22-5 Extension Points for Accounting

Description of "Figure 22-5 Extension Points for Accounting"

Update-Request Processing Extension Points

ECE provides an extension point for post-update extensions in the updates-processing flow. The role of the post-update extension is to enrich and filter external notifications. This extension is called after receiving update requests and before publishing the external notifications.

Usage-Request Processing Extension Points

ECE provides extension points in the rating flow: before charge calculation, after charge calculation (prior to making a balance impact), and after charging (after applying a balance impact).

Table 22-1 describes the role of each extension point in the rating flow.

Table 22-1 Rating Flow Extension Roles

Extension Point	Role
Pre-Rating Extension	Alter the usage request
Post Rating Extension	Alter the rated result
Rating Extension	Alter rated results after each of the following processes: rating, alteration, sharing, and taxation
Post-Charging Extension	Enrich the usage response

You cannot customize rating during the rating, alteration, and tax calculation processes, only before and after. Access is provided to a custom data store that provides low-latency access to data required for the extensions; for example, customer data and balance data.

Figure 22-6 shows the usage-request processing extension points.

Figure 22-6 Usage-Request Processing Extension Points

Description of "Figure 22-6 Usage-Request Processing Extension Points"

Implementing the Extensions Logic

The BRMCustomOpCodeCallExtension, DiameterGyExtension, DiameterSyExtension, HTTPExtension, PreRatingExtension, PostRatingExtension, PostChargingExtension, RadiusRequest, and RadiusResponse interfaces expose initialize() and shutdown() methods that are called by the hook framework when the server starts up and when it shuts down. Use these methods to configure your own internal data structures related to the extensions business logic.

For diameter-request processing extension points, a different method is called for each extension point.

handleRequestReceived(). Called for every CCR that is processed by the charging flow.
handlePreOCS(). Called for every CCR and usage request that is processed by the charging flow.
handlePostOCS(). Called for every CCA and usage response that is processed by the charging flow.

All methods expose relevant ExtensionContext data for accessing the ExtensionsDataRepository, AppConfigRepository, and other extensions-related contexts.

Figure 22-7 shows the data used in the diameter-request processing extension points.

Figure 22-7 Data Used in Diameter-Request Processing Extension Points

Description of "Figure 22-7 Data Used in Diameter-Request Processing Extension Points"

For HTTP-request processing extension points, a different method is called for each extension point.

handleRequestReceived(). Called for every charging data request that is processed by the charging flow.
handlePreOCS(). Called for every usage request that is processed by the charging flow.
handlePostOCS(). Called for every usage response that is processed by the charging flow.
handlePostOCSBalanceQuery(). Called for every usage response that is processed by the charging flow.

All methods expose relevant ExtensionContext data for accessing the ExtensionsDataRepository, AppConfigRepository, and other extensions-related contexts.

Figure 22-8 shows the data used in the HTTP-request processing extension points.

Figure 22-8 Data Used in HTTP-Request Processing Extension Points

Description of "Figure 22-8 Data Used in HTTP-Request Processing Extension Points"

For extension points that process requests from RADIUS clients, the RadiusRequest and RadiusReply interfaces are exposed to the extension points through the ExtensionContext methods.

For authentication-related extension points, the following methods are called by the authentication flow:

handleRequestReceived(). Called for every authentication request that is processed by the authentication flow.
handlePreOCS(). Called to perform any actions related to authentication that are required in the authentication flow.
handlePostOCS(). Called for each authentication response that is processed by the authentication flow.
handleCustomEAPChallenge(). Called to send custom access-challenge requests to the RADIUS client in the EAP authentication flow.
handleCustomAuth(). Called to implement a custom EAP authentication method in the authentication flow.
handleCustomEncode(). Called to implement the custom hashing algorithm that is used on passwords in the PAP authentication flow.

Figure 22-9 shows the data used in the RADIUS-request processing extension points for authentication.

Figure 22-9 Data Used in RADIUS-Request Processing Extension Points for Authentication

Description of "Figure 22-9 Data Used in RADIUS-Request Processing Extension Points for Authentication"

For accounting-related extension points, the following methods are called by the accounting flow:

handleRequestReceived(). Called for every accounting request that is processed by the accounting flow.
handlePreOCS(). Called for every accounting request and usage request that is processed by the accounting flow.
handlePostOCS(). Called for every accounting response and usage response that is processed by the accounting flow.

Figure 22-10 shows the data used in the RADIUS-request processing extension points for accounting.

Figure 22-10 Data Used in RADIUS-Request Processing Extension Points for Accounting

Description of "Figure 22-10 Data Used in RADIUS-Request Processing Extension Points for Accounting"

For usage-request processing extension points, the execute() method is called for every usage request, rated result, usage response, and notification that is processed by the charging flow.

For the rating extension point, the following methods are called by the charging flow:

handlePostApplyCharge(). Called to alter rated results after calculating charges (rating).
handlePostApplyAlteration(). Called to alter rated results after calculating discounts (alteration).
handlePostApplyDistribution(). Called to alter rated results after calculating charge distribution (sharing).
handlePostApplyTaxation(). Called to alter rated results after calculating taxes (taxation).

All methods expose relevant ExtensionContext data for accessing the ExtensionsDataRepository, AppConfigRepository, and other extensions-related contexts.

Figure 22-11 shows the data used in the pre-rating extension point.

Figure 22-11 Data Used in Pre-Rating Extension Point

Description of "Figure 22-11 Data Used in Pre-Rating Extension Point"

Figure 22-12 shows the data used in the rating extension point.

Figure 22-12 Data Used in Rating Extension Point

Description of "Figure 22-12 Data Used in Rating Extension Point"

Figure 22-13 shows the data used in the post-rating extension point.

Figure 22-13 Data Used in Post-Rating Extension Point

Description of "Figure 22-13 Data Used in Post-Rating Extension Point"

Figure 22-14 shows the data used in the post-charging extension point.

Figure 22-14 Data Used in Post-Charging Extension Point

Description of "Figure 22-14 Data Used in Post-Charging Extension Point"

ECE provides build and deployment capabilities in the form of shell scripts. If any third-party libraries need to be used inside the custom extensions logic, copy the third-party JAR files to the ECE_home/lib directory, where ECE_home is the directory in which ECE is installed. After the JAR files have been copied, they need to synchronize across to the other servers in the cluster. Synchronization is done by running the sync command in Elastic Charging Controller (ECC).

Custom extensions logic implementation classes that implement the GyExtension, PreRatingExtension, RatingExtension, PostRatingExtension, PostChargingExtension, RadiusRequest, and RadiusResponse interfaces and their dependencies must be packaged in JAR format. Ensure the packaged extensions JAR files are available to the ECE runtime environment in the ECE_home/lib directory.

BRMCustomOpCodeCall Extension

The BRMCustomOpCodeCall extension enriches external notifications with an input flist for a BRM opcode. The extension is called before publishing the external notification to the ECE Notification topic, where it will be retrieved by the BRM Gateway.

You can modify the external notifications to include an input flist for a different BRM opcode.

CustomAuth Extension

The CustomAuth extension implements custom EAP authentication methods; for example, EAP-POTP, EAP-PSK etc.

The extension can access this data:

EAP-Authentication-Request
System configuration

You can use a custom EAP authentication method if the RADIUS client does not support EAP-TTLS or EAP-MD5.

CustomEAPChallenge Extension

The CustomEAPChallenge extension sends a custom access-challenge request to the RADIUS client when custom EAP authentication mechanisms are used for authentication.

The extension can access this data:

Access-Challenge-Request
System configuration
Extensions data

You can use the extension point to send the custom access-challenge request to the RADIUS client when EAP is used for authentication.

CustomEncode Extension

The CustomEncode extension implements the custom hashing algorithm that is used on passwords for authentication.

The extension can access this data:

Encoded Password
System configuration
Extensions data

You can use the custom hashing algorithm on passwords for authentication. For example, typically the password from the RADIUS client is hashed (stored in the hash format) for PAP authentication. However, if the password is hashed in any other format, you implement the CustomEncode extension point to hash the incoming password.

OCSBypass Extension

The OCSBypass extension bypasses rating of CCRs received during ECE downtime or a planned maintenance activity. The CCRs are persisted to Oracle NoSql. When ECE is restored, the persisted requests are replayed to the ECE charging server for rating and updating balance impacts along with the real-time requests. The entire diameter request is accessible and modifiable and the entire request information is passed to the custom extension. When rating bypass is enabled and the custom extension is run, Diameter Gateway returns responses that you configured in the custom extension. If the extension is not enabled but bypassing of rating is enabled, ECE returns Diameter Result Code 5012 for the described conditions, which must be handled in your custom extension implementation.

PreOCS Extension

The PreOCS extension manipulates usage request payloads before the usage request is sent to ECE, so that the request can match the business requirement. In addition, the PreOCS extension performs any actions related to authentication that are required before the request is sent to ECE. This extension is called before any rating, discounting, or alteration logic has been invoked.

The extension can access this data:

Credit Control Request
Authentication Request
Accounting Request
ECE Usage Request
System configuration
Extensions data

You can modify the ECE usage request payload. For example, certain usage request manipulations can be made only when the ECE usage request payload is accessible. The usage request manipulations are done in this extension.

PreProcessor Extension

The PreProcessor extension manipulates CCR requests before the usage request is created, so that the request can match the business requirement. The PreProcessor extension can bypass charging or mutate the contents of the Sy message. This extension is called before any rating, discounting, or alteration logic has been invoked.

The extension can access this data:

Credit Control Request
Request AVPs
ECE payload
System configuration
Extensions data

PostOCS Extension

The PostOCS extension manipulates CCA, accounting, usage, or authentication responses to match the business requirement before returning the response to the client. This extension is called after charging, authentication, and accounting has been completed and recorded.

The extension can access this data:

Credit Control Request
Accounting Response
Authentication Response
ECE Usage Response
Diameter Credit Control Answer
System configuration
Extensions data

You can modify the CCA, accounting response, and authentication response. For example, you can manipulate AVPs to adapt to non-standard diameter and RADIUS implementations.

PostOCSBalanceQuery Extension

The PostOCSBalanceQuery extension manipulates ECE usage responses to match the business requirement before returning the response to the HTTP client. This extension is called after a balance query has been completed and recorded.

Pre-Rating Extension

The pre-rating extension enhances the usage request based on customer, service, balance, product, and system data so that the usage request can match the business requirement. This extension is called before any rating, discounting, or alteration logic has been invoked.

The extension can access this data:

ECE usage request information
Customer data (including profile data)
Service data (including profile data)
Balance information
Product information
System configuration
Extensions data

You can modify usage requests. For example, you modify usage requests to:

Alter the requested quota. This is implemented in the sample extensions provided.
Apply special rates or discounts (such as birthday discounts) for calls based on the extended rating attributes of both calling customers and called customers.
Generate a midsession-rated event when an update operation occurs. This is implemented in the sample extensions provided.

You can also modify the values of the pricing attributes with custom logic. This enables you to override a product price.

Post-Rating Extension

The post-rating extension modifies the rated event based on customer, service, balance, product, and system data. This extension is called after any rating, discounting, or alteration logic has been invoked.

The extension can access this data:

Balance information
Customer data (including profile data)
ECE usage request information
Product information
Shared customers (if part of a sharing relationship)
Service data (including profile data)
System configuration
Extensions data
Rated result

You can modify rated events in the following ways:

You can modify the balance impact amount, GL code, tax code, balance element or invoice data for rating impacts generated from ECE.
Generate a midsession-rated event when an update operation occurs. This is implemented in the sample extensions provided.

You can also create new tax rating impacts, such as implementing a tax on tax.

Rating Extension

The rating extension modifies the rated results after each of the following processes: rating, alteration, sharing, and taxation.

The extension can access this data:

Customer (including profile)
Shared customer (if part of a sharing relationship)
Product (including profile)
Balance information
System configuration
Extensions
Rated result

You can alter rated results to modify charges, discounts, charge sharing, taxes, and item assignments. For example:

After rating, you can alter charges based on the zones, such as standard and geographic zones.
After taxation, you can alter custom item types for the rating impacts generated from ECE, such as charge, alteration, and distribution rating impacts.

RequestReceived Extension

The RequestReceived extension manipulates the CCR, charging data request, authentication request, or accounting request so that the request can match the business requirement and provides an immediate response that bypasses the OCS completely. This extension is called before any rating, discounting, or alteration logic has been invoked.

The extension can access this data:

Credit Control Request
Authentication Request
Accounting Request
System configuration
Extensions data

You can modify the CCR, authentication, or accounting request. For example, you can manipulate AVPs to adapt to non-standard diameter implementations. Certain CCR, authentication, and accounting request types may not be supported by ECE, Diameter Gateway, or RADIUS Gateway, so a response can be created in this extension and returned immediately, bypassing the OCS.

Post-Charging Extension

The post-charging extension enriches usage responses and external notifications, excluding Advice of Charge (AOC) notifications. This extension is called after charging is completed but before the usage response is generated.

The extension can access this data:

Customer (including profile data and subscriber preferences)
Shared customers (if part of a sharing relationship, subscriber preferences)
Service (including profile data, subscriber preferences, life cycle state)
Balance information (including current request impacts)
Business profile
System configuration
Extension data
Rated result

You can modify the usage responses and external notifications. You can use the post-charging extension point to:

Enrich usage responses and external notifications. You can add custom data as AVPs to the response and notification. For example, you can add a custom language preference to a customer's subscriber preferences. The custom values will be available as diameter hooks for further propagation.
Filter out external notifications that you do not want to be published to external systems.

Post-Update Extension

The post-update extension enriches the external notifications; excluding the AoC notifications. This extension is called after receiving update requests and before publishing the external notifications.

The extension can access this data:

Customer (including profile data and subscriber preferences)
Shared customers (if part of a sharing relationship, subscriber preferences)
Service (including profile data, subscriber preferences, life cycle state)
Balance information (including current request impacts)
Business profile
System configuration
Extension data
Rated result

You can modify the external notifications with custom logic. You can use the post-update extension to:

Enrich external notifications. For example, you can add custom data to any external notification that is generated to provide additional data, such as spending limit notifications.
Filter out external notifications that you do not want to be published to external systems. For example, when billing is run, ECE generates subscribe-notification-request (SNR) notifications for all impacted resources. You can filter out unneeded SNR notifications and publish only required notifications to external systems.

To use the post-update extension, you must define the post-update extension's fully qualified class name in the ECE_home/config/management/charging-settings.xml file.

Extensions Cache

The extensions framework provides a generic repository from which data required for the pre-rating, post-rating, and post-charging extensions can be uploaded and used. The data format is described in a specifications file that describes the format of the data. The extensions specification allows a DataLoader to load the data into the ECE extensions cache. Example 22-1 is an example of a specifications file for the post-rating extension:

Example 22-1 Sample Tax Table

/*
 * Sample tax table
 */
ExtensionDataSpecification
   Info {
      Name "tax_table_0001"
   }
   Payload {
      Block "TAX_ROW" {
         String "TAXCODE"
         String "PKG"
         Decimal "RATE"
         DateTime "START"
         DateTime "END"
         String "LEVEL"
         String "LIST"
         String "DESCRIPTION"
         String "RULE"
      }
   }
}

Example 22-2 shows the associated data to load into the cache using the specification file above:

Example 22-2 Example Data File

# This is a sample csv file containing typical tax configuration data.
#
#TaxCode |Pkg |Rate    |Start      |End        |Level |List  |Description |Rule
 usage   |U   |0.05    |01/01/2013 |12/31/2014 |Fed   |US    |USF         |Std
 usage   |U   |0.08    |01/01/2013 |12/31/2014 |Sta   |CA    |USTA        |Std
 usage   |U   |0.06    |01/01/2013 |12/31/2014 |Fed   |US    |USF         |Std
 usage   |U   |0.085   |01/01/2013 |12/31/2014 |Sta   |CA,AZ |USTA        |Std
 purchase|V   |0.08525 |01/01/2013 |12/31/2014 |Sales |CA    |PSLS        |Std

Extensions Cache API

The extensions repository provides the following APIs for managing extensions data:

putExtensionsData(). Takes a single key-value pair of string as a key and value being an ExtensionsData object.
putExtensionsDataCollection(). Takes a map of key-value pairs of string keys and value being ExtensionsData objects.
findExtensionsData(). Returns an ExtensionsData object for a given key.
getAllExtensionsData(). Returns a read-only collection of all extensions data from the repository.

The extension includes these repository constraints:

You must generate a unique key as a string for one ExtensionsData object (entry in the extensions cache) at the time of retrieval of the extensions data from the cache.
Because the extensions data is replicated across the whole cluster, the amount and size of data is limited to what a given Java heap can manage. You can also adjust the Java heap size. Refer to the Java provisioning guidelines.
Changes made to the extensions data after it is loaded are expensive to make due to its cache topology. Avoid frequent updates to the extensions data, especially in a larger cluster.
The framework does not dictate the type of data source that extensions data are loaded from. The provided SampleExtensionsDataLoader SDK demonstrates loading the data from a comma-separated-value (CSV) file using extensions domain-specific language APIs. This sample is a recommended design, but it should not be used as a reference about how to store data.

Sample Extensions

The BRM SDK includes sample extensions. For information about how to use the samples, see "How To Use the Sample Extensions" and "Validating Sample Extensions".

For information about each sample extension, see the following:

How To Use the Sample Extensions

To use the sample extensions:

ECE SDK is installed under $SDK_HOME. The directory listing is shown below:

$ ls -l
total 124
drwxr-xr-x 2 ecsuser ecsuser  4096 Jun 21 10:47 bin
drwxr-xr-x 2 ecsuser ecsuser  4096 Jun 21 10:47 bin
drwxr-xr-x 3 ecsuser ecsuser  4096 Jun 21 10:47 config
-rw-r--r-- 1 ecsuser ecsuser     5 Jun 21 10:47 VERSION

Under the source directory, create a pre-extensions or post-extensions Java Class using the Extensions API and other libraries (samples are provided as a part of the ECE SDK.)

$ cd source
$ cd oracle/communication/brm/charging/sdk/extensions
$ ls -l
total 28
-rw-r--r-- 1 ecsuser ecsuser  6427 Jun 21 10:47 SampleExtensionsDataLoader.java
-rw-r--r-- 1 ecsuser ecsuser XXXXX Jun 21 10:47 SampleOCSByPassExtension.java
-rw-r--r-- 1 ecsuser ecsuser 12194 Jun 21 10:47 SamplePostRatingComplexTaxation
-rw-r--r-- 1 ecsuser ecsuser  6066 Jun 21 10:47 SamplePreRatingExtension.java
-rw-r--r-- 1 ecsuser ecsuser XXXXX Jun 21 10:47 SamplePostChargingExtension.java

Write custom logic in Java and copy it under the directory. The Java source is under the package oracle.communication.brm.charging.sdk.extensions:
```
$SDK_HOME/source/oracle/communication/brm/charging/sdk/extensions
```
Change ECE_HOME in the script build_deploy_extension.sh file under $SDK_HOME/bin/extensions:
```
### configuration begin
ECE_HOME=$ECE_HOME
### configuration end
```

Compile the extensions class using the shell script: build_deploy_extension.sh.

Each extensions file has to be compiled individually (similar to SDK programs).

Any additional ECE or third-party library required for the extensions needs to be added to the CLASSPATH in the build_deploy_extension.sh. script

$sh $SDK_HOME/bin/extensions/build_deploy_extension.sh build SampleDiameterGyExtension
$sh $SDK_HOME/bin/extensions/build_deploy_extension.sh build SamplePostRatingComplexTaxationExtension
$sh $SDK_HOME/bin/extensions/build_deploy_extension.sh build SamplePreRatingExtension
$sh $SDK_HOME/bin/extensions/build_deploy_extension.sh build SamplePostChargingExtension
$sh $SDK_HOME/bin/extensions/build_deploy_extension.sh build SampleOCSByPassExtension

Do the following optional step if external data needs to be loaded. To compile the sample extensions loader use the sample_extensions_loader.sh shell script:

$sh $SDK_HOME/bin/extensions/sample_extensions_loader.sh build SampleExtensionsDataLoader
$sh $SDK_HOME/bin/extensions/sample_extensions_loader.sh run

Deploy creates a single JAR file (ece.extensions-VERSION-SNAPSHOT.jar) with all the extensions classes and copies the JAR file under $ECE_HOME/lib. The JAR file is copied only to the driver node. It has to be propagated to other ECE nodes in the grid manually or use a rolling upgrade.
```
$sh $SDK_HOME/bin/extensions/build_deploy_extension.sh deploy
```

Define the fully-qualified class names of the pre-rating, bypass rating, rating, post-rating, post-charging, and post-update extensions by configuring the charging.extensions MBean in the ECE Configuration node using a JMX editor. For instructions, see "Configuring Extensions".

preRatingExtension="oracle.communication.brm.charging.sdk.extensions.
SamplePreRatingExtension"
RatingExtension="oracle.communication.brm.charging.sdk.extensions.
SampleRatingExtension"
postRatingExtension="oracle.communication.brm.charging.sdk.extensions.
SamplePostRatingComplexTaxationExtension"
postChargingExtension="oracle.communication.brm.charging.sdk.extensions.SamplePostChargingExtension"
diameterGyExtension="oracle.communication.brm.charging.sdk.extensions. SampleDiameterGyExtension"
postUpdateExtension="oracle.communication.brm.charging.sdk.extensions.SamplePostUpdateExtension"
ocsBypassExtension="oracle.communication.brm.charging.sdk.extensions.SampleOCSByPassExtension"

Start or restart the ECE server nodes and enable logging for the extensions by setting oracle.communication.brm.charging.extensions.client to DEBUG via JMX and verify that the custom extensions are run as a part of rating logic. You can also turn on debug logging for the RATING module using the JMX console.

Validating Sample Extensions

After the server nodes are bought up initially or by using a rolling upgrade, send a sample SDK usage request. Enable debug for the RATING module and verify the server log contains these messages:

SamplePreRatingExtension invoked
PostRatingComplexTaxationSampleExtension executed

BRM Gateway Extension - Creating Opcode Flist

The sample program SampleBRMGwCustomOpCodeExtension shows how to use the ECE Extensions API to enrich an external notification with an input flist for a specified opcode.

The sample program builds an input flist for the PCM_OP_BILL_DEBIT opcode.

Diameter Gateway Extension - Gy Service

The sample program SampleDiameterGyExtension shows how to use the immediate-response feature based on an incoming AVP value.

The logic: If Service-Context-Id is OFFLINE, respond with Diameter Code DIAMETER_REDIRECT_INDICATION and set the Redirect-Host AVP value

Diameter Gateway Extension - Sy Service

The sample program SampleDiameterSyExtension shows how to use the ECE extensions API to suspend the Sy interface when a subscriber is suspended. The sample program does the following:

Bypasses rating by calling the setBypassOCS() method and setting the DiameterResultCode to DIAMETER_REDIRECT_INDICATION.

Note:

To skip the bypass, comment or remove the setBypassOCS() method invocation under the handleRequestReceived() method.
Adds or removes AVPs in the Custom Sy Response.
Modifies the request data time and product type in the policy request.
Modifies the status and reason codes in the policy response.

HTTP Gateway Extension - Service

The sample program SampleHTTPExtension shows how to use the ECE Extensions API to override the requested number of units and perform call screening.

The handleRequestReceived() method overrides the requested units for a call.
The handlePreOCS() method sets the timestamp of when the call originally occurred.
The handlePostOCS() method logs a message when call screening is done and returns a response to the 5G client.
The handlePostOCSBalanceQuery() method logs a message when a balance query occurs and returns a response to the 5G client.

OCSBypass Extension - Bypassing Rating

The sample program SampleOCSByPassExtension shows how to use the ECE extensions API to bypass rating during ECE downtime. When bypass rating is enabled, the CCRs are persisted to Oracle NoSql. When ECE is restored, the persisted requests are replayed to the ECE charging server for rating and updating balance impacts along with the real-time requests. Using this extension, you can write your own logic for modifying the AVP of incoming diameter messages and for creating the diameter responses.

Pre-Rating Extension - Dynamic Quota Management

The sample program SamplePreRatingExtension shows pre-rating custom logic. It illustrates sample logic for the pre-rating scenarios.

Dynamic Quota Management - Modifying Quota Based on Network Type

The SamplePreRatingExtension program shows how to use the ECE extensions API to modify the input request quantity based on the input network type where the customer balance is greater than a predefined amount.

Logic:

If ORIGIN_NETWORK network field is:

"3G_UTRAN" and USD balance greater than 50 then set quota to 10 MB

"4G_UTRAN" and USD balance greater than 50 then set quota to 100 MB

Dynamic Quota Management - Modifying Requested Quota

The SamplePreRatingExtension program shows how to use the ECE extensions API to update the input request to modify the requested quota. You can use this sample program to access the ECE cache to derive at a quota and then update the requested quota in the input request. ECE then uses the derived quota for allocation.

Dynamic Quota Management - Modifying Default Quota Configuration

The SampleDynamicQuotaExtension program shows how to use the ECE extensions API to update the following attributes in the input request to modify the quota configuration based on your requirements:

Quota holding time. Specifies how long a granted quota can be idle before the reservation is released.
Volume quota threshold. Specifies how much of the granted quota must be consumed before a subscriber can request additional quota. This attribute is configured per service, event, and number of granted units.
Validity time. Specifies whether the validity time can be set to a fixed value per service-event combination at runtime. This attribute is independent of the number of units in the granted quota.

Pre-Rating Extension - Retrieving Function Values for Discount Expressions

The SamplePreRatingExtension program shows how to use the ECE extensions API to retrieve the value referenced by the function in a discount expression. You create a custom function in ECE that defines an event profile attribute. You can use the SamplePreRatingExtension program to call the custom function. ECE then adds the defined event profile attribute and its value to the usage request.

If the PDC pricing specifies a 10% discount for all accounts active less than 12 months, then the logic is the following:

If customerActiveMonths value is:

< 12 then apply a discount of 10%
> 12 then apply a discount of 0%

Pre-Rating Extension - Generating Midsession-Rated Event

The SamplePreRatingMidSessionExtension program shows how to use the ECE extensions API to generate a midsession-rated event when an update request contains the following:

A specified balance, such as greater than or equal to $500
A changed field in a usage request
A specified account field
A specified product type, such as TelcoGsmTelephony

Pre-Rating Extension - Overriding Price in Product Offerings

The SamplePreRatingExtension program shows how to use the ECE extensions API to override the price specified in product offerings. You create a custom function in ECE that overrides the default value of the pricing attributes in dynamic tags, which are the XML elements configured in PDC. You can use the SamplePreRatingExtension program to call the custom function. The overridden values are then populated in the event profile map in the request specification data. ECE uses the overridden values to determine the price when processing usage requests.

Post-Rating Extension - Complex Taxation

The sample program SamplePostRatingComplexTaxationExtension shows how to use the ECE extensions API to override or augment post-rating results using complex taxation as an example. The program iterates over the tax rating periods and overrides tax impacts by modifying the rating periods for federal tax and then generates new tax periods for the state tax.

It applies the tax rate based on the pre-loaded tax configuration data in the extensions cache. The tax rate is determined based on tax code, tax time, and validity, which are all based on the request start time. The default configuration for the tax code used in the extension must exist in the ECE configuration.

The extension uses the following logic:

Determines the federal tax rate from the tax configuration table using the tax code, request start time.
Calculates the federal tax based on this tax rate.
Modifies the original impact in the tax rating period based on the taxable impact from the linked charge, alteration, or distribution rating period.
Determines the state tax rate from the tax configuration table using the tax code, request start time.
Calculates state tax based on this tax rate.
Creates new tax rating period for the state tax and link it to the original charge/alteration/distribution rating period.

This program also shows how to use the extensions API to override the invoice data in the rating result. The overridden value is persisted into the CDR output file.

Post-Rating Extension - Generating Midsession-Rated Events

The SamplePostRatingMidSessionExtension.java sample program shows how to use the ECE extensions API to generate a midsession-rated event when a rated event contains the following:

A balance granted by an offer is exhausted
A balance bucket is expired
The charge offer used during rating is different from that of the ongoing session

Post-Rating Extension - Adding or Deleting Rating Periods

The PostRatingConsolidateRatingPeriods sample program shows how to use the ECE extensions API to:

Add a single rating period with the consolidated charge for all the rating periods of type CHARGE.
Delete all the existing rating periods of type CHARGE.

You can use this sample program to access the ECE cache and override the rating periods in the final rated results by adding or deleting rating periods.

Post-Charging Extension - Adding Custom Data to Usage Responses and Notifications

The sample program SamplePostChargingExtension shows how to use the ECE extensions API to add custom data to the following:

Usage responses. You add the data as AVPs. For example, you can add a custom language preference to a customer's subscriber preferences. The custom values are available as diameter hooks for further propagation.
External notifications. You add the data as key-value pairs. For example, you can add information such as calling number, called number, event type, and balance group to these notifications, such as credit threshold notifications.

Post-Charging Extension - Overriding Dynamic Quota

The SamplePostChargingExtension program shows how to use the ECE extensions API to override the quota attributes, such as quota holding time and volume quota threshold, in the usage response. You provide the data as name-value pairs. ECE then accesses the data and updates the usage response.

Post-Charging Extension - Adding or Modifying Redirection Rules

The SamplePostChargingExtension program shows how to use the ECE extensions API to add or modify rules for redirecting a subscriber session to a service portal applicable to the business scenario. You can add or modify them based on the customer conditions, such as whether the customer has insufficient funds or whether the customer has an inactive account.

Post-Charging Extension - Creating Custom Notifications for Top Ups

The sample program SamplePostChargingExtension shows how to use the ECE extensions API to create a custom notification for topping up a customer's balance element through the BRM PCM_OP_BILL_DEBIT opcode.

The sample program retrieves data and for a specified service type, request type, and balance element combination. It also specifies the BRM opcode to call. The sample program includes the following:

The getUsageRequest() method, which specifies that the logic applies to the INITIATE request type andEventDelayedSessionTelcoGprs service type.
The getBalance() method, which specifies that the logic applies to the USD balance element.
The customMap() method, which retrieves the following data: customer ID, service ID, balance ID, product type, and balance element code.
The addCustomServiceEventWithOpCode() method, which specifies to call the PCM_OP_BILL_DEBIT opcode.

Post-Update Extension - Enriching External Notifications

The sample program SampleUpdateNotificationExtension shows how to use the ECE extensions API to add custom data to external notifications that are generated to provide additional data. You add the data as name-value pairs. ECE then accesses the data and updates the external notifications.

Rating/Charging Extension - Triggering RAR Notifications

The following sample programs show how to use the ECE extensions API to trigger server-initiated reauthorization request (RAR) notifications in the rating and charging flow:

SampleRarPreRatingExtension
SampleRarPostRatingExtension
SampleRarPostChargingExtension

These programs access the ECE cache data and trigger RAR notifications to retrieve the exact reservation balance for performing any business operation.

In the custom logic, if the SendGenericRARNotification is set to true, ECE generates generic RAR notifications for all Diameter sessions for the client and the Rating-Group and Service-Identifier are not set in those notifications. If SendGenericRARNotification is set to false, ECE generates service-specific RAR notifications with Rating-Group and Service-Identifier set in the notifications.

Rating Extension - Custom Item Assignment

The sample program SampleRatingExtension shows how to use the ECE extensions API to alter the custom item type for rating impacts.

It alters custom item types for the rated results based on the data accessible through the rating extension. The default configuration for the custom item type used in the extension must exist in the ECE configuration.

The extension uses the following logic:

After taxation, determines the custom item type to be used based on the data accessible through the rating extension.
Assigns the rating impacts to the custom bill items based on the new custom item type.

Extensions Data Load Sample

The sample program SampleExtensionsDataLoader demonstrates how the extensions data repository can be used and how to load data into the repository.

The data loader used for extensions is located at ECE_home/ocecesdk/source/oracle/communication/brm/charging/sdk/extensions.

The following SDK artifacts are provided:

tax_configuration.spec
- This is a specification for tax codes. The specification expects a single block with a cardinality of 1 per ExtensionsData.
- Contains the following attributes:
  - Tax code (String)
  - Pkg (String)
  - Rate (Decimal)
  - Start (DateTime)
  - End (DateTime)
  - Level (String)
  - List (String) Description (String)
  - Description (String)
  - Rule (String)
tax_configuration_data.csv
- A pipe-delimited CSV file. This file acts as a data source for tax codes.
SampleExtensionsDataLoader
- A class that reads the CSV file, prepares the payload as per tax specification, and uses the extensions repository to put a collection of ExtensionsData.
- Also asserts if the number of ExtensionsData put in the Repository are the same as the total being read.