Professional Documents
Culture Documents
ECE Extensions
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.
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.
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
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.
• 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
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.
• 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.
1) ECE SDK is installed under $SDK_HOME. The directory listing is shown below:
$ ls -l
total 124
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
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
Optional step if external data needed to be loaded: To compile the sample extensions loader use the
shell script sample_extensions_loader.sh
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>
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.