ECE Extensions

• Background
• Architecture
o Extension points
o Implementing the Extension logic

Pre-rating Extension

Accessible Data

Modifiable Data

Post-rating Extension

Accessible Data

Modifiable Data

Extension Cache

Extension Cache API

Repository constraints
• Sample Extensions
o Pre-rating Extension - Dynamic Quota Management
o Post-rating Extension - Complex Taxation

Extension Data load sample
o How to use the sample Extensions?

Validating sample extensions
• Operational Considerations
o Configuration
o Performance
o Logging
o Exception
o Metrics (Latency)
o Upgrading extensions
• Best Practices

Background
BRM has traditionally supported extensibility through Policy opcodes, iScripts and iRules. This has
been a strength of the product and provided great value to our customers and partners. After the
release of the Elastic Charging Engine (ECE) 11.1 our partners and customers have requested the
ability to add their own extensions into the charging flow of ECE. We have listened and are now
creating the capability to add in custom extensions to the ECE charging flow. We wanted to provide
a extension framework that is simple to use yet powerful while also providing access to extension-
specific data in a way that doesn't compromise the overall performance of the system.

The Elastic Charging Engine Extension capability introduces a pre-rating and a post-rating extension
point to allow for maximum flexibility. We will also be providing a sample implementation of the both
the pre- and post-rating extensions so that you can see how they work. The sample extensions will
 demonstrate how to implement dynamic quota, using the pre-rating extension, and how to implement
complex taxation using the post-rating extension.

The objective of this Whitepaper is to provide all the information required in order to use the
Extension capability in the Elastic Charging Engine.

Architecture
Extension points
The two extension points in rating flow are positioned before rating and after final charge calculation
as indicated in the diagram below.

Implementing the Extension logic

The PreRatingExtension and PostRatingExtension interfaces are intended to be implemented by
the extension author. They expose initialize() andshutdown() methods that will be called by the
hook framework at ECS Node startup and shutdown time. Implementers can use these methods to
configure their own internal data structures relating to the extension business logic.
The execute() method is called for every UsageRequest that is processed by the Charging Flow. All
methods expose relevant ExtensionContext data for accessing the ExtensionsDataRepository,
AppConfigRepository and other Pre and Post extension related contexts.
For additional details refer to ECE public API Javadoc for ECE (insert link).

ECE provides the extension implementation author with the build and deploy capabilities in form of
shell scripts. If there are any 3rd party libraries that needs to be used inside the custom extension
logic then the extension author needs to include those 3rd party jars in the classpath, this is done by
copying the 3rd party jars to $ECE_HOME/lib folder. Once the jars have been copied they need to
synchronized across to the others servers in the cluster, this can be done by executing
the sync command in the Elastic Charging Controller (ECC). Please refer to the standard ECE
documentation for more information.

Custom extension logic implementation classes that

implements PreRatingExtension and PostRatingExtension interfaces and its dependencies need
 to be packaged in jar format. The packaged extension jar should be made available to ECE runtime
environment under $ECE_HOME/lib folder.

Pre-rating Extension
The pre-rating extension is designed to give access to usage request as well as the Customer,
Product, Balance and Offer data so that the usage request can be altered to match the business
requirement. This extension is call before any rating, discounting or alteration logic has been invoked.

Accessible Data

• Usage request
• Customer (including profile data)
• Product (including profile data)
• Balance information
• System Configuration
• Extension Data

Modifiable Data

• Usage request

Modification of the usage requests, for example, enables to alteration of the requested quota. Use
the PayloadMutator, which is available in PreRatingExtensionContext, to modify the values of a
UsageRequest payload. This is implemented in the sample extensions provided.

Additional details:
Supports only modification to payload attributes of the built request using PayloadMutator? interface,
refer to ECE Java docs.
Following request values cannot be modified:
userIdentity,
SessionId? ,
Request Start time,
Request End time
Sequence number
Operation
Product Type
Event Type
version
unit reporting mode

