24 Implementing Diameter Ro Online Charging

This chapter describes how to manage and configure the Oracle Communications Services Gatekeeper Credit Control Interceptors to work with Diameter online (Ro) credit checks.

Understanding Credit Control Interceptors

The Credit Control Interceptors perform credit checks toward a Diameter server using the Diameter Ro interface. This allows for easy integration with charging systems that support Diameter Ro online charging. Oracle Communications Elastic Charging Engine or Oracle Communications Billing and Revenue Management, can be used out-of-the-box with Services Gatekeeper.

Traffic flowing through any Communication Service is intercepted and the data in the request, with other configuration data, is passed on to a Diameter server for credit control verification. Both application-initiated and network-triggered requests are intercepted, there is one interceptor for each direction.

The credit control check is performed either synchronous or asynchronous.

Using Application-Initiated Requests

In the synchronous case, money is reserved before the request is passed on to the telecom network node. When the request has been successfully handed off and the thread of execution is returning, the reservation is committed. In case the requests fails, the reservation is canceled.

In the asynchronous case, money is reserved before the request is passed on to the telecom network node. When a correlated request arrives to the interceptors, the reservation is committed. In case the correlated request does not arrive within a set period, the reservation is canceled.

Using Network-Triggered Requests

Money is reserved before the request is passed on to the application. When the request has been successfully handed off and the thread of execution is returning, the reservation is committed. In case the requests fails, the reservation is canceled.

Only synchronous reservations are supported.

Using Credit Control Interception Points

Only requests that are explicitly defined to be subject to credit control checks are passed on to the Diameter server.

You can map a parameter in the request to be passed in the Diameter request. Or define a static value for the following attribute value pairs:

  • User-Name

  • OCSG-Charge-Description

  • Service-Context-Id

  • Unit-Value.Exponent and Unit-Value.Value-Digits

  • Currency-Code

The mapping is expressed in XML and provisioned as a service level agreement on service provider group or application group level.

Writing Credit Control SLAs

Credit Control SLAs define which methods are subject to credit control, how the credit control is performed, and which data to provide to the Diameter server. Table 24-1 describes the structure and content of a credit control SLA.

Table 24-1 Structure and contents of a credit control SLA

Tag Description

<CCInterceptions>

Main tag.

Defines a set of interception points for credit controls.

Contains:

<CCInterception>, one (1) or more

<CCInterception>

Defines how and when to trigger a credit control reservation. Used both in asynchronous and synchronous credit control checks.

This element has the following attributes:

  • InterfaceName, which defines the Service Gatekeeper interface that the method defined in the attribute methodName belongs to.

  • methodName, which defines the name of the method that the credit control check applies to.

See "Configuring and Managing Communication Service Traffic" for information on how to get a list of interface names and methods.

For example, the interface name for Parlay X 2.1 Short Messaging and RESTful Short Messaging send SMS is com.bea.wlcp.wlng.px21.plugin.SendSmsPlugin and the method that sends the SMS is sendSms.

Contains:

<SubscriptionId>, exactly one (1).

<OCSGChargeDescription>, zero (0) or one (1).

<ServiceContextId>, zero (0) or one (1).

<Amount>, zero (0) or one (1).

<Currency>, zero (0) or one (1).

<AsynchronousCommit>, zero (0) or one (1).

<SubscriptionId>

Parent tag: <CCInterception>.

Defines how the Diameter AVP User-Name shall be populated.

The alternatives are to dynamically fetch the value from the request that is being subject to credit control or to pass in a configurable value.

This element has the following attributes:

  • type, that defines if the value of the AVP shall be fetched dynamically or statically. Use the keyword Dynamic to fetch the value from the request. Use the keyword Static to define a static value.

  • value, that defines what to send in the AVP. If the attribute type is set to Dynamic, use the fully qualified name of the parameter to use. If the attribute type is set to Static, enter the string to use in the AVP.

See "Defining Static and Dynamic Parameter Mappings"for more information.

<OCSGChargeDescription>

Parent tag: <CCInterception>.

Defines how the Diameter AVP OCSG-Charge-Description shall be populated.

The alternatives are to either dynamically fetch the value from the request that is being subject to credit control or to pass in a configurable value.

