This chapter provides information about network integration for online charging using Oracle Communications Billing and Revenue Management Elastic Charging Engine (ECE) Diameter Gateway.
Before reading this chapter, you should be familiar with ECE concepts and architecture. See the following chapters in BRM Elastic Charging Engine Concepts:
ECE Overview
ECE System Architecture
The following steps summarize how to set up network integration for online charging using Diameter Gateway, which enables Diameter Gateway to do the following:
Receive Gy, Sp, and Sy Diameter requests from Diameter clients and translate them into ECE requests.
Submit ECE requests to ECE charging servers for credit-control processing.
Receive ECE request responses and translate them into respective Gy, Sp, and Sy Diameter message responses.
Send Diameter message responses to Diameter clients.
Consume JMS notifications from the ECE notification queue, construct Diameter notification messages from them, and send the notification messages to the appropriate Diameter clients.
Important:
Before sending requests to ECE using Diameter Gateway, you must first implement ECE with PDC and BRM. See "Integrating ECE with PDC" and "Integrating ECE with BRM" for instructions.Install ECE.
Diameter Gateway is included in the ECE Server software package.
Add Diameter Gateway node instances required for your topology and configure each instance.
See the discussion about post-installation tasks in BRM Elastic Charging Engine Installation Guide for instructions on how to add and configure Diameter Gateway node instances.
For all request types you receive from the network, ensure that your credit-control request (CCR) message formats adhere to the attribute value pair (AVP) fields that Diameter Gateway supports and requires.
For Gy interface Diameter requests, ensure that you have done the following:
Loaded your event definitions (which includes request specification data) from PDC into ECE.
Edited your mediation specification file and loaded it into ECE.
The mediation specification enables Diameter Gateway to associate each Gy interface Diameter request with its respective usage-request builder.
Configure notifications for Diameter Gateway.
Diameter Gateway listens for notifications on the ECE (JSM) notification queue (for push notifications from Elastic Charging Server).
You must enable the notification types to be generated in the ECE system. See "Configuring Notifications for Diameter Gateway".
You can set tuning parameters for how Diameter Gateway sends notifications to Diameter clients. For information, see the discussion about setting Diameter Gateway node properties in the post-installation tasks chapter of BRM Elastic Charging Engine Installation Guide.
If a Diameter client fails or becomes unavailable before receiving a notification message from a Diameter Gateway instance, Diameter Gateway can route the notification message to another available Diameter peer. For information, see "Configuring Alternative Diameter Peers for Notifications".
See "Configuring Notifications for Charging" for information about configuring the JMS credentials in ECE for the ECE notification queue.
Start the Diameter Gateway nodes.
When the Diameter Gateway nodes start, they automatically join the Coherence cluster gaining access to ECE caches and invocation services that it uses to send requests to ECE. At startup, the Diameter Gateway instances read from the ECE notification queue for notifications.
See the discussion about starting and stopping ECE in BRM Elastic Charging Engine System Administrator's Guide for information about starting Diameter Gateway nodes.
This section provides information about network integration for policy requests using Diameter Gateway.
Given that the technical implementation of Sp has not been defined by the 3GPP standards body, Diameter Gateway uses the Sh interface as the implementation to request and subscribe to policy-related information in the ECE server.
Diameter Gateway uses the ECE policy API for retrieving Sp and Sy information from ECE charging servers and sends the information to the Policy and Charging Rules Function (PCRF).
The following Sp (implemented as Sh) and Sy interface policy request types are processed by Diameter Gateway (using the ECE policy-request builders).
Sy:
Spending-Limit-Report-Request (SLR/SLA)
Subscribe-Notification-Request
Sp/Sh:
User-Data-Request (UDR)
Subscribe-Notifications-Request (SNR)
Push-Notification-Request (PNR)
Diameter Gateway manages notification subscriptions (when the PCRF subscribes and unsubscribes) for notifications due to Sy and Sp related updates.
Diameter Gateway listens for notifications on the ECE (JSM) notification queue (for push notifications from the Elastic Charging Server). For policy-driven charging, when changes occur to policy counters (balances) or to policy-related subscriber preferences that are associated with products that have an active policy session, ECE charging servers publish asynchronous notifications to the JMS notification queue. Diameter Gateway subscribes for receiving the policy notifications at startup and processes them as follows:
From the ECE spending-limit JMS notifications it receives, Diameter Gateway creates Sy (Spending-Status-Notification-Request (SNR)) messages for all subscribed sessions and routes them to the appropriate Diameter clients.
From the ECE subscriber-preferences JMS notifications it receives, Diameter Gateway creates Sp/Sh (Push-Notification-Request (PNR)) messages for all subscribed sessions and routes them to the appropriate Diameter clients.
For information about how Diameter Gateway processes policy requests, see the overview of Elastic Charging Engine and see the discussion about understanding charging scenarios in BRM Elastic Charging Engine Concepts.
For information about how Diameter Gateway uses the ECE policy management APIs to retrieve Sy-interface and Sp-interface data from the ECE server, see "Integrating Policy Clients with ECE".
To enable Diameter Gateway to create ECE requests for policy-driven charging, you must configure notifications for Diameter Gateway. See "Configuring Notifications for Diameter Gateway". You can configure alternate Diameter peers for each peer to which a Diameter Gateway instance connects for routing notifications. See "Configuring Alternative Diameter Peers for Notifications" for more information.
Ensure that your policy CCR message formats adhere to the to the well-known AVP fields of the 3GPP standard for Sh and Sy policy requests.
For information about how Diameter Gateway complies with standard AVPs for the Sy and Sh interfaces, see the Diameter Sy Protocol and Diameter Sh Protocol chapters of the BRM Elastic Charging Engine Diameter Gateway Protocol Implementation Conformance Statement.
This section provides information about network integration for Gy interface online charging requests using Diameter Gateway.
The following Gy interface credit-control request types are processed by Diameter Gateway (using ECE usage-request builders):
Session-based requests
Initiate
Update
Terminate
Cancel
Price enquiry
Direct debit
Refund
For Gy interface credit-control requests, you must do the following for Diameter Gateway to process the requests successfully:
Present Gy interface request types inside of a Multiple-Service Credit Control (MSCC) group.
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. Contain the following Gy interface request types in a MSCC group:
Initiate
Update
Terminate
Cancel
Price enquiry
Direct debit
Refund
For more information about MSCC requests and ECE, see "Using Multiple Services Credit Control (MSCC)".
Add network attributes for all event attributes in the event definition that apply to usage-request charging operations.
Diameter Gateway uses the network specification and corresponding network attributes to dynamically populate the event attributes of ECE requests with the CCR AVP data of your incoming Diameter request.
Edit your mediation specification file and load your mediation specification into ECE.
The mediation specification enables Diameter Gateway to associate each Gy interface Diameter request with its respective usage-request builder.
For information about how Diameter Gateway complies with standard AVPs for the Gy interface, see the BRM Elastic Charging Engine Diameter Gateway Protocol Implementation Conformance Statement.
Diameter Gateway uses incremental based accounting behavior when processing usage requests.
Diameter Gateway listens for notifications on the ECE (JSM) notification queue (for push notifications from the Elastic Charging Server). From the ECE reauthorization-request JMS notifications it receives, Diameter Gateway creates Gy reauthorization-request (RAR) messages and sends them to Diameter clients running the applicable active Gy sessions.
The Diameter Gateway uses ECE usage-request builders to construct request and response messages for Gy interface request types.
Diameter Gateway constructs usage requests automatically provided the required request specification data (that pertains to the requests you want to send to the ECE charging servers) has been published to ECE from PDC by way of the Pricing Updater.
Diameter Gateway includes a usage-request builder for constructing usage requests (as well as different builders for building other requests ECE supports, such as balance query requests, and top-up requests, and so on). When you start Diameter Gateway nodes, the usage-request builder reads the request specification data and sends requests that adhere to the specifications.
When you perform network enrichment of the event definition for your events in PDC, you add network attributes for all event attributes in the event definition that apply to usage-request charging operations. Diameter Gateway uses the network specification and corresponding network attributes to dynamically populate the event attributes of ECE requests with the CCR AVP data of your incoming Diameter request.
You can have Diameter Gateway dynamically populate some fields using the event-attribute to network-attribute you map in PDC and you can have Diameter Gateway explicitly populate other fields using your own custom extension code (for example, when using the Pre-OCS extension, you can explicitly populate the ECE payload for fields using your Pre-OCS extension mechanism).
For information about mapping event attributes to network attributes, see the discussion about network enrichment of event definitions in PDC User's Guide.
The mediation specification enables Diameter Gateway to associate each Diameter request with its respective usage-request builder. Diameter Gateway uses the mediation specification to derive which product and event type combination applies to an incoming Diameter request, allowing it to select the request specification that applies to the event to be rated.
Diameter Gateway reads the mediation specification to automatically create usage requests by dynamically mapping the values of the AVPs in the Diameter request to their corresponding payload items that are defined in request specifications.
You configure Diameter Gateway to base its selection of a request specification on the presence of any combination of these four AVPs in the Diameter request:
Service-Context-Id AVP
Service-Identifier AVP
Rating-Group AVP
Event-Timestamp AVP
From the preceding four AVP field values, Diameter Gateway derives the following three fields which uniquely identify the request specification to use for building the ECE request:
ProductType
EventType
Version
You can configure Diameter Gateway to base its selection of a request specification on the presence of a custom AVP by using the Diameter Gateway Request-Received extension. You use the Request-Received extension to modify one of the four AVP values (Service-Context-Id AVP, Service-Identifier AVP, Rating-Group AVP, or Event-Timestamp AVP) in the Diameter request so that a different Diameter mediation mapping is produced (for a ProductType, EventType, and Version). For information about the Diameter Gateway Request-Received extension, see BRM Elastic Charging Engine Extensions.
To edit the mediation specification:
Create a mediation specification file or edit an existing one.
A sample mediation specification file is available at ECE_home/oceceserver/sample_data/config_data/specifications/ece_end2end/diameter_mediation.spec.
It is recommended to create only one mediation specification file to represent your mediation specification. You can have only one mediation specification loaded in the ECE cluster and the last one loaded takes precedence.
In the mediation specification file, add a row (in the table) for each event to be rated that specifies the following information:
Rating-Group AVP
The Rating-Group AVP value sent in the Diameter message.
Null is an acceptable value if the field is not expected to be present on the CCR.
Service-Context-Id AVP
The Service-Context-Id AVP value sent in the Diameter message.
Null is an acceptable value if the field is not expected to be present on the CCR.
Service-Identifier AVP
The Service-Identifier AVP value sent in the Diameter message.
Null is an acceptable value if the field is not expected to be present on the CCR.
ProductType
The product type you have defined for the event in its associated request specification.
EventType
The event type you have defined for the event in its associated request specification.
Version
The version number of the request specification that you want to apply to the event.
Define the Service-Identifier, Rating-Group, and Service-Context-Id for each request specification defined in the mediation table.
For each received Diameter request, Diameter Gateway correlates the Service-Context-Id, Service-Identifier, Rating-Group, and Event-Timestamp AVP values (that you defined in the mediation specification) to the usage-request builder that applies to the event to be rated (for the applicable version, product type, and event type that you defined in the event definition (request specification).
(Optional) In the ValidFrom field of the table, set a future date and time when you want Diameter Gateway to recognize a newly deployed request specification.
For example, to have requests processed according to a new specification on April 16, 2015, you would enter:
| ValidFrom | "2015-04-16T12:01:01"
You can also specify a time zone. For example,
| ValidFrom | "2015-04-16T12:01:01 PST"
If a time zone is not sent, then the ValidFrom field is assumed as UTC.
Save the mediation specification file with a .spec suffix (for example, diameter_mediation.spec) into the directory where you save your configuration data.
Verify that the directory specified in the ECE_home/oceceserver/config/management/migration-configuration.xml file is the directory where you save your configuration data.
Load the mediation specification file into the ECE server by running the configLoader utility:
start configLoader
The utility deploys your mediation specification to the ECE cluster. Any earlier mediation specification that was in the ECE cluster is overwritten.
Any time you deploy a new version of a mediation specification (or request specification) into the repository, Diameter Gateway re-creates its in-memory usage-request builder map and begins using the mapping definitions (to send requests that adhere to the specifications) provided that the ValidFrom date is reached.
Perform a rolling restart of Diameter Gateway node instances.
This section provides information about network integration for balance query requests using Diameter Gateway.
Diameter Gateway uses custom AVPs for querying for remaining-balance customer data; these Oracle AVPs have an ORA- prefix.
For a balance query, the CC-Request-Type AVP in the CCR must be set to 4 (EVENT_REQUEST) and the Requested-Action AVP must be set to 5 (which is an undefined value in the 3GPP standard specification).
For information about the AVPs that Diameter Gateway requires for balance queries, see the section about Gy Balance Query Request/Response AVPs in BRM Elastic Charging Engine Diameter Gateway Protocol Implementation Conformance Statement.
For information about the data types for custom balance-query AVP fields, see the ECE_home/oceceserver/config/diameter/dictionary_main.xml file.
This section provides information about network integration for top-up requests using Diameter Gateway.
Diameter Gateway exposes a custom event request for top-up operations that does the following:
Credits the specified balances, optionally setting valid-from and valid-to dates
Optionally extends the validity of existing balances credited by the top-up
Returns that the top-up succeeded or failed
Returns updated balance information in the top-up response
Diameter Gateway uses custom AVPs for processing top-up requests; these Oracle AVPs have an ORA- prefix.
For a top-up, the CC-Request-Type AVP in the CCR must be set to 4 (EVENT_REQUEST) and the Requested-Action AVP must be set to 4 (which is an undefined value in the 3GPP standard specification).
Diameter Gateway uses custom AVPs for processing top-up requests; these Oracle AVPs have an ORA- prefix.
For information about the AVPs that Diameter Gateway requires for top-up requests, see the section about Gy Top-up Request/Response AVPs in BRM Elastic Charging Engine Diameter Gateway Protocol Implementation Conformance Statement.
For information about the data types for custom top-up-request AVP fields, see the ECE_home/oceceserver/config/diameter/dictionary_main.xml file.
Diameter Gateway supports Multiple-Service Credit Control (MSCC) requests in which a Diameter application performs credit control for multiples services within the same session.
Diameter Gateway only supports MSCC requests for usage request processing (all usage-request charging operations must be contained in an MSCC group even if the request contains only a single service).
When multiple subscriber ID types come in on the CCR message, not all subscription identifiers may be provisioned for your ECE implementation. For example, you might have separate online charging systems for handling different subscription services. You can now configure Diameter Gateway to look up customer public user identity information based only on the subscription identifier types for which you have provisioned your ECE implementation.
The possible customer subscription IDs that pertain to various customer services are defined by the Subscription-Id grouped AVP in the CCR message. Multiple subscription identifier types can be provided in the group's Subscription-Id-Type AVP field. The customer may have all of the following subscription identifiers for various networks on which the customer uses services: MSISDN, IMSI, SIP, NAI, PRIVATE.
For Diameter Gateway to look up customer public user identity information based on your subscription-identifier-type configuration, do the following:
Open your mediation specification file, diameter_mediation.spec.
diameter_mediation.spec is in the directory specified by the configObjectsDataDirectory parameter in the ECE_home/oceceserver/config/management/migration-configuration.xml file.
Where multiple subscription types are expected in the CCR for the event to be rated, locate the row that specifies the rating group, service identifier, and service context ID for the event.
Your subscription-identifier-type configuration is relevant for the combination of the given Service-Context-Id, Service-Identifier, and Rating-Group AVP values specified in the row for the event to be rated.
In the Subscription-Id-Type column for that row, enter the subscription-identifier-type configuration of your choice.
For each received CCR Diameter message that includes multiple subscriber ID types, Diameter Gateway uses your subscription-identifier-type configuration for looking up the public user identity.
The subscription-identifier-type configuration options are as follows:
For Diameter Gateway to perform a customer lookup by using only one subscription ID type, enter the full string name of that Subscription-Id-Type.
Enter the name exactly as it is defined in the RFC specification (in capitals) and enclose it with quotation marks.
The possible values you can enter in the Subscription-Id-Type column for the Subscription-Id-Type are as follows (values in bold):
"END_USER_E164"
The identifier is in international E.164 format (for example, MSISDN), according to the ITU-T E.164 numbering plan defined in [E164] and [CE164].
"END_USER_IMSI"
The identifier is in international IMSI format, according to the ITU-T E.212 numbering plan as defined in [E212] and [CE212].
"END_USER_SIP_URI"
The identifier is in the form of a SIP URI, as defined in [SIP].
"END_USER_NAI"
The identifier is in the form of a Network Access Identifier, as defined in [NAI].
For example, if you enter "END_USER_NAI" in the Subscription-Id-Type column for that event, Diameter Gateway uses only the subscription identifier type END_USER_NAI to perform a customer public user identity lookup for those events and ignores all other subscription identifier types that may be included in the CCR for those events.
DiameterMediationTable {
Service-Context-Id | Service-Identifier | Rating-Group | ProductType | EventType | Version | Subscription-Id-Type | ValidFrom |
"gy.service@example.com" | "1" | "10" | "VOICE" | "V_USAGE" | 1.0 | "END_USER_NAI" | "2012-12-31T12:01:01 PST" |
"gy.service@example.com" | "1" | "11" | "DATA" | "D_USAGE" | 1.0 | "END_USER_IMSI" | "2012-12-31T12:01:01 PST" |
}
For Diameter Gateway to perform a customer lookup by using a subscription ID type determined by the order that you list subscription ID types in the mediation specification, enter a comma-delimited list in the order that Diameter Gateway is to resolve the subscription ID type.
The following example shows a comma-delimited list for which Diameter Gateway first looks up the public user identity of the customer based on the SIP URI subscription identifier, and secondly based on the IMSI. In this case Diameter Gateway ignores all other subscription ID types that may be included in the CCR.
DiameterMediationTable {
Service-Context-Id | Service-Identifier | Rating-Group | ProductType | EventType | Version | Subscription-Id-Type | ValidFrom |
"gy.service@example.com" | "1" | "12" | "DATA" | "D_USAGE" | 1.0 | "END_USER_SIP_URI, END_USER_IMSI" | "2012-12-31T12:01:01 PST" |
}
For Diameter Gateway to perform a customer lookup by using the first subscription ID type that is read in the CCR (all other subscription ID types that may be included in the CCR are ignored), leave the Subscription-Id-Type column blank. This type of configuration is shown in the fourth row of the sample mediation specification.
DiameterMediationTable {
Service-Context-Id | Service-Identifier | Rating-Group | ProductType | EventType | Version | Subscription-Id-Type | ValidFrom |
"gy.service@example.com" | "1" | "13" | "SMS" | "S_USAGE" | 1.0 | "" | "2012-12-31T12:01:01 PST" |
}
Save the mediation specification file.
Run the configLoader utility to load your mediation specification in the ECE cluster:
start configLoader
When your mediation specification is loaded, the earlier version of your mediation specification (that was in the ECE cluster) is overwritten and Diameter Gateway uses the configuration of the newly loaded mediation specification.
Your subscription-identifier-type configuration is used by Diameter Gateway for all usage-charging operation types: Initiate, Update, Terminate, PriceEnquiry, BalanceQuery, TopUp, Debit, and Refund.
To troubleshoot issues that may occur with your subscription-identifier-type configuration, note the following points:
If the subscription IDs cannot be resolved correctly with the values supplied in the diameter_mediation.spec file, errors are logged in the Diameter Gateway log files.
In a DEBUGGING environment, you can enable DEBUG messages in the log4j.properties file as shown here:
log4j.logger.oracle.communication.brm.charging.ecegateway.diameter.framework=DEBUG log4j.logger.oracle.communication.brm.charging.ecegateway.diameter.gy=DEBUG
If the subscription IDs cannot be found as configured in the diameter_mediation.spec file, you can expect an Errant result-code of DIAMETER_MISSING_AVP (5005) or DIAMETER_INVALID_AVP_VALUE (5004).
If you introduce custom AVPs (to introduce new ways for charging for your services), you define your custom AVPs in the ECE_home/oceceserver/config/diameter/dictionary_custom.xml file to define their data types.
After modifying the dictionary_custom.xml file, perform a rolling restart of Diameter Gateway nodes in your topology.
For AVPs that apply to usage-request processing, you add network attributes for all event attributes in the event definition so that they can be dynamically mapped to ECE payload fields by Diameter Gateway (for information about mapping event attributes to network attributes, see the discussion about network enrichment of event definitions in PDC User's Guide). You also put a path to your AVP field to an MSCC group block.
To enable Diameter Gateway to consume notifications from the ECE notification queue:
Note:
The following steps assume ECE is installed and required ECE post-installation tasks are completed. See BRM Elastic Charging Engine Installation Guide for information.On the Oracle WebLogic server, verify that the ECE event notification queue (a JMS topic) has been created.
See the discussion about ECE post-installation tasks for information about creating the ECE notification queue.
In ECE, verify that JMS credentials have been configured correctly so that ECE can publish notifications to the ECE notification queue.
See "Configuring Notifications for Charging" for information about configuring JMS credentials in ECE.
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.notification.
Expand Attributes.
Set the appropriate type of notification (such as top-up or advice of charge) to the appropriate value:
For information about each notification, see the NotificationConfigMBean of the BizParamConfigMBean package in BRM Elastic Charging Engine Java API Reference.
Peer details are configured in Diameter Gateway to filter and route the notifications for the peers to which Diameter Gateway connects. Each Diameter Gateway instance listens to a registered peer. The connection is initiated from the peer to send the respective notifications. If a Diameter Gateway instance sends a notification message to its peer and the peer is unavailable or the peer fails after receiving the notification message, the Diameter Gateway instance retains the notification messages and sends them to another available peer based on your alternative-peer configuration.
To configure alternative Diameter peers for notifications:
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.
To add a Diameter peer, expand charging.diameterGatewayPeerConfigurations.
Expand Operations and select addPeer.
Specify the value for the following parameter:
peerName. Enter the name of the Diameter peer.
Click the addPeer button.
The peer is added to Diameter Gateway.
Expand charging.diameterGatewayPeerConfigurations.Peer_Name, where Peer_Name is the name of the Diameter peer.
Expand Attributes.
For each peer connected to Diameter Gateway, configure alternative peers by specifying values for the following attribute:
alternatePeerNames. Enter the name of the alternative peer for the specified Diameter peer. You can specify two alternative peers for each Diameter peer. If the peer connected to Diameter Gateway fails or if it is unavailable, Diameter Gateway routes the notifications to the alternate peers configured for the peer.
Diameter Gateway can be configured to use a degraded mode operating mode if the Elastic Charging Server (charging server nodes) become unavailable.
Diameter Gateway actively monitors the health of the Elastic Charging Server. If the Elastic Charging Server becomes unavailable (such as going below the charging-server health threshold), Diameter Gateway sends the DIAMETER_TOO_BUSY result code response to network requests.
See the discussion about configuring the charging-server health threshold and the discussion about checking the ongoing health of ECE charging server nodes in BRM Elastic Charging Engine System Administrator's Guide for more information.