Post-rating Extension
Accessible Data

• Customer (including profile data)

• Shared Customers (if part of a sharing relationship)
• Product (including profile data)
• Balance information
• System Configuration
• Extension Data
• Rated Result

Modifiable Data

• Rated Result

When modifying the rated result you are able to do the following:

1. Modify impact amount, GL code and balance element for rating impacts generated from ECE.
(e.g Charge, Alteration or Distribution rating impacts)
2. Creation new tax rating impacts (e.g. implement tax on tax)

Additional details:
Only following items in rating result can be modified in extension logic
a) Impact amount of any rating period ( e.g CHARGE, ALTERATION and DISTRIBUTION)
b) GL Code of any rating period ( e.g CHARGE, ALTERATION and DISTRIBUTION)
c) Balance Element of rating period ( e.g CHARGE, ALTERATION and DISTRIBUTION)
d) Custom invoice data
e) Create new tax rating period associated to any existing rating period

Extension Cache
The Extensions framework provides a generic repository where data required for the pre- and post-
rating extensions can be uploaded and used from. The data format is described in a Specifications
file which describes the format of the data, this allows a DataLoader to load the data into the
Extensions cache in Coherence. The following is an example of Specifications file for the post-rating
example.
 And the following is the associated data to load into the cache using the Specification file above.

Extension Cache API

The Extension Repository provides following APIs for managing the Extension 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 Collection of all ExtensionsData in the repository.
Repository constraints
Following expectations are set for using the Repository:

• The extension implementation author generates an Unique key as String for one
ExtensionsData object. The author must have a way to construct this key at the time of
retrieval.
• The key must be a String.
• As the repository is configured as a Coherence Replicated cache it is required that amount
and size of data must be limited to what a given Java heap must comfortably manage.
Please refer to Java provisioning guidelines.
• Changes made to ExtensionsData once loaded are expensive to make due to its cache
topology. Typically frequent updates to the ExtensionsData must be avoided, specially in a
larger cluster.
• The framework does not dictate the type of data source that Extensions Data are loaded
from. A SDK program SampleExtensionsDataLoader has been provided to demonstrate
loading the data from a CSV file using Extensions DSL APIs. This sample is provided in
good faith using recommended design but should not be used as a reference in how to store
data. It is up to the extensions implementation author how he/she constructs the
ExtensionsData.

Sample Extensions
Pre-rating Extension - Dynamic Quota Management
The Sample program !SamplePreRatingExtension shows pre extension custom rating logic. It
illustrates a sample logic to modify the input request quantity based on input network type and if
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
OR
"4G_UTRAN" and USD balance greater than 50 then set quota to 100 MB

Post-rating Extension - Complex Taxation

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

It applies the tax rate based on the pre-loaded tax Configuration data in the extension cache. Tax
rate is determined based on Taxcode, Taxtime and Validity based on the request start time. Default
configuration for the tax code used in extension must exist in the ECE configuration
 Logic:

1. Determine federal tax rate from the tax configuration table using the taxcode, request start
time
2. Calculate federal tax based on this tax rate.
3. Modify the original impact in the tax rating period based on the taxable impact from the linked
charge,alteration or distribution rating period.
4. Determine state tax rate from the tax configuration table using the taxcode, request start time
5. Calculate state tax based on this tax rate.
6. Create 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 extension API to override the invoice data in the rating
result The overridden value is persisted into the CDR output file generated by the BRM CDR Plugin.

Extension Data load sample

A sample SDK SampleExtensionsDataLoader has been provided to demonstrate how Extensions
Repository can be used. Following SDK artifacts have been provided:

• tax_configuration.spec
o This is a specification DSL for Tax codes. The specification expects a single Block
with a cardinality of 1 per ExtensionsData? .
o Contains following attribute:

Tax Code (String)

Pkg (String)

Rate (Decimal)

Start (DateTime? )

End (DateTime? )

Level (String)

List (String)

Description (String)