This element has the following attributes:

  • type, that defines if the value of the AVP shall be fetched dynamically or statically. Use the keyword Dynamic to fetch the value from the request. Use the keyword Static to define a static value.

  • value, that defines what to send in the AVP. If the attribute type is set to Dynamic, use the fully qualified name of the parameter to use, If the attribute type is set to Static, enter the string to use in the AVP.

See "Defining Static and Dynamic Parameter Mappings" for more information.

<ServiceContextId >

Parent tag: <CCInterception>.

Defines how the Diameter AVP Service-Context-Id shall be populated.

The alternatives are to either dynamically fetch the value from the request that is being subject to credit control or to pass in a configurable value.

This element has the following attributes:

  • type, that defines if the value of the AVP shall be fetched dynamically or statically. Use the keyword Dynamic to fetch the value from the request. Use the keyword Static to define a static value.

  • value, that defines what to send in the AVP. If the attribute type is set to Dynamic, use the fully qualified name of the parameter to use. If the attribute type is set to Static, enter the string to use in the AVP.

See "Defining Static and Dynamic Parameter Mappings" for more information.

If not present, the value is set to current time, given in milliseconds, from 1970.

<OCSGChargeDescription>

Parent tag: <CCInterception>.

Defines how the Diameter AVP OCSG-Charge-Description shall be populated.

The alternatives are to either dynamically fetch the value from the request that is being subject to credit control or to pass in a configurable value.

This element has the following attributes:

  • type, that defines if the value of the AVP shall be fetched dynamically or statically. Use the keyword Dynamic to fetch the value from the request. Use the keyword Static to defined a static value.

  • value, that defines what to send in the AVP. If the attribute type is set to Dynamic, use the fully qualified name of the parameter to use. If the attribute type is set to Static, enter the string to use in the AVP.

See "Defining Static and Dynamic Parameter Mappings" for more information.

<Amount>

Parent tag: <CCInterception>.

Defines how the Diameter AVPs Unit-Value.Exponent and Unit-Value.Value-Digits shall be populated.

The alternatives are to either dynamically fetch the value from the request that is being subject to credit control or to pass in a configurable value.

This element has the following attributes:

  • type, that defines if the value of the AVP shall be fetched dynamically or statically. Use the keyword Dynamic to fetch the value from the request. Use the keyword Static to defined a static value.

  • value, that defines what to send in the AVP. If the attribute type is set to Dynamic, use the fully qualified name of the parameter to use. If the attribute type is set to Static, enter the string to use in the AVP.

See "Defining Static and Dynamic Parameter Mappings" for more information.

<Currency>

Parent tag: <CCInterception>.

Defines how the Diameter AVP Currency-Code shall be populated.

The alternatives are to dynamically fetch the value from the request that is being subject to credit control or to pass in a configurable value.

This element has the following attributes:

  • type, that defines if the value of the AVP shall be fetched dynamically or statically. Use the keyword Dynamic to fetch the value from the request. Use the keyword Static to defined a static value.

  • value, that defines what to send in the AVP. If the attribute type is set to Dynamic, use the fully qualified name of the parameter to use. If the attribute type is set to Static, enter the string to use in the AVP.

See "Defining Static and Dynamic Parameter Mappings" for more information.

<AsynchronousCommit>

Parent tag: <CCInterception>

Defines how and when to trigger charging of a previously reserved amount and which data to use. If present, the charging is asynchronous. If not present, the charging is synchronous.

Has the following attributes:

  • InterfaceName, which defines the Service Gatekeeper interface that the method defined in the attribute methodName belongs to.

  • methodName, which defines the name of the method that the credit control check applies to.

See "Configuring and Managing Communication Service Traffic" for information on how to get a list of interface names and methods.

For example, the interface name for Parlay X 2.1 Short Messaging and RESTful Short Messaging call-back interface is com.bea.wlcp.wlng.px21.callback.SmsNotificationCallback and the method that contains a delivery notification is notifySmsReception.

Contains:

  • <ReservationCorrelator>, zero (0) or one (1).

  • <CommitCorrelator>, exactly one (1).

See "Correlating Reservation and Commit Triggers in Asynchronous Credit Control Checks" for more information.

<ReservationCorrelator>

Parent tag: <AsynchronousCommit>

Defines what to use as an ID, or correlator, for the reservation part of an asynchronous credit control check.

The alternatives are to dynamically fetch the value from the request that is being subject to credit control or to pass in a configurable value.

