This chapter describes how to integrate charging client applications with Oracle Communications Billing and Revenue Management Elastic Charging Engine (ECE).
Note:
The information in this chapter is relevant for those using third party network mediation software (for online charging) for receiving network messages 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 all charging-operation-type requests that ECE supports for online charging.
You can integrate ECE with network mediation systems so that they can send requests to ECE for executing charging and network operations in ECE.
Running the ECE sample programs is the best way to learn how to use the ECE API for integrating ECE with external network mediation systems. The Java API documentation is also a general resource for learning how to use the ECE API.
Third party network mediation software programs can use different types of builders to build different ECE requests. The network mediation software program receives the network request and transfers the relevant request fields from the network-request data structures into the UsageRequest Payloads by using the ECE UsageRequestBuilder APIs.
You call a constructor which is an ECE API (a public file included in the ECE SDK jar file installed on the client) to make a request (Build) and then call other usage-request classes to populate the request (Payload/createPayload). See "About Building Usage Requests" for more information.
ECE is pre-integrated with Offline Mediation Controller for offline charging; Offline Mediation Controller includes pre-made builders for building the different request types needed for offline charging (charging requests, balance query requests, and so on). See "Integrating ECE with Offline Mediation Controller".
This section describes how network mediation software programs (client applications) build usage requests.
The usage request builder creates usage requests; it is created and used by the network mediation software program when a request from the network is received.
Network mediation software programs use the Elastic Charging Client API for instantiating the usage request builder. The Elastic Charging Client API is included in the ECE SDK.
For sample code that demonstrates how to use the usage request builder, see the sample programs included in the ECE SDK.
ECE supports incremental and cumulative based accounting behavior when processing usage requests.
Incremental accounting logic is used by the Diameter standard which supports Requested Service Units (RSU) and Used Service Units (USU) concepts. Incremental accounting logic indicates that the creator of the usage request enables the rating engine (ECE) to calculate in the active session the duration based on the units that have been used since the previous session update.
Cumulative accounting logic is used by the Radius standard which indicates that the creator of the usage request always supplies the full quantity (for example: duration, volume, meters, miles and so on) inclusive of all previous session requests.
When you create your usage request builder, specify the accounting behavior by using the UnitReportingMode ECE Java enum. When the usage request builder is instantiated, the enum indicates to ECE whether to use incremental or cumulative accounting behavior.
Important:
When there are multiple RUMs and attributes ROUND_UP and ROUND_DOWN of quantity in the rate plan, Granted Service Units that are reported on all attributes may be rounded up or down based on the rate plan configuration.For both incremental and cumulative accounting, you must set attributes for the Requested_Units and Used_Units blocks in the payloads of applicable operation types. For example, the Requested_Units block is defined for the payloads of Initiate and Update operation types and the Used_Units block is defined for the payloads of Update, Update Accounting and Terminate operation types.
When configuring incremental or cumulative quota for usage requests, the metric name (RUMs) must be the same as the attribute name. For example, when sending attribute INPUT_VOLUME on the usage request, the RUMs must be defined with the same name.
Diameter Gateway uses incremental based accounting only.
Usage requests contain a set of well known or fixed attributes that must be provided. Fixed attributes are required fields directly exposed by the UsageRequest interface. Fixed attributes are applicable for all the events in ECE.
You cannot pass in null for any of the fixed attributes. For non-duration requests, you can pass the same timestamp for both requestStart and requestEnd.
Fixed attributes within a usage request include the following:
userIdentity
The userIdentity attribute is the fixed attribute name representing the public user identity of the person or entity using the product (phone number, email address and so on). It is a generic way of identifying who is being charged for the usage.
requestId
The requestId is an identifier that uniquely identifies the usage interaction. If the usage is session based, the requestId must be the same across different operation types (Initiate, Update and Terminate). The requestId is used to locate the active session associated with the charging customer.
requestStart
The requestStart is the time at which the usage started.
For session-based usage requests, ECE observes the requestStart value for Initiate operation-type usage requests.
requestEnd
The requestEnd is the time at which the usage ended.
If the usage interaction has no duration, such as for event-based charging, the requestStart is equal to the requestEnd.
Note:
If the payload contains a non-null "DURATION" attribute (either as a top-level attribute or under a Requested Service Units (RSU) and Used Service Units (USU) block, its value will override the value of the requestEnd attribute.requestMode
The requestMode defines the mode of the usage request. Valid values are OFFLINE and ONLINE.For backward compatibility, the default value is ONLINE.
sequenceNumber
The sequenceNumber is the sequential session-centric attribute and is a type of subID you can apply for different types of charging within a session.
You cannot change the name of the fixed attributes.
Usage requests also contain configurable (dynamic) attributes. Configurable attributes are defined in the payload blocks of the event definition (request specification data defined in PDC when you enrich event definitions).
The ECE API is designed to receive usage requests and send usage responses for common operation types in the charging industry.
ECE usage charging supports the following operation types:
Table 13-1 Charging Operation Types Supported by ECE
Operation Type | Description |
---|---|
Initiate |
Commencement of a session-based charging operation. |
Update |
Continuation of a session-based charging operation. |
Terminate |
Conclusion of a single non-session based charging operation. |
Cancel |
Complete cancellation of a session-based charging operation. |
Refund_Amount |
Refund a specific amount to a specific balance resource. |
Refund_Unit |
Refund a calculated amount, based on units consumed, to the impacted resource(s). |
Debit_Amount |
Debit a specific amount to a specific balance resource. |
Debit_Unit |
Debit a calculated amount, based on Units consumed, to the impacted resource(s). |
Price_Enquiry |
Generate a price estimation without any balance reservations occurring. It is used when there isn't a high probability of receiving a charging request. For example, Price_Enquiry might be called to get the price of an event charge to display in a content portal. |
Start_Accounting |
Begin tracking usage without incurring balance impacts. |
Update_Accounting |
Continue tracking usage without incurring balance impacts. |
Balance_Query |
Return the user balance. |
Accounting_On_Off |
Clean left open session and reservation for a specific network element. |
Each charging operation type requires an input payload that supplies fields which are relevant to the charging operation.
The BALANCE_QUERY operation type is used for query requests. The query request is built using the Query Request Builder.
The ACCOUNTING_ON and ACCOUNTING_OFF operation types are used for management requests. Management requests are built using the Management Request Builder.
For offline charging, requests are typically submitted for a single event that represents the entire charge (using the Terminate operation type). Session-based operations such as Initiate and Update are not as common for offline charging; however, these operation types are used when using a stream protocol like Radius or Rf in which ECE is used to record the consumption of resources (quantity consumption) as the session continues.
ECE processes charging operations by forwarding usage requests to the applicable combinations of charge, alteration and distribution rate plans. ECE creates the rate plan expressions required for usage charging by using fields which are supplied in the request specification payloads.
The sample request specification files demonstrate the data ECE requires to support the charging operation types.
Your network mediation software receives network requests and transfers the relevant network-request fields from the network-request data structures into the usage-request payloads. The network mediation software program uses the usage-request builder APIs for transferring the relevant network-request fields.
The usage-request builder uses ECE request specification data in the ServiceSpec repository initially so that it knows the format to use to build usage requests. The same instance of a usage-request builder can create usage requests for the lifetime of the network mediation client application for a specified request specification payload definition. For example, a usage-request builder creates the same Voice/Usage usage request repeatedly until you change the request specification data for a Voice/Usage usage request.
When you change the payload definitions of an event definition (to extend its associated usage request) and deploy the new definitions into the ECE cluster, the usage-request builder will need to get the changes of the newly deployed request specification data.
The notification framework publishes external notifications, the data in which can be used by charging clients for further processing. For example, ECE can publish an external notification when a balance breaches a credit threshold value. The charging client application can use this information for sending an email to the customer informing the customer that a credit threshold has been breached.
See the discussion about notifications in BRM Elastic Charging Engine Concepts for information about the external notifications published by the notification framework.
ECE supports Multiple-Service Credit Control (MSCC) requests in which a Diameter application performs credit control for multiples services within the same session.
An MSCC request is a list of sub-requests that are targeted to the same customer, share the same operation type and session id, but individually apply to different products.
When ECE receives MSCC requests, it assigns a different session ID to each of its sub-requests. Doing this allows ECE to distinguish one sub-request from another when looking up the active session associated with each sub-request.
An MSCC request results in an MSCC response containing a sub-response for each sub-request. Each sub-response contains status indicating whether the sub-request succeeded or failed.
When ECE persists rated event information for MSCC requests in the Oracle NoSQL Database, note the following points:
Rated event information is persisted for each sub-request.
The NoSQL key for the rated event is based on the session ID that ECE assigned (not based on the original MSCC request session ID).
The ECE session ID in the Oracle NoSQL Database is a composite of the original usage request's session ID, the user identity and the product type, separated by underscore characters. For example:
Original MSCC requestId: 1313b2ab-d51e-4545-8bba-25c731daf10b
Usage request's userIdentity: 650123555
usage request's product type: VOICE
ECE session ID: 1313b2ab-d51e-4545-8bba-25c731daf10b_VOICE_650123555
MSCC support does not include support for rating groups (Rating-Group AVP), credit pools (G-S-U-Pool-Reference AVP where units of the service type are pooled in a credit pool) and credit control (as described in section 5.1.2 of IETF RFC 4006).
For for an example of how to send MSCC requests to ECE, see the SampleMultipleServicesLauncher sample program in the ECE SDK. For information about how to run ECE sample programs, see "About the ECE Sample Programs".
MSCC AVPs are part of the CCR and Diameter Gateway expects each Gy interface request type to be included in the MSCC group even if the request contains only a single service. When CCR is sent without MSCC AVPs, Diameter Gateway validates only the subscriber ID in the CCR and authenticates the subscriber.
See "About the ECE Sample Programs" for information about sample programs that demonstrate how to use the ECE charging API.