Rule (String)
• tax_configuration_data.csv
o A pipe delimited CSV file. This file acts as a data source for Tax codes.
• SampleExtensionsDataLoader?
o A class that reads the CSV file, prepares the payload as per Tax specification and
uses Extensions Repository to put a collection ofExtensionsData? .
o Also asserts if the number of ExtensionsData? put in the Repository are the same as
the total being read.

How to use the sample Extensions?

NOTE: * In the current ECE version only *one Pre Rating and one Post Rating Extension class
can be deployed.

1) 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 config

drwxr-xr-x 3 ecsuser ecsuser 4096 Jun 21 10:47 source

-rw-r--r-- 1 ecsuser ecsuser 5 Jun 21 10:47 VERSION

2) Under the source directory, create a Pre or Post extension Java Class using the Extensions API
and other libraries.
[Samples are already 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 12194 Jun 21 10:47

SamplePostRatingComplexTaxationExtension.java

-rw-r--r-- 1 ecsuser ecsuser 6066 Jun 21 10:47 SamplePreRatingExtension.java

3) Write Custom logic in Java and copy it under the directory. The java source should be under the
package oracle.communication.brm.charging.sdk.extensions

$SDK_HOME/source/oracle/communication/brm/charging/sdk/extensions

4) Change ECE_HOME in the script build_deploy_extension.sh under

$SDK_HOME/bin/extensions.

### configuration begin

 ECE_HOME=$HOME/ECE/trunk/target

### configuration end

5) Compile the Extension class using the shell script build_deploy_extension.sh.

a) Each extension file has to be compiled individually (Similar to sdk programs)
b) Any additional ECE or third party libraries required for the extensions need to be added to the
CLASSPATH in the script build_deploy_extension.sh.

$sh $SDK_HOME/bin/extensions/build_deploy_extension.sh build

SamplePostRatingComplexTaxationExtension

$sh $SDK_HOME/bin/extensions/build_deploy_extension.sh build

SamplePreRatingExtension

Optional step if external data needed to be loaded: To compile the sample extensions loader use the
shell script sample_extensions_loader.sh

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

SampleExtensionsDataLoader

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

6) Deploy creates a single jar ece.extensions-VERSION-SNAPSHOT.jar with all the extension

classes and copies the jar 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 rolling upgrade.

$sh $SDK_HOME/bin/extensions/build_deploy_extension.sh deploy

7) Define the Pre and Post rating extension's fully qualified class names in application configuration
file - charging-settings.xml under $ECE_HOME/config/management.
The configuration can also be changed using Extensions MBeans.

<extensions

config-
class="oracle.communication.brm.charging.appconfiguration.beans.extensions.Ex
tensionsConfig"
 preRatingExtension="oracle.communication.brm.charging.sdk.extensions.SamplePr
eRatingExtension"

postRatingExtension=""oracle.communication.brm.charging.sdk.extensions.Sample
PostRatingComplexTaxationExtension">

</extensions>

8) Start/Restart the ECE server node(s)

Enable logging for the extensions by
setting oracle.communication.brm.charging.extensions.client to DEBUG
and verify that the custom extensions are executed as a part of rating logic.
We can also turn on debug logging for RATING module via JMX console.

Validating sample extensions

Once ecs nodes are bought up initially or via rolling upgrade then send an sample SDK usage
request. Enable debug for RATING module and verify the ecs1.log contains the
"SamplePreRatingExtension invoked" and "PostRatingComplexTaxationSampleExtension
executed!!!" messages.

Operational Considerations
Configuration
Configuration of the Extension capability is done via JMX, the implementation classes for both pre-
and post-rating extension are configured
here:

Performance
Logging

Exception

Metrics (Latency)

Upgrading extensions

Best Practices
All prerating extensions must be implemented in a single class, this can delegate to additional
implementations if multiple extensions are being implemented. Extension data is loaded into a
Replicate Cache in Coherence and amount of data loaded into the cache will need to be taken into
consideration when doing the sizing for Java.