# System Administrator’s Guide

# Managing and Configuring Credit Control Interceptors and SLAs

The following section describes how to manage and configure the Credit Control Interceptors in Oracle Communications Services Gatekeeper.

- Introduction

- Application-Initiated Requests
- Network-Triggered Requests
- Credit Control Interception Points

- Writing Credit Control SLAs

- Defining Static and Dynamic Parameter Mappings
- Correlating Reservation and Commit Triggers in Asynchronous Credit Control Checks
- Example Credit Control SLA

- Configuration, Management and Provisioning

- Deployment of CreditControlInterceptor
- Configuration of CreditControlInterceptor
- Management of CreditControlInterceptor
- Reference: Attributes and Operations for CreditControlInterceptor

## Introduction

The Credit Control Interceptors performs credit checks towards a Diameter server using the Diameter Ro interface. This allows for easy integration with charging systems that support Diameter Ro on-line charging. Oracle Communications Billing and Revenue Management, can be used out-of-the-box with Oracle Communications Services Gatekeeper.

Traffic flowing through any Communication Service is intercepted and the data in the request, together 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.

### 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 cancelled.

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 of time, the reservation is cancelled.

### 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 cancelled.

Only synchronous reservations are supported.

### Credit Control Interception Points

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

It is possible to map a parameter in the request to be passed in the Diameter request, or to define a static value for the following AVPs:

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

See for information about how CDRs are mapped to Diameter attribute-value pairs (AVPs).

## Writing Credit Control SLAs

Credit Control SLAs defines which methods that shall be subject to credit control, how the credit control shall be performed, and which data to provide to the Diameter server.

Table 9-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 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 section Managing and Configuring the Plug-in Manager in Oracle Communications Services Gatekeeper Administration Guide 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. 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.
<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. 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.
<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. 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. 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. 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.
<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. 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.
<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. 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.
<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 section Managing and Configuring the Plug-in Manager in Oracle Communications Services Gatekeeper Administration Guide 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.
<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. 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.
Note: | The parameter to use is any of the parameters in the method of the reservation request as defined in the tag <CCInterception>. 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. 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 tag <CCInterception>. 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 9-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 section Managing and Configuring the Plug-in Manager in Oracle Communications Services Gatekeeper Administration Guide 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.

Example of a static parameter mapping:

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

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 tag <CCInterception>.

For asynchronous credit control checks, the ID, or correlator, to use to tie together the reservation request and the commit request is defined. This is done in the same manner as parameter mappings are defined, see Defining Static and Dynamic Parameter Mappings. 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

Listing 9-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 send a getLocation request. The reservation is committed when the request has successfully returned from the network node.

Listing 9-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>

## Configuration, Management and Provisioning

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.

For more information about service interceptors, see chapter Service Interceptors in Oracle Communications Services Gatekeeper Platform Development Studio - Developer’s Guide.

The interceptors are configured and managed using an MBean.

The Credit Control SLAs are provisioned using the Service Provider Group and Application Group SLA MBeans, see chapter Managing SLAs in Oracle Communications Services Gatekeeper Managing Accounts and SLAs.

### Properties for Credit Control Service Interceptors

Property | Description
--- | ---
Managed object in Administration Console | <domain name>OCSG<server name>ContainerServicesCreditControlInterceptor
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 the Credit Control interceptors are not deployed.

Deploy the EAR file that contains the interceptors using WebLogic Server tools, see Oracle WebLogic Server Deploying Applications to WebLogic Server at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/deployment/ for a description of the different deployment options.

The EAR file is located in `$OCSG_HOME/applications.`

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

### Configuration of CreditControlInterceptor

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

1. Specify:

- Attribute: PeerRetryDelay
- Attribute: DestinationHost
- Attribute: DestinationPort
- Attribute: DestinationRealm
- Attribute: OriginHost
- Attribute: OriginPort
- Attribute: MoReservationInterceptorIndex
- Attribute: MtReservationInterceptorIndex
- Attribute: CommitInterceptorIndex
- Attribute: PeerRetryDelay
- Attribute: RequestTimeout
- Attribute: WatchdogTimeout
- Attribute: OriginHost

2. Use Operation: connect to connect to the Diameter server.

### Management of 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:

- Operation: connect
- Operation: disconnect

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

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

### Provision Credit Control SLAs

Credit Control SLAs can be enforced on application group and service provider group level.

The SLAs are provisioned as custom SLAs, see section Managing SLAs in Managing Accounts and SLAs.

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 EAR that contains the Credit Control interceptors, see Deployment of CreditControlInterceptor. 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`

### Reference: Attributes and Operations for CreditControlInterceptor

Managed object: Container ServicesCreditControlInterceptor

MBean: com.bea.wlcp.wlng.interceptor.management.DiameterMBean

Below is a list of attributes and operations for configuration and maintenance.

- Attribute: Connected (r)
- Attribute: CommitInterceptorIndex
- Attribute: DestinationHost
- Attribute: DestinationPort
- Attribute: DestinationRealm
- Attribute: OriginHost
- Attribute: OriginPort
- Attribute: PeerRetryDelay
- Attribute: RequestTimeout
- Attribute: WatchdogTimeout
- Operation: connect
- Operation: disconnect

#### Attribute: Connected (r)

Read-only.

Scope: Server

Format: Boolean

Unit: n/a

Displays the status of the connection to the Diameter server.

Displays:

- `true`, if connected.
- `false`, if not connected.

#### Attribute: CommitInterceptorIndex

Scope: Cluster

Format: Integer

Unit: n/a

Specifies where in the Service Interceptor chain to register the Credit Control interceptor for committing asynchronous Credit Control Checks.

#### Attribute: DestinationHost

Scope: Cluster

Format: String

Unit: n/a

Specifies the Destination-Host AVP in the Diameter request.

Can be specified either as an IP-address or a host name.

#### Attribute: DestinationPort

Scope: Cluster

Format: int

Unit: n/a

Specifies the port on the Diameter server to connect to.

#### Attribute: DestinationRealm

Scope: Cluster

Format: String

Unit: n/a

Specifies the Destination-Realm AVP in the Diameter request.

#### Attribute: OriginHost

Scope: Server

Format: String

Unit: n/a

Specifies the Origin-Host AVP in the Diameter request.

Can be specified either as an IP-address or a host name.

Optional.

#### Attribute: OriginPort

Scope: Server

Format: int

Unit: n/a

Specifies the local originator port to be used for the connection to the Diameter server.

If specified as 0 (zero), a random local port is used.

Random port is a requirement in order to support hitless upgrades of the interceptor.

#### Attribute: MoReservationInterceptorIndex

Scope: Cluster

Format: int

Unit: n/a

Specifies where in the Service Interceptor chain to register the Credit Control interceptor for network-triggered requests.

#### Attribute: MtReservationInterceptorIndex

Scope: Cluster

Format: int

Unit: n/a

Specifies where in the Service Interceptor chain to register the Credit Control interceptor for application-initiated requests.

#### Attribute: PeerRetryDelay

Scope: Cluster

Format: int

Unit: seconds

Specifies the time to wait before attempting to reconnect to the Diameter server if the connection is lost.

#### Attribute: RequestTimeout

Scope: Cluster

Format: int

Unit: milliseconds

Specifies the maximum time to wait for a response to a request to the Diameter server.

#### Attribute: WatchdogTimeout

Scope: Cluster

Format: int

Unit: seconds

Specifies the watchdog timeout Tw.

This setting corresponds to the timer Tw, see RFC 3539 at http://www.ietf.org/rfc/rfc3539.txt.

It specifies the time to wait before attempting to reconnect to the Diameter server in the case of a lost connection.

#### Operation: connect

Scope: Cluster

Connects to the Diameter server.

Once connected, the interceptor will try to reconnect to the Diameter server if the server is restarted or the interceptor is redeployed.

Signature:

    connect()

Table 9-2 connect
connect
Parameter | Description
--- | ---
- | -

#### Operation: disconnect

Scope: Cluster

Disconnects from the Diameter server.

Once disconnected, the interceptor will not try to reconnect to the DAMETER server if the server is restarted or the interceptor is redeployed.

Signature:

    disconnect()

Table 9-3 disconnect
disconnect
Parameter | Description
--- | ---
- | -