| Oracle® Communications Services Gatekeeper Communication Service Guide Release 5.1 E37526-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Services Gatekeeper Communication Service Guide Release 5.1 E37526-01 |
|
|
PDF · Mobi · ePub |
This chapter describes the Parlay X 3.0 Payment/Diameter communication service in detail.
The Parlay X 3.0 Payment/Diameter communication service exposes the Parlay X 3.0 Payment set of application interfaces.
The communication service acts as a credit control client to a credit control server using the Diameter protocol.
For the exact version of the standards that the communication service supports for the application-facing interfaces and the network protocols, see the discussion on standards and specifications in Oracle Communications Service Broker Concepts Guide.
Using a Payment communication service, an application can:
Charge and refund accounts directly.
Operate on reservations, which includes:
Make reservations.
Charge reservations.
Release reservations.
Charge multiple accounts concurrently.
This communication service uses templates that you use to change the list of Diameter AVPs that Services Gatekeeper sends to a Diameter server. See "Changing the List of Diameter AVPs for Your Implementation" for details on creating templates.
All charging is done on accounts. Accounts can be charged using units of charge (specified as a given currency or a charging code) or by volume of (specified by time or data). See "Amount Charging" and "Volume Based Charging" for details.
A reservation expires after a given time. An expiration mechanism provided by the Storage Service is used. If the store entry expires, the reservation is cancelled.
Some Diameter servers, for example Oracle Billing and Revenue Management, mandate that a refund operation be correlated with a previous charge operation. The Payment interface does not provide any correlation between charge operations and refund operations. The session-id tunneled parameter has been added in order to correlate these requests. When an application calls chargeAmount, the tunneled parameter session-id is returned in the SOAP header. An application should use this session-id in subsequent refundAmount requests to correlate the two requests. If the application does not provided the tunneled parameter, it is the responsibility of the Diameter server to either accept or deny the request. If the request is denied, the application receives a ServiceException. See "session-id" for more information.
Volume-based charging is similar to amount charging. However volume base charging maps to these Diameter AVPs instead of CC-Money:
CC-Time (in seconds)
CC-Total-Octets (in bytes)
CC-Input-Octets (in bytes)
CC-Output-Octets (in bytes)
CC-Service-Specific-Units
These AVPs all accept either bytes or seconds (as integers) as input. If your AVPs use something different, you also need to convert the data.
The rating parameters to use are unit, contract, service, or operation and they all map to the Service-Parameter-Info AVP.
Diameter servers frequently require a specific list of AVPs, or custom AVPs to process correctly, so you will probably have to modify the list of AVPs that Services Gatekeeper sends. You do this using a template file. See "Changing the List of Diameter AVPs for Your Implementation" for instructions.
Credit-control clients may need to request the price (or an estimate) of the service event in advance, and these clients should be able to handle situations where this amount may not be known.
Clients requesting cost information must:
Set the CC-Request-Type AVP to EVENT_REQUEST
Include a Requested-Action AVP set to PRICE_ENQUIRY, and
Include the requested service event information in the Service-Identifier AVP in the CCR message
If an application makes a request to interact directly with an account, Services Gatekeeper sends the request to the network node capable of handling the request. The request does not return until the targeted account has been updated.
There are no notifications or other network-triggered requests for this communications service.
The communication service supports the Granted-Service-Unit Diameter AVP that Services Gatekeeper sends to the network.
This support enables the plug-in to validate whether the number of units granted is equal to the number of reserved units requested.
After the Credit Control Answer (CCA) has been received, the plug-in checks the CCA for the Granted-Service-Unit AVP. If this AVP exists, the plug-in compares the number of granted units to the number of reserved units that were requested in the RSU of the Credit Control Request (CCR).
If the Granted-Service-Unit AVP does not exist, the plug-in assumes that the full reservation was granted.
If the Granted-Service-Unit value is less than the number of requested units, the plug-in performs the following actions:
Raises the RESERVATION_NOT_GRANTED_ERROR exception (error id=”000005”) to notify the client that the reservation failed.
Releases the reservation by sending a termination Credit Control Request (CCR). This CCR may or may not contain the Used-Service-Unit (USU) field, depending on whether the client has called chargeReservation since the last reservation.
For information about the SOAP-based interface for the Parlay X 3.0 Payment communication service, see the discussion of Parlay X 3.0 Interfaces in Oracle Communications Services Gatekeeper Application Developer's Guide.
For information about the RESTful Call Notification interface, see the discussion of Payment in Oracle Communications Services Gatekeeper RESTful Application Developer's Guide.
The RESTful Service Call Notification interfaces provide RESTful access to the same functionality as the SOAP-based interfaces. The internal representations are identical, and for the purposes of creating SLAs and reading CDRs, and so on., they are the same.
Diameter servers vary quite a bit in their messaging requirements. You probably need to change the list of AVPs that Services Gatekeeper sends to a Diameter server to make it acceptable to that server.
There are three ways to add AVPs to your implementation:
By adding new AVP definitions to AVP template files that you create, than loading the template files into Services Gatekeeper. This is the best method for major changes to your AVP list, and is probably most appropriate for the changes you make for the initial configuration of Services Gatekeeper. You must stop and restart Gatekeeper to make the changes take effect. See "About the AVP Template Files" for information on creating template files, and "Adding New AVPs for Diameter Payment in Template Files" for details on loading new AVPs into Services Gatekeeper.
By adding new AVP definitions to the default AVP template file. You add AVPs to the default template file and restart Services Gatekeeper. This is probably the best method for initial testing of Services Gatekeeper. You only alter one file, but you still need to restart Services Gatekeeper. Follow the instructions in "Adding New AVPs for Diameter Payment in Template Files" but instead of creating template files just make changes to defaultavptemplate.xml file provided.
By using JMX operations to add new AVP definitions during runtime. This allows you to make changes to existing AVP template files without interrupting traffic or having to stop and restart Services Gatekeeper. This is most appropriate for changes to a running implementation. See "Adding Diameter AVPs to a Template File During Runtime" for details.
Changes to template files also require XSD changes.
You can create separate templates for each of these operations:
com.bea.wlcp.wlng.px30.plugin.VolumeChargingPlugin. chargeVolume
com.bea.wlcp.wlng.px30.plugin.VolumeChargingPlugin. chargeSplitVolume
com.bea.wlcp.wlng.px30.plugin.VolumeChargingPlugin. getAmount
com.bea.wlcp.wlng.px30.plugin.VolumeChargingPlugin. refundVolume
com.bea.wlcp.wlng.px30.plugin.ReserveVolumeChargingPlugin. getAmount
com.bea.wlcp.wlng.px30.plugin.ReserveVolumeChargingPlugin. reserveVolume
com.bea.wlcp.wlng.px30.plugin.ReserveVolumeChargingPlugin. reserveAdditionalVolume
com.bea.wlcp.wlng.px30.plugin.ReserveVolumeChargingPlugin. releaseReservation
Each template can have three separate variations, one each for each of the time or octet data format, and a third if you use a custom data format. For example, the chargeVolume operation can have these templates:
com.bea.wlcp.wlng.px30.plugin.VolumeChargingPlugin.chargeVolumeTime
com.bea.wlcp.wlng.px30.plugin.VolumeChargingPlugin.chargeVolumeTime
com.bea.wlcp.wlng.px30.plugin.VolumeChargingPlugin.chargeVolumeCustom
If your implementation requires multiple template files, follow the steps in this section to add them.
You must know the name, code number, and data type of each AVP to add before starting this procedure.
Tip:
For testing or for minor AVP additions you can simply edit and use the example template file (defaultavptemplate.xml) instead of creating new template files.To add new AVPs to your Services Gatekeeper implementation:
Navigate to OCSB_home\ocsg_5.1\applications.
Unpackage the Plugin_px30_payment_diameter.ear file.
Unpackage the Plugin_px30_payment_diameter.jar file.
Navigate to the /xml directory you just unpacked.
Add an avpAttributeDefinitions element for each new AVP to the avp-attribute.xml file.
Make a copy of the defaultavptemplate.xml template file to work on. See "About the AVP Template Files" for details on what to name template files.
Create a new avpTemplate element in your new template file for each new AVP.
Repeat step 6 and 7 for each template file you are creating.
Navigate to the xsd directory (../xsd).
Add an element for each new AVP to the diameterAvp.xsd file.
An example XSD file paymentConfig.xsd is provided.
Update the Plugin_px30_payment_diameter.jar file to save your changes.
Update the wlng_nt_payment_px30.ear file to make your changes take effect.
Restart Services Gatekeeper.
The instructions in this section allow you to add AVPs to existing template files. Before you follow the instructions in this section you must decide on a template file to change. See "About the AVP Template Files" for details on the template files.
To add AVPs without interrupting traffic or having to restart Services Gatekeeper using JMX operations:
Navigate to OCSB_home\ocsg_5.1\applications.
Unpackage the Plugin_px30_payment_diameter.ear file.
Unpackage the Plugin_px30_payment_diameter.jar file.
Navigate to the /xml directory you just unpacked.
Add your AVP changes to the defaultavpTemplate.xml file.
Open Service Gatekeeper in the Platform Test Environment (PTE) or anther MBean browser.
Navigate to navigate to wlng, then AccountService then ServiceLevelAgreementMBean, then to the setupCustomSlaXSDDefinition operation.
In the SlaType: field enter payment_diameter_avp.
In the FileContent: field select the Load the contents of a file icon.
Select the xml/paymentConfig.xsd file to add.
Click Record to make your changes take effect.
Navigate to wlng, AccountService, then ServiceLevelAgreementMBean.
Select one of these operations:
loadGlobalSlaByType
loadServiceProviderGroupSlaByType
loadApplicationGroupSlaByType
In the SlaType: field enter payment_diameter_avp.
In the FileContent: field, enter defaultavptemplate.xml.
Click Record to make your changes take effect.
The Parlay X 3.0 Payment/Diameter communication service generates Event Data Records (EDRs), Charging Data Records (CDRs), alarms, and statistics to assist system administrators and developers in monitoring the service.
For general information, see Appendix A, "Events, Alarms, and Charging."
Table 18-1 lists Event Data Record (EDR) IDs created by the Payment/Diameter communication service.
Table 18-1 Event Types Generated by Parlay X 3.0 Payment/Diameter
| EDR ID | Interface | Method Called |
|---|---|---|
|
15001 |
com.bea.wlcp.wlng.plugin.payment.diameter.north.AmountChargingPluginNorth |
chargeAmount |
|
15002 |
com.bea.wlcp.wlng.plugin.payment.diameter.north.AmountChargingPluginNorth |
refundAmount |
|
15003 |
com.bea.wlcp.wlng.plugin.payment.diameter.north.AmountChargingPluginNorth |
chargeSplitAmount |
|
15004 |
com.bea.wlcp.wlng.plugin.payment.diameter.north.ReserveAmountChargingPluginNorth |
reserveAmount |
|
15005 |
com.bea.wlcp.wlng.plugin.payment.diameter.north.ReserveAmountChargingPluginNorth |
reserveAdditionalAmount |
|
15006 |
com.bea.wlcp.wlng.plugin.payment.diameter.north.ReserveAmountChargingPluginNorth |
chargeReservation |
|
15007 |
com.bea.wlcp.wlng.plugin.payment.diameter.north.ReserveAmountChargingPluginNorth |
releaseReservation |
|
15013 |
oracle.ocsg.plugin.payment.north.VolumeChargingPluginNorth |
chargeVolume |
|
15014 |
oracle.ocsg.plugin.payment.north.VolumeChargingPluginNorth |
chargeSplitVolume |
|
15015 |
oracle.ocsg.plugin.payment.north.VolumeChargingPluginNorth |
getAmount |
|
15016 |
oracle.ocsg.plugin.payment.north.VolumeChargingPluginNorth |
refundVolume |
|
15017 |
oracle.ocsg.plugin.payment.north.ReserveVolumeChargingPluginNorth |
getAmount |
|
15018 |
oracle.ocsg.plugin.payment.north.ReserveVolumeChargingPluginNorth |
reserveVolume |
|
15019 |
oracle.ocsg.plugin.payment.north.ReserveVolumeChargingPluginNorth |
reserveAdditionalVolume |
|
15020 |
oracle.ocsg.plugin.payment.north.ReserveVolumeChargingPluginNorth |
chargeReservation |
|
15021 |
oracle.ocsg.plugin.payment.north.ReserveVolumeChargingPluginNorth |
releaseReservation |
Table 18-2 maps methods invoked from either the application or the network to the transaction types collected by the Services Gatekeeper statistics counter.
Table 18-2 Methods and Transaction Types for Parlay X 3.0 Payment/Diameter
| Method | Interface | Transaction type |
|---|---|---|
|
chargeAmount |
com.bea.wlcp.wlng.px30.plugin.AmountChargingPlugin |
TRANSACTION_TYPE_CHARGING_DIRECT |
|
chargeSplitAmount |
com.bea.wlcp.wlng.px30.plugin.AmountChargingPlugin |
TRANSACTION_TYPE_CHARGING_DIRECT |
|
refundAmount |
com.bea.wlcp.wlng.px30.plugin.AmountChargingPlugin |
TRANSACTION_TYPE_CHARGING_DIRECT |
|
reserveAmount |
com.bea.wlcp.wlng.px30.plugin.ReserveAmountChargingPlugin |
TRANSACTION_TYPE_CHARGING_RESERVED |
|
reserveAdditionalAmount |
com.bea.wlcp.wlng.px30.plugin.ReserveAmountChargingPlugin |
TRANSACTION_TYPE_CHARGING_RESERVED |
|
chargeReservation |
com.bea.wlcp.wlng.px30.plugin.ReserveAmountChargingPlugin |
TRANSACTION_TYPE_CHARGING_RESERVED |
|
chargeVolume |
com.bea.wlcp.wlng.px30.plugin.VolumeChargingPlugin |
TRANSACTION_TYPE_CHARGING_DIRECT |
|
chargeSplitVolume |
com.bea.wlcp.wlng.px30.plugin.VolumeChargingPlugin |
TRANSACTION_TYPE_CHARGING_DIRECT |
|
refundVolume |
com.bea.wlcp.wlng.px30.plugin.VolumeChargingPlugin |
TRANSACTION_TYPE_CHARGING_DIRECT |
|
reserveVolume |
com.bea.wlcp.wlng.px30.plugin.ReserveVolumeChargingPlugin |
TRANSACTION_TYPE_CHARGING_RESERVED_STRING |
|
reserveAdditionalVolume |
com.bea.wlcp.wlng.px30.plugin.ReserveVolumeChargingPlugin |
TRANSACTION_TYPE_CHARGING_RESERVED_STRING |
|
chargeReservation |
com.bea.wlcp.wlng.px30.plugin.ReserveVolumeChargingPlugin |
TRANSACTION_TYPE_CHARGING_RESERVED_STRING |
This section lists the parameters that can be tunneled.
Correlates a refundAmount operation with a chargeAmount operation.
Some billing systems, including Oracle Billing and Revenue Management, allow refund operations only on previously charged amounts. Parlay X does not have the ability to correlate charge and refund operations. This parameter provides that functionality.
The key and the value are available in the return message from a chargeAmount operation. It is the responsibility of the application to provide the key and the value in subsequent refundAmount operations to correlate the two.
If no session-id is provided in the request to the Diameter node, the Diameter node can either accept or deny the request. If the node denies the request, a ServiceException is sent back to the application.
String
This is an example in a SOAP header:
<xparams> <param key=" session-id value="12233187769"/> </xparams>
This section describes the properties and workflow for the Parlay X 3.0 Payment/Diameter plug-in instance.
Table 18-3 lists the technical specifications for the communication service.
Table 18-3 Properties for Parlay X 3.0 Payment/Diameter
| Property | Description |
|---|---|
|
Managed object in Administration Console |
domain_name, then OCSG, then server_name, then Communication Services, then plugin_instance_id |
|
MBean |
Domain=com.bea.wlcp.wlng Name=wlng_nt InstanceName=same as the network protocol instance_id assigned when the plug-in instance is created Type=com.bea.wlcp.wlng.plugin.payment.diameter.management.PaymentMBean |
|
Network protocol plug-in service ID |
Plugin_px30_payment_diameter |
|
Network protocol plug-in instance ID |
The ID is assigned when the plug-in instance is created. See “Managing and Configuring the Plug-in Manager” in System Administrator's Guide. |
|
Supported Address Scheme |
tel |
|
Application-facing interfaces |
com.bea.wlcp.wlng.px30.plugin.AmountChargingPlugin com.bea.wlcp.wlng.px30.plugin.ReserveAmountChargingPlugin |
|
Service type |
Payment |
|
Exposes to the service communication layer a Java representation of: |
Parlay X 3.0 Part 6: Payment |
|
Interfaces with the network nodes using: |
Diameter RFC3588 and RFC 4006 |
|
Deployment artifact NT EAR wlng_nt_payment_px30.ear |
Plugin_px30_payment_diameter.jar and px30_payment_service.jar |
|
Deployment artifact AT EAR: Normal wlng_at_payment_px30.ear |
rest_payment.war and px30_payment.war |
|
Deployment artifact AT EAR: SOAP Only wlng_at_payment_px30_soap.ear |
px30_payment.war |
Following is an outline for configuring the plug-in using the Administration Console or an MBean browser.
Create one or more instances of the plug-in service. See “Managing and Configuring the Plug-in Manager” in Oracle Communications Services Gatekeeper System Administrator's Guide. Use the plug-in service ID as listed in the "Properties for Parlay X 3.0 Payment/Diameter" section.
Add any additional or custom AVPs that your Diameter server requires. See "Changing the List of Diameter AVPs for Your Implementation" for instructions.
Using the Administration Console or an MBean browser, select the MBean for the plug-in instance. The MBean display name is the same as the plug-in instance ID given when the plug-in instance was created.
Configure the behavior of the plug-in instance:
Use "Operation: connect" to connect to the Diameter server.
Set up the routing rules to the plug-in instance. See “Managing and Configuring the Plug-in Manager” in Oracle Communications Services Gatekeeper System Administrator's Guide. Use the plug-in instance ID and address schemes listed in the "Properties for Parlay X 3.0 Payment/Diameter" section.
If required, create and load a node SLA. For details see “Defining Global Node and Service Provider Group Node SLAs” and “Managing SLAs” in the Oracle Communications Services Gatekeeper Accounts and SLAs Guide.
Provision the service provider accounts and application accounts. For information, see Oracle Communications Services Gatekeeper Accounts and SLAs Guide.
The Parlay X 3.0 Payment/Diameter plug-in instance can be explicitly connected to the Diameter server. It does not connect to the server by default. The service has a connection status that will be preserved after service redeployment and server restart.
Use:
Use "Attribute: SplitChargeEnabled" after any changes to the configuration attributes. Changes does not take affect until this operation is invoked.
This section describes the attributes and operations for configuration and maintenance:
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the OneAPI charging channels. Channels are specified as a comma delimited list.
Example:
WAP, WEB, SMS
Scope: Server
Unit: Not applicable
Format: Boolean
Displays the status of the connection to the Diameter server.
Displays:
true, if connected.
false, if not connected.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the Diameter server's Host addresses. Addresses are specified in a comma delimited list.
Example:
host.destination1.com:3588,host.destination2.com:3588
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the Destination-Realm AVP in Diameter requests.
Example:
destination.com
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the Service-Context ID AVP.
The default is oracle.com.
Scope: Server
Unit: Not applicable
Format: String
Specifies the Origin-Host AVP in Diameter requests.
Example:
host.oracle.com
Scope: Server
Unit: Not applicable
Format: Integer
Specifies the local originator port to be used for the connection to the Diameter server.
Example:
7002
Scope: Server
Unit: Not applicable
Format: String
Specifies the Origin-Realm AVP in Diameter requests.
Example:
oracle.com
Scope: Cluster
Unit: Not applicable
Format: Boolean
Specifies whether OneAPI queries are enabled or disabled.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the value of the Service-Context-Id AVP in Diameter requests. Used to override the oracle.com suffix in the ServiceContextId value to work with third-party charging applications. If set to NULL (empty string), the ParlayX request charge.code is used.
Example:
SCAP_V.2.0@xyz.com
Scope: Cluster
Unit: Not applicable
Format: Boolean
Controls whether Volume Split Charging is enabled or disabled.
Scope: Server
Connects to the Diameter server.
Once connected, the plug-in will try to reconnect to the Diameter server if the server is restarted or the plug-in is redeployed.
Signature:
connect()
Scope: Cluster
Disconnects from the Diameter server.
Once disconnected, the plug-in will not try to reconnect to the Diameter server if the server is restarted or the plug-in is redeployed.
Signature:
disconnect()
|
 Copyright © 2011, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
