Oracle® Communications Services Gatekeeper System Administrator's Guide Release 5.1 E37531-01 |
|
|
PDF · Mobi · ePub |
This chapter describes how to manage and configure the Credit Control Interceptors in Oracle Communications Services Gatekeeper.
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.
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.
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.
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.
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 describes the structure and content of a credit control SLA.
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:
See "Managing and Configuring the Plug-in Manager" 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:
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. Has the following attributes:
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. Has the following attributes:
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. Has the following attributes:
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.
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. Has the following attributes:
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:
See "Managing and Configuring the Plug-in Manager" 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:
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. Has the following attributes:
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 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:
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. |
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 "Managing and Configuring the Plug-in Manager" 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"/>
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" 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 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 sends a getLocation request. The reservation is committed when the request has successfully returned from the network node.
Example 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>
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 "Service Intercepters" in the 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 “Managing SLAs” in the Oracle Communications Services Gatekeeper Accounts and SLAs Guide.
Table 9-2 describes the properties of Credit Control Service Interceptors.
Property | Description |
---|---|
Managed object in Administration Console |
<domain name>->OCSG-><server name>->ContainerServices->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 |
By default the Credit Control interceptors are not deployed.
Deploy the EAR file that contains the interceptors using WebLogic Server tools. For a description of the different deployment options, see "Deploying, Undeploying, and Redeploying Java EE Applications" in Oracle® Fusion Middleware Deploying Applications to Oracle WebLogic Server at:
http://download.oracle.com/docs/cd/E15523_01/web.1111/e13702/title.htm
The EAR file is located in $OCSG_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.
To configure the behavior of the CreditControlInterceptor, in the managed object CreditControlInterceptor:
Specify:
Use Operation: connect to connect to the Diameter server.
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:
Use Attribute: Connected (r) to check the current connection status.
Use Operation: connect after any changes to the configuration attributes. Changes do not take affect until this operation is invoked.
Credit Control SLAs can be enforced on application group and service provider group level.
The SLAs are provisioned as custom SLAs, see “Managing SLAs” in the Oracle Communications 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 EAR 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
Managed object: Container Services−>CreditControlInterceptor
MBean: com.bea.wlcp.wlng.interceptor.management.DiameterMBean
Following is a list of attributes and operations for configuration and maintenance.
Read-only.
Scope: Server
Format: Boolean
Unit: Not applicable
Displays the status of the connection to the Diameter server.
Displays:
true
, if connected.
false
, if not connected.
Scope: Cluster
Format: Integer
Unit: Not applicable
Specifies where in the Service Interceptor chain to register the Credit Control interceptor for committing asynchronous Credit Control Checks.
Scope: Cluster
Format: String
Unit: Not applicable
Specifies the Destination-Host AVP in the Diameter request.
Can be specified either as an IP-address or a host name.
Scope: Cluster
Format: int
Unit: Not applicable
Specifies the port on the Diameter server to connect to.
Scope: Cluster
Format: String
Unit: Not applicable
Specifies the Destination-Realm AVP in the Diameter request.
Scope: Server
Format: String
Unit: Not applicable
Specifies the Origin-Host AVP in the Diameter request.
Can be specified either as an IP-address or a host name.
Optional.
Scope: Server
Format: int
Unit: Not applicable
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.
Scope: Cluster
Format: int
Unit: Not applicable
Specifies where in the Service Interceptor chain to register the Credit Control interceptor for network-triggered requests.
Scope: Cluster
Format: int
Unit: Not applicable
Specifies where in the Service Interceptor chain to register the Credit Control interceptor for application-initiated requests.
Scope: Cluster
Format: int
Unit: seconds
Specifies the time to wait before attempting to reconnect to the Diameter server if the connection is lost.
Scope: Cluster
Format: int
Unit: milliseconds
Specifies the maximum time to wait for a response to a request to the Diameter server.
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.
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()
Scope: Cluster
Disconnects from the Diameter server.
Once disconnected, the interceptor will not try to reconnect to the DIAMETER server if the server is restarted or the interceptor is redeployed.
Signature:
disconnect()