Connecting ECE to a Diameter Client

21 Connecting ECE to a Diameter Client

You can set up network integration for online charging by using the Oracle Communications Elastic Charging Engine (ECE) Diameter Gateway.

Topics in this document:

Overview of Network Integration Using Diameter Gateway

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 notifications from the ECE Notification queue or topic, create Diameter notification messages from them, and send the notification messages to the appropriate Diameter clients.

For information about conformance with industry standards, see ECE Diameter Gateway Protocol Implementation Conformance Statement.

To implement Diameter Gateway:

Create Apache topics and connect ECE to them. See "Creating Kafka Topics for ECE Integration".
For all of the 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.
Configure Diameter Gateway to retrieve Sp and Sy information. See "Network Integration for Sp and Sy Interface (Policy) Requests".
For Gy interface Diameter requests, ensure that you have done the following:
- Defined any custom service-event mappings in PDC.
- 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.
  
  See "Network Integration for Gy Interface Requests".
Configure the Diameter Gateway nodes for online charging. See "Configuring Diameter Gateway Nodes for Online Charging".
Configure the Diameter Gateway to terminate requests that have timed out at the client. See "Checking for Client-Side Timeouts in Diameter Gateway".
Configure ECE to send your desired notification types to Diameter Gateway. See "Configuring ECE to Publish Notifications to Diameter Gateway".
(Optional) Configure Diameter Gateway to add custom AVPs to usage requests. See "Adding Custom AVPs for Usage Requests".
(Optional) Configure whether Diameter Gateway uses incremental accounting logic, cumulative accounting logic, or both. See "Using Incremental or Cumulative Accounting for Usage Requests".
(Optional) Configure ECE and Diameter Gateway to use WebLogic queues, rather than Kafka topics, for notifications. See "Configuring WebLogic Queues for Notifications".
(Optional) Configure Diameter Gateway to include both the main and loan balance information in balance query responses. See "Including Loan Sub-Balance in Balance Queries".
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 start up, the Diameter Gateway instances read from the ECE Notification queue or topic for notifications.

Network Integration for Sp and Sy Interface (Policy) Requests

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 retrieves Sp and Sy information from ECE charging servers and sends the information to the Policy and Charging Rule 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 associated with charge offers that have an active policy session, ECE charging servers publish asynchronous notifications to the JMS notification queue. Diameter Gateway receives the policy notifications at startup and processes them as follows:

From spending-limit JMS notifications, Diameter Gateway creates Sy (Spending-Status-Notification-Request (SNR)) messages for all subscribed sessions and routes them to the appropriate Diameter clients.
From subscriber-preferences JMS notifications, 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 uses the ECE policy management APIs to retrieve Sy-interface and Sp-interface data from the ECE server, see "Configuring Policy-Driven Charging".

To enable Diameter Gateway to create ECE requests for policy-driven charging, you must configure notifications for Diameter Gateway. See "Configuring WebLogic Queues for Notifications". You can configure alternative Diameter peers for each peer to which a Diameter Gateway instance connects for routing notifications. See "Configuring Alternative Diameter Peers for Notifications".

Ensure that your policy CCR message formats adhere to the well-known AVP fields of the 3GPP standard for Sh and Sy policy requests.

Network Integration for Gy Interface Requests

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 inquiry
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 one service. Contain the following Gy interface request types in an MSCC group:
- Initiate
- Update
- Terminate
- Cancel
- Price inquiry
- Direct debit
- Refund
For more information about MSCC requests and ECE, see "Configuring Multiple Services Credit Control".
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.

See "How Diameter Gateway Creates Usage Requests".
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.

See "Editing the Mediation Specification File".

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 RAR messages and sends them to Diameter clients running the applicable active Gy sessions.

The Diameter Gateway uses ECE usage-request builders to create request and response messages for Gy interface request types.

How Diameter Gateway Creates Usage Requests

Diameter Gateway creates usage requests based on the event definitions sent from PDC to ECE. Diameter Gateway includes a usage-request builder for creating usage requests (as well as different builders for building other requests ECE supports, such as balance query requests, top-up requests, and so on). When you start Diameter Gateway nodes, the usage-request builder reads the event definition data and sends requests that adhere to the specifications. See "About Usage Request Fixed Attributes" for more information on the attributes.

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).

About Usage Request Fixed Attributes

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).

Editing the Mediation Specification File

The mediation specification enables Diameter Gateway to associate each Diameter request with its respective usage-request builder. Diameter Gateway uses the mediation specification to determine which service and event combination applies to an incoming Diameter request, enabling it to select the event definition that applies to the event to be rated.

You configure Diameter Gateway to base its selection of event definitions on any combination of the following AVPs in the request:

Service-Context-Id
Service-Identifier
Rating-Group
Event-Timestamp

From the preceding AVP values, Diameter Gateway derives the following fields, which uniquely identify the event definition to use for building the ECE request:

ProductType (service)
EventType
Version

You can configure Diameter Gateway to base its event definition on a custom AVP by using the Diameter Gateway Request-Received extension. You use that extension to modify one of the AVP values in the request so that a different Diameter mediation mapping is produced for a service, event, and version.

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/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 service you have defined for the event.
- EventType
  
  The event definition you have defined for the event.
- Version
  
  The version number of the event definition object that you want to apply to the event.
Define the Service-Identifier, Rating-Group, and Service-Context-Id for each event definition object 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, service, and event).
(Optional) In the ValidFrom field of the table, set a future date and time when you want Diameter Gateway to recognize a newly deployed event definition object.

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/config/management/migration-configuration.xml file is the directory where you save your configuration data.
Run 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 into the repository, Diameter Gateway recreates 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.
Load the mediation specification file into the ECE server by using the configLoader utility.

Network Integration for Gy Balance Query Requests

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 data types for custom balance-query AVP fields, see the ECE_home/config/diameter/dictionary_main.xml file.

Network Integration for Gy Top-Up Requests

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
Return that the top-up succeeded or failed
Return 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 data types for custom top-up-request AVP fields, see the ECE_home/config/diameter/dictionary_main.xml file.

Sending Multiple-Service Credit Control (MSCC) Requests from Diameter Gateway

Diameter Gateway supports MSCC requests in which a Diameter application performs credit control for multiple services within the same session.

Diameter Gateway only supports Multiple-Service Credit Control (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).

Configuring Subscriber ID Lookups

When multiple subscriber ID types come in on the CCR message, not all subscription identifiers may be provisioned for your ECE system. For example, you might have separate online charging systems for handling different subscription services. You can 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 system.

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, and 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.

The file is in the directory specified by the configObjectsDataDirectory parameter in the ECE_home/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).

Configuring Diameter Gateway Nodes for Online Charging

To configure Diameter Gateway node to process online charging requests:

Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the ECE Configuration node.
Expand charging.diameterGatewayConfigurations.Instance_Name, where Instance_Name is the name of the instance to configure.
Expand Attributes.

Specify values for all the attributes required to configure the instance.

See Table 21-1 for attribute descriptions and default values.

Table 21-1 Diameter Gateway Node Configuration Attributes and Values

Attribute Name	Default Value	Description
name	"diameterGateway1"	The name of the Diameter Gateway instance. Name Diameter Gateway node instances consistently and uniquely (for example, diameterGateway1, diameterGateway2, and so on. If you change the name of an existing instance, you must update the name in the ECE_home/config/eceTopology.conf file.
clusterName	"cluster1"	The cluster name of the Diameter Gateway instance. ECE uses both name and clusterName to identify a Diameter Gateway instance. You must specify a different cluster name if you are configuring Diameter Gateway nodes with the same name. Note: Ensure that this cluster name matches the cluster name in the ECE_home/config/charging-coherence-override-secure-prod.xml file.
diameterTrafficPort	"3868"	The port (on the physical host computer running the Diameter Gateway node instance) the Diameter Gateway instance listens on to handle Diameter messages. When adding new Diameter Gateway instances, choose a port number that is not used by another application. When multiple Diameter Gateway instances run on the same physical host computer, each instance must use a different port number.
ioThreadPoolSize	"10"	The number of threads used by the network I/O thread pool. The valid values are greater than zero and up to any number the system resources allow.
responseTimeout	"10"	The maximum duration, in seconds, the Diameter Gateway instance waits for a response from the Diameter client. If the Diameter Gateway instance does not receive a response from the Diameter client within the specified duration, the Diameter Gateway instance stops waiting for a response and removes the notification from the JMS queue. The valid values are greater than zero and up to any number the system resources allow.
watchDogInterval	"30"	The duration in seconds that the Diameter Gateway instance waits before it issues a Device-Watchdog-Request message (DWR).
originHost	No default value Setting a value for this field is mandatory.	The Origin-Host attribute-value pair (AVP) to be sent in the Diameter request. You assign this unique identifier to your Diameter Gateway server on its host. It can be any string value.
originRealm	No default value Setting a value for this field is mandatory.	The Origin-Realm AVP to be sent by the Diameter Gateway in outgoing Diameter requests. You assign this signaling realm (domain) to your Diameter Gateway server. You must set the same origin realm value for all Diameter Gateway instances in the same ECE topology.
diameterTrafficHost	""	The network interface (on the physical or virtual host computer running the Diameter Gateway node instance) that the Diameter Gateway node binds to and listens on for Diameter messages. The value can be an IP address or a host name. The value can also be an empty string (the default). In that case, the Diameter Gateway instance listens for Diameter messages on all network interfaces available on the server.
diameterTrafficHostSctp	""	When SCTP is used, the network interface (on the physical or virtual host computer running the Diameter Gateway node instance) that the Diameter Gateway node binds to and listens on for Diameter messages (sent from Diameter clients). The value can be: One or more SCTP IP addresses. For multihoming systems, separate multiple IP addresses with a comma (,). For example: 10.240.179.147,10.240.182.149 One or more host names. An empty string, which disables the SCTP transport. Your operating system must support SCTP to use this configuration. If not, install the SCTP system package for your operating system version.
loopback	"false"	Specifies the loopback setting for performance testing. The valid values are: True specifies that the Diameter Gateway instance does not send the credit-control request to ECE. Instead, the Diameter Gateway instance returns the success result code to the network element. False specifies that the Diameter Gateway instance sends the credit-control request to ECE.
requestProcessorThreadPoolSize	"10"	The number of threads used by the request-processor thread pool. The request-processor thread pool is a Diameter Gateway thread pool dedicated to processing Diameter requests handed off to it from the I/O thread pool. The valid values are greater than zero and up to any number the system resources allow.
requestProcessorBatchSize	"10"	The batch size of the Diameter requests handed off by the network I/O thread pool to the request-processor thread pool. The valid values are greater than zero and up to any number the system resources allow.
notificationThreadPoolSize	"10"	The number of threads used by the Diameter Gateway instance to process notification messages. The valid values are greater than zero and up to any number the system resources allow. Tune this value to the expected workload in the deployed environment.
maxNotificationCommitSize	"100"	The maximum number of dequeued notification messages from the JMS topic that can remain uncommitted. If the number of dequeued notification messages from the JMS topic exceeds this number, the Diameter Gateway instance stops reading messages until the read messages are committed.
maxWaitTimeNotificationCommit	"3600000"
ccFailover	"FAILOVER_SUPPORTED"	Indicates if the Diameter Gateway instance operates in a cluster that supports failover. The valid values are: FAILOVER_SUPPORTED FAILOVER_NOT_SUPPORTED The value set here is the value the Diameter Gateway instance sends for the CC-Session-Failover AVP in all credit-control answers (CCAs) it produces. For more information, see the Diameter Credit-Control Application standard at: `https://tools.ietf.org/html/rfc4006#section-8.4`
creditControlFailureHandling	"RETRY_AND_TERMINATE"	Indicates how the Diameter client should proceed if a CCA is not received before the Tx timeout. The valid values are: TERMINATE CONTINUE RETRY_AND_TERMINATE The value set here is the value the Diameter Gateway instance sends for the Credit-Control-Failure-Handling AVP in all CCAs it produces. For more information, see the Diameter Credit-Control Application standard at: `https://tools.ietf.org/html/rfc4006#section-8.14`
directDebitingFailureHandling	"TERMINATE_OR_BUFFER"	Indicates how the Diameter client should proceed if a Direct Debit CCA is not received before the transaction timeout. The valid values are: TERMINATE_OR_BUFFER CONTINUE The value set here is the value the Diameter Gateway instance sends for the Direct-Debiting-Failure-Handling AVP in all credit-control answers (CCAs) it produces. For more information, see the Diameter Credit-Control Application standard at: `https://tools.ietf.org/html/rfc4006#section-8.15`
allowMultipleConnectionsPerPeer	"false"
sctpMaxInStream	"0"	The maximum number of incoming streams allowed per association. The valid range is 0 to 65535.
sctpMaxOutStream	"0"	The maximum number of outgoing streams allowed per association. The valid range is 0 to 65535.
sctpSendBufferSize	"0"	The buffer size for sending data (in bytes). The valid range is 0 to 2147483647. This attribute determines the maximum amount of data that can be sent in a single transaction. You can increase or decrease the size based on your requirements.
sctpReceiveBufferSize	"0"	The buffer size for receiving data (in bytes). The valid range is 0 to 2147483647. This attribute determines the SCTP receiver window size. You can increase or decrease the size based on your requirements. For example, you can increase the size for high-volume connections or decrease the size if you want to limit the incoming data backlog.
notificationListenerConnectionPoolSize	"10"	The connection pool size for notification listeners.
kafkaPartition	"4"	The number of Kafka partitions the notification listeners should consume messages from.
dgwNotifNetworkResponseTimeoutAdder	"200"	The interval, in milliseconds, the Diameter Gateway instance waits for a response from the notification topic.
ingressRequestTimeoutMs	"3000"	How long the client waits for a response, in milliseconds, before timing out. After this amount of time, the Diameter Gateway terminates the request. The default is 3000. Note: Set this to a slightly lower value than the client's timeout to account for the time spent traversing the network.
enableNetworkExpiration	"true"	Whether to calculate the ingress request timeout using the time stamp contained in the request payload (true) or the time the message arrived at the Diameter Gateway (false). The default is true.

Checking for Client-Side Timeouts in Diameter Gateway

Client applications can contain their own request timeouts that activate when ECE takes too long to respond. When this occurs, the client application abandons the request, but ECE may continue to process the request and send a response, which the client discards. This extra processing is unnecessary and can be detrimental to ECE production systems approaching overload conditions. To improve performance, you can configure the Diameter Gateway to terminate requests that have timed out on the client side.

To configure the Diameter Gateway to check for client-side timeouts:

Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the ECE Configuration node.
Expand charging.diameterGatewayConfigurations.name, where name is the name of the Diameter Gateway instance.
Expand Attributes.
Specify timeout values for the Diameter Gateway instance:
- ingressRequestTimeoutMs: Specifies how long the client waits for a response, in milliseconds, before timing out. After this amount of time, the Diameter Gateway terminates the request. The default is 3000.
  
  Note:
  
  Set this to a slightly lower value than the client's timeout to account for the time spent traversing the network.
- enableNetworkExpiration: Specifies whether to calculate the ingress request timeout using the time stamp contained in the request payload (true) or the time the message arrived at the Diameter Gateway (false). The default is true.
Expand charging.brsConfigurations.name, where name is the name of the BRS instance.
Expand Attributes.
Specify timeout values for the BRS instance:
- requestMaxRetry: Specifies the maximum number of time the BRS retries sending the ingress request to ECS. Use a value between 1 and 5. The default is 3.
- requestRetryWaitTimeMs: Specifies the amount of time, in milliseconds, between each retry attempt. The default is 5.

When a request is terminated, the Diameter Gateway logs an error and sets the ResponseConsumerFailureCode field to Expired in the response to the client.

Configuring ECE to Publish Notifications to Diameter Gateway

You can enable ECE to send SNR and RAR notifications to the ECE Notification topic, where they will be retrieved by the Diameter Gateway. To do so:

Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the ECE Configuration node.
Expand charging.server.
Expand Attributes.
Set the kafkaEnabledForNotifications property to true.
Expand charging.notification.
Expand Attributes.
Set the rarNotificationMode and spendingLimitNotificationMode properties to one of the following:
- NONE: ECE does not send this notification type.
- ASYNCHRONOUS: ECE sends asynchronous notifications to the ECE notification topics.
  
  If configured to do so, the Diameter Gateway will consume notifications from the ECE notification topics and dispatch them through a REST API call.

Adding Custom AVPs for Usage Requests

If you introduce custom AVPs (to introduce new ways for charging for your services), you define your custom AVPs in the ECE_home/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. You also put a path to your AVP field to an MSCC group block.

Using Incremental or Cumulative Accounting for Usage Requests

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 the active session duration based on the units 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 creating your usage request builder, specify the accounting behavior 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.

Note:

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 the attribute INPUT_VOLUME on the usage request, the RUMs must be defined with the same name.

Configuring Accounting Mode for Diameter Gateway

You can configure Diameter Gateway to use both incremental-based and cumulative-based accounting logic when processing usage requests. You can perform this by specifying the accounting mode in the mediation specification file. The accounting mode indicates to Diameter Gateway whether to use incremental-based or cumulative-based accounting logic.

To configure the accounting mode for Diameter Gateway:

Open the Diameter mediation specification file, diameter_mediation.spec.

For the location of the diameter_mediation.spec file, see the configObjectsDataDirectory parameter in the ECE_home/config/management/migration-configuration.xml file.
For each event to be rated (in each row), specify the accounting mode in the UnitReportingMode column. Valid values are:
- INCREMENTAL
- CUMULATIVE
For example:
```
Service-Context-Id       | Service-Identifier | Rating-Group | ProductType | EventType | Version | Subscription-Id-Type | ValidFrom                | UnitReportingMode |
"gy.service@example.com" | "1"                | "10"         | "VOICE"     | "V_USAGE" | 1.0     | ""                   | "2024-3-31T12:01:01 PST" | "INCREMENTAL"     |
"gy.service@example.com" | "1"                | "11"         | "DATA"      | "D_USAGE" | 1.0     | ""                   | "2024-3-31T12:01:01 PST" | "CUMULATIVE"      |
```
The default accounting mode is Incremental. If you specify null or if you do not specify a mode in the UnitReportingMode column, Diameter Gateway uses the default accounting mode when processing usage requests. This supports backward compatibility.

Your accounting mode configuration is applicable for the combination of the given values specified in the row for the event to be rated. You can also configure different accounting modes for the same product and event type combination.
Save and close the file.
Run the configLoader utility to load your mediation specification in the ECE cluster:
```
start configLoader
```
When the 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.
Go to the ECE_home/bin directory.
Start ECC:
```
./ecc
```
Do one of the following:
- If the Diameter Gateway instance is not running, start it.
  
  The instance reads its configuration information by name at startup.
- If the Diameter Gateway instance is running, stop and restart it.
For information about stopping and starting Diameter Gateway instances, see "Starting and Stopping ECE" in BRM System Administrator's Guide.

Configuring WebLogic Queues for Notifications

To configure Diameter Gateway to listen for notifications from ECE, you must specify the types of notifications that ECE generates.

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".

To enable Diameter Gateway to consume notifications from an ECE notification queue set up in WebLogic:

Note:

The following steps assume that ECE is installed and that the required ECE postinstallation tasks have been completed.

On the Oracle WebLogic server, verify that the ECE notification queue (a JMS topic) was created.
In ECE, verify that JMS credentials were configured correctly so that ECE can publish notifications to the ECE notification queue.

See "About ECE Notifications" for information.
Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
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. See "About ECE Notifications" for information.

Configuring Alternative Diameter Peers for Notifications

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 configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the ECE Configuration node.
Expand charging.diameterGatewayPeerConfigurations.
Expand Attributes.
For each peer connected to the Diameter Gateway, configure alternative peers by specifying values for the following attributes:
- peerName: Enter the name of the Diameter peer.
- alternatePeerName: Enter the name of the alternative peer for the specified Diameter peer. You can specify two alternative peers for each Diameter peer.
Go to the ECE_home/bin directory.
Start the Elastic Charging Controller:
```
./ecc
```
Do one of the following:
- If the Diameter Gateway instance is not running, start it.
- If the Diameter Gateway instance is running, stop and restart it.

Viewing Active Diameter Peers

To view all the active diameter peers:

Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
Expand the DiameterGateway node.
Expand PeerConnectionsTracker.
Expand Attributes.
Click the peerConnections value.

The diameter peers that are active (which are currently connected to the specific Diameter Gateway instance) are displayed.

Including Loan Sub-Balance in Balance Queries

By default, Diameter Gateway includes information about the main currency balance in balance query responses. You can configure Diameter Gateway to include both the main and loan balance information in balance query responses. To configure it to do so, in the ECE Balance Java API, set the balancequerymode to TURBO. For example:

ORA-Balance-Query-Mode (248,VM,v=3512,I=16) = TURBO_MODE (4)

For more information about balancequerymode, see the documentation for oracle.communication.brm.charging.messages.query in Elastic Charging Engine Java API Reference.

About Handling Requests When Charging Servers Are Unavailable

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.

Cleaning Sy Sessions from the Cache

You can free system resources and improve performance by cleaning stale Sy sessions from the DiameterPersistenceSySession cache. Ongoing Sy sessions can become stale if ECE never receives the session termination request (STR) or if the session fails but the session entry remains in the cache.

When this functionality is enabled, ECE automatically removes stale Sy sessions each time it receives a request from a customer to initiate an SLR. During this process, ECE searches for inactive Sy sessions associated with the same customer and deletes the sessions from the cache.

To clean stale Sy Sessions from the DiameterPersistenceSySession cache:

For on-premises systems:
- To change the value with a Diameter Gateway restart:
  1. In your charging-settings.xml file, set the enableSySessionCleanup element to true.
  2. Restart the Diameter Gateway for the changes to take effect.
- To change the value without restarting the Diameter Gateway:
  1. Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
  2. Expand the ECE Configuration node.
  3. Expand charging.server.
  4. Expand Attributes.
  5. Set the enableSySessionCleanup attribute to true.
For cloud native systems:
1. In your override-values.yaml file for oc-cn-ece-helm-chart, set the charging.server.enableSySessionCleanup key to true.
2. Run the helm upgrade command or run a chargingConfigurationReloader job. See "Reloading ECE Application Configuration Changes" in BRM Cloud Native System Administrator’s Guide for more information.

Note:

When the application configuration, subscriptionIdOnStrEnabled, is set to TRUE, the Diameter Gateway relies on the PCF for sending subscription IDs and the Sy session cache will not be used. ECE will not perform any look-up to the cache or prime it. The previous enableSyCleanup attribute should also be set to FALSE.

When the subscriptionIdOnStrEnabled configuration is set to FALSE, the default behavior of the system is enabled, and the Diameter Sy session cache is used. The Diameter Gateway will not rely on the PCF to send subscription IDs for STRs.