This element has the following attributes:

  • type, that defines if the value of the correlator shall be fetched dynamically or statically. Use the keyword Dynamic to fetch the value from the request. Use the keyword Static to define a static value.

  • value, that defines what to use as a correlator. If the attribute type is set to Dynamic, use the fully qualified name of the parameter to use. If the attribute type is set to Static, enter the string to use.

See "Defining Static and Dynamic Parameter Mappings" for more information.

Note: The parameter to use is any of the parameters in the method of the reservation request as defined in the <CCInterception> tag. Normally, the correlator used to correlate asynchronous request-response pairs is used.

<CommitCorrelator>

Parent tag: <AsynchronousCommit>

Defines what to use as an ID, or correlator, for the commit part of an asynchronous credit control check.

The alternatives are to dynamically fetch the value from the request that is being subject to credit control or to pass in a configurable value.

This element has the following attributes:

  • type, that defines if the value of the correlator shall be fetched dynamically or statically. Use the keyword Dynamic to fetch the value from the request. Use the keyword Static to define a static value.

  • value, that defines what to use as a correlator. If the attribute type is set to Dynamic, use the fully qualified name of the parameter to use. If the attribute type is set to Static, enter the string to use.

Note: The parameter to use is the parameter of the reservation request as defined in the <CCInterception> tag. Normally, the correlator used to correlate asynchronous request-response pairs is used.


Defining Static and Dynamic Parameter Mappings

The Credit Control Interceptors can map parameters in two ways:

  • Static

  • Dynamic

Mappings are defined using two components: type and value. The mappings are expressed as attributes to a subset of the Credit Control SLA elements, see Table 24-1.

When type is set to Static, the mapping is static, which means that the attribute value is set to, and treated as an arbitrary string

When type is set to Dynamic, the mapping is dynamic, which means that the attribute value is set to the content of a parameter in the request that is subject to credit control checks. Which parameter to chose is configurable by referring to the Java representation of the parameter defined in the WSDL. See "Configuring and Managing Communication Service Traffic" for information on how to get a list of valid parameter names. The representation is arg0.<name of parameter as defined in WSDL>.

Depending on which element the parameter mapping exists, the value is passed on to a DIAMTER AVP or used as a key for reservations.

Here is an example of a static parameter mapping:

<OCSGChargeDescription type="static" value ="Static value for reservation."/>

Here is an example of a dynamic parameter mapping:

<Amount type="dynamic" value ="arg0.charging.amount"/>

Correlating Reservation and Commit Triggers in Asynchronous Credit Control Checks

In both synchronous and asynchronous credit control checks, the request that triggers a reservation is defined. This is done using the <CCInterception> tag.

For asynchronous credit control checks, the ID, or correlator, ties together the reservation request and the commit request. This is done in the same manner as parameter mappings are defined; see "Defining Static and Dynamic Parameter Mappings" for more information. There is one parameter mapping for the reservation, and one for the commit.

In most use cases the correlators are fetched dynamically from the requests. The reservation correlator is fetched from a parameter in the method in the interface defined for the trigger. The commit correlator is fetched from the request that commits the reservation. Since the commit correlator is a parameter in the method that triggers the commit the interface, method, and parameter must be defined explicitly since it is different from the method that triggers the reservations.

For each request, the two correlators are compared and in the case of a match, the reservation is committed. Reservations time-out after a certain time period and the reservation is released. The time-out is defined in the store configuration for the interceptor.

Example Credit Control SLA

Example 24-1 shows a Credit Control SLA with two different credit control checks.

The firsts check is done asynchronously. The reservation is done when the application sends a sendSms request. In this case, the charging description is a static String, while all other are picked up dynamically from the request. The reservation is committed when a delivery notification is sent to the application using the method notifySmsReception and the parameter correlator in the sendSms request is identical with the parameter correlator in the notifySmsReception request.

The second check is done synchronously. The reservation is done when the application sends a getLocation request. The reservation is committed when the request has successfully returned from the network node.

Example 24-1 Example Credit Control SLA

