This chapter describes how to integrate Oracle Communications Billing and Revenue Management Elastic Charging Engine (ECE) with top-up clients, such as those in a Third-Party top-up system.
Note:
The information in this chapter is relevant for those using third party network mediation software (for online charging) for receiving top-up requests from the network and translating them into ECE requests.If you are using Diameter Gateway for receiving Diameter messages and translating them into ECE requests, see "Network Integration for Online Charging Using Diameter Gateway". Diameter Gateway constructs top-up requests for ECE.
ECE can receive top-ups from Third-Party top-up systems.
The ECE top-up API interfaces directly with top-up systems. The top-up systems send the top-up amount to ECE. ECE updates the customer balance in the cache and sends the update to BRM to update the customer balance in BRM.
ECE acts only as the Balance Management Function for the external top-up systems. The ECE top-up API does not perform authentication, authorization, or accounting operations as these AAA functions are handled by other systems.
To use the top-up API, clients call the submitUpdate API with ExternalTopupUpdateRequest.
For detailed information about the top-up API, see the documentation for the following in BRM Elastic Charging Engine Java API Reference:
oracle.communication.brm.charging.brs
oracle.communication.brm.charging.messages.update
Consider the following points for how the ECE top-up API validates top-up requests:
For a currency resource, validity should not be passed as part of the request; if it is passed, it fails with an error. The customer's balance is expected to have one valid currency balance item/bucket with infinite validity. If no balance item/bucket is present, a new one is created with infinite validity.
Validity extend (ValidityExtend) is only for non-currency resources (given that currency resources do not have a validity).
Whenever validity needs to be set for a resource, then both validity start and validity end are mandatory to be sent as part of the request.
To create bucket with infinite validity, set both validityStart and validityEnd to -1.
If the request is to extend validity and the customer balance has multiple valid balance items/buckets, then an error response is sent.
If the request is to create a firstUsage bucket, then validity start and validity end should not be set in the request, except for the FirstUsageValidityUnit.ABSOLUTE mode.
ValidityExtend is not allowed on a first-usage bucket.
If both the validity and first-usage information (such as offset and unit) are specified as part of the request, then the top-up request fails with an error.
Top-ups from Third-party top-up systems are not allowed when ECE is in a short-lived phase of the rerating process called the CATCH_UP phase.
If top-up requests are sent during the CATCH_UP phase of rerating, ECE sends a failed response and includes the reason code for the failure in the response message. If that occurs, you can resend the top-up and ECE will process it.
During testing, if a top-up request is sent to ECE with an event time that is earlier than the account creation time of the account to which the top-up applies, the balance is updated with the top-up in ECE but the balance is not updated in BRM. When you set event time stamps during testing, ensure the event time of the top-up request is later than the applicable account creation time.
Third-party top-up systems, such as voucher management systems, are used to eliminate duplicate top-up requests sent to ECE. However, duplicate top-up requests can occur internally in ECE, for example, when an unexpected ECE server shutdown occurs.
To detect duplicate top-up requests, ECE uses a combination of the Session ID field and the Recharge Reference field in the top-up CCR message.
As part of detecting duplicate top-up requests, ECE maintains a top-up history cache of the customer. The top-up history cache maintains a number of top-up Recharge Reference message IDs for each customer at any given time. The Recharge Reference message ID is required to be unique in the top-up history cache.
For top-up requests that have the same session ID, if the Recharge Reference message ID of an incoming top-up request is available in the history, then ECE considers the request to be a duplicate.
If ECE detects a duplicate top-up request, the following occurs:
ECE does not apply the top-up
ECE includes the following in the top-up response message:
The reason code DUPLICATE_REQUEST
The current customer balance
If you do not configure top-up request history for your implementation, ECE may not detect internal duplicate top-up requests. If ECE cannot detect an internal duplicate top-up request, the following occurs:
ECE applies the top-up balance to the customer balance in its customer cache (as though it were a new request) and sends the top-up to BRM.
BRM, which stores all top-up Recharge Reference message IDs in the BRM database, detects the top-up request as a duplicate and does not apply the top-up to the customer balance in the BRM database.
BRM throws an error in the BRM Gateway log file as Error from BRM: ERR_DUPLICATE.
You would need to manually track such errors in the BRM Gateway log file since the ECE customer balance would no longer be synchronized with the customer balance in the BRM database.
You manage the number of top-up Recharge Reference message IDs to store in the top-up history cache by using the external.topupConfig ECE MBean.
To configure a top-up history cache:
Access the ECE MBeans:
Log on to the driver machine.
Start the ECE charging servers (if they are not started).
Start a JMX editor, such as JConsole, that enables you to edit MBean attributes.
Connect to the ECE charging server node set to start CohMgt = true in the ECE_home/oceceserver/config/eceTopology.conf file.
The eceTopology.conf file also contains the host name and port number for the node.
In the editor's MBean hierarchy, expand the ECE Configuration node.
Expand charging.externalTopUpConfig.
Expand Attributes.
Set the topUpHistoryCount attribute to the number of top-up request message IDs to store for each customer.
The default value is 3.
If you change the value of this attribute (for example, from 10 to 4) and the top-up history cache already contains 10 message IDs, ECE eliminates the message IDs of the oldest 6 top ups when the next top up arrives so that only the message IDs of the 4 most recent top-up requests are stored.
For information about running sample programs that demonstrate how to use the ECE top-up API, see "About the ECE Sample Programs".