<?xml version="1.0" encoding="UTF-8"?>
<CCInterceptions>
<CCInterception
interfaceName="com.bea.wlcp.wlng.px21.plugin.SendSmsPlugin"
methodName="sendSms">
<SubscriptionId type="dynamic" value ="arg0.senderName"/>
<OCSGChargeDescription 
type="static" value ="Static description for reservation."/>
<ServiceContextId type="dynamic" value ="arg0.charging.code"/>
<Amount type="dynamic" value ="arg0.charging.amount"/>
<Currency type="dynamic" value ="arg0.charging.currency"/>
<AsynchronousCommit
interfaceName="com.bea.wlcp.wlng.px21.callback.SmsNotificationCallback"
methodName="notifySmsReception">
<ReservationCorrelator 
type="dynamic" value="arg0.receiptRequest.correlator"/>
<CommitCorrelator type="dynamic" value="arg1.correlator"/>
</AsynchronousCommit>
</CCInterception>
<CCInterception
interfaceName="com.bea.wlcp.wlng.px21.plugin.TerminalLocationPlugin"
methodName="getLocation">
<SubscriptionId type="dynamic" value="arg0.address"/>
<OCSGChargeDescription 
type="static" value ="Static dummy description."/>
<ServiceContextId type="static" value="Static dummy code."/>
<Amount type="static" value="2"/>
<Currency type="dynamic" value="USD"/>
</CCInterception>
</CCInterceptions>

Configuring, Managing, and Provisioning Credit Control Interceptors

The Credit Control interceptors are deployed as regular EARs, but they are not registered with the InterceptorManager until a connection is established with the Diameter server. They are de-registered when the connection to the server is connection is closed.

The interceptors are configured and managed using an MBean. For more information about service interceptors, see the discussion on service intercepters in Services Gatekeeper Extension Developer's Guide.

The Credit Control SLAs are provisioned using the Service Provider Group and Application Group SLA MBeans. See the discussion on Managing SLAs in Services Gatekeeper Portal Developer's Guide.

Properties for Credit Control Service Interceptors

Table 24-2 describes the properties of Credit Control Service Interceptors.

Table 24-2 Credit Control Service Interceptor Properties

Property Description

Managed object in Administration Console

<domain_name> then OCSG then <server name> then ContainerServices then CreditControlInterceptor

MBean

Domain=com.bea.wlcp.wlng

Name=wlng_nt

InstanceName=CreditControlInterceptor

Type=com.bea.wlcp.wlng.cc_interceptor.management.DiameterMBean

Deployment artifacts

cc_interceptor.ear


Deployment of CreditControlInterceptor

By default Credit Control interceptors are not deployed.

Deploy the EAR file that contains the interceptors using WebLogic Server tools. See "Java EE Deployment Implementation" in Oracle WebLogic Server Deploying Applications to Oracle WebLogic Server for a description of the different deployment options.

The EAR file is located in Gatekeeper_Home/applications.

Following is an example on how to the deploy the Credit Control Interceptors:

java weblogic.Deployer -adminurl http://<admin host>:<admin port> -user <admin user> -password <admin password -name ccInterpeptor.ear -deploy 

The interceptors are not connected to the Diameter server after deployment.

Configuring CreditControlInterceptor

To configure the behavior of the CreditControlInterceptor, in the managed object CreditControlInterceptor:

  1. Specify entries for these fields:

    • PeerRetryDelay

    • DestinationHost

    • DestinationPort

    • DestinationRealm

    • OriginHost

    • OriginPort

    • MoReservationInterceptorIndex

    • MtReservationInterceptorIndex

    • CommitInterceptorIndex

    • PeerRetryDelay

    • RequestTimeout

    • WatchdogTimeout

  2. Use the connect method to connect to the Diameter server.

Managing CreditControlInterceptor

The Credit Control Interceptors can be explicitly connected to the Diameter server. It does not connect to the server by default. The interceptors have a connection status that will be preserved after redeployment and server restart.

Use:

  • The connect method

  • The disconnect method

Use the Connected (r) field to check the current connection status.

Use the: connect method after any changes to the configuration attributes. Changes do not take affect until this operation is invoked.

Provisioning Credit Control SLAs

Credit Control SLAs can be enforced at the application group and service provider group level. These SLAs are provisioned as custom SLAs. See the discussion about managing SLAs in the Services Gatekeeper Accounts and SLAs Guide.

Before any Credit Control SLAs can be provisioned, the XSD for the SLA must be loaded, and the SLA type is given when the XSD is loaded.

The XSD is found in an .ear file that contains the Credit Control interceptors. See "Deployment of CreditControlInterceptor" for more information. The XSD is located in

/xsd/ccMapping.xsd

The SLA type to use when loading the Credit Control SLAs XSD is credit_control.

The SLA type to use when provisioning Credit Control SLAs is credit_control.

: