Oracle® Communications Services Gatekeeper Platform Development Studio Developer's Guide Release 5.1 E37535-01 |
|
|
PDF · Mobi · ePub |
This section describes how to customize Diameter AVPs (Attribute-Value Pairs) in Oracle Communications Services Gatekeeper (Services Gatekeeper) for:
Parlay X 3.0 Payment Diameter communication service
Credit Control Interceptor
CDR Diameter listener
You can customize the Diameter AVPs that Services Gatekeeper sends to the network. You can add or modify the AVPs.
A set of standard AVPs are sent using Diameter, and you can add additional AVPs and modify them using configuration. Applications can also provide custom AVPs as tunnelled parameters, and they can receive returned AVPs using tunneled parameters.
The Parlay X 3.0 Payment/Diameter communication service translates Parlay X requests or requests over the RESTful interfaces to Diameter calls. You can add and modify the Diameter AVPs that are sent in the Diameter request using a custom global SLA or a custom service provider SLA. See Managing Accounts and SLAs Guide, another document in this set. Use the SLA type payment_diameter_avp
when loading the SLA.
The custom SLA has the following structure:
<tns:paymentConfig>
<tns:avpAttributeDefinitions>
<avp:avpAttribute></avp:avpAttribute>
...
</tns:avpAttributeDefinitions>
<tns:avpTemplate>
<avp:avpValue/>
...
</tns:avpTemplate>
</tns:paymentConfig>
The paymentConfig
element contains one instance of avpAttributeDefinitions
and a sequence of avtTemplate
. It has no attributes.
The avpAttribute
element specifies the AVP attribute to use and defines its characteristics. One or more avpAttribute
elements can be defined under avpAttributeDefinitions
. The avpAttribute
element has the following attributes:
code
Required. Defines the AVP attribute code.
vendorId
Required. Defines the Vendor ID for the AVP.
name
Required. Symbolic name to use when referring to the AVP attribute definition in the avpValue
element.
type
Required. Type is String. Defines the data type of the AVP. Possible values are:
INTEGER32
INTEGER64
FLOAT32
FLOAT64
STRING
ADDRESS
GROUPED
BYTES
If the type is GROUPED, the AVP attribute is a grouped attribute and a sequence of avpAttribute
elements can be added as siblings to a avpAttribute
.
flag
default is 64. Use the following values:
FLAG_NONE = 0x0 (0)
FLAG_VENDOR_SPECIFIC = 0x80 (128)
FLAG_MANDATORY =0x40 (64)
FLAG_END_TO_END_ENCRYPTION = 0x20 (32)
You can combine these flags by adding their values together.
The value parts of the AVPs are defined as sequence of avpValue
elements. The avpValue
is a sibling to the avpTemplate
element.
The avpTemplate
element defines the optional paramName
attribute. If a ParamName
is not specified, the template that has the same name as the calling operation is used.
The avpValue
element defines the value of an AVP. It has two attributes:
avpName
Required. Type is String. Points to the avpAttribute
the value corresponds to.
defaultValue
Optional. Type is String. Defines the value of the AVP. When it is a grouped AVP (type
is set to GROUPED) the value must be null, otherwise it must have a value.
Example 14-1 illustrates a custom AVP definition for Payment. It defines three AVP attributes and shows how to set the values for these.
Example 14-1 Custom AVP definition for Payment
<?xml version="1.0" encoding="UTF-8"?> <tns:paymentConfig xmlns:avp="http://ocsg.oracle/diameterAvp/xml" xmlns:tns="http://ocsg.oracle/plugin/payment/diameter/xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <tns:avpAttributeDefinitions> <avp:avpAttribute code="3001" vendorId="111" name="test-avp-1" type="String" flag="0"></avp:avpAttribute> <avp:avpAttribute code="3002" vendorId="111" name="test-avp-2" type="Grouped" flag="0"> <avp:avpAttribute code="3003" vendorId="111" name="test-avp-3" type="Integer32" flag="0"></avp:avpAttribute> </avp:avpAttribute> </tns:avpAttributeDefinitions> <!-- default template --> <tns:avpTemplate> <avp:avpValue avpName="test-avp-1" defaultValue="hello world."/> <avp:avpValue avpName="test-avp-2"> <avp:avpValue avpName="test-avp-3" defaultValue="2"/> </avp:avpValue> </tns:avpTemplate> <!-- custom template --> <tns:avpTemplate ParameterName="template1"> <avp:avpValue avpName="test-avp-1" defaultValue="hello template 1"/> <avp:avpValue avpName="test-avp-2"> <avp:avpValue avpName="test-avp-3" defaultValue="20"/> </avp:avpValue> </tns:avpTemplate> </tns:paymentConfig>
The Credit Control Interceptor sends Diameter requests based on the content of a request from an application. For each request, you can specify one or more AVPs to send in the request.
You specify the AVPs in an custom global SLA or custom service provider SLA. See Accounts and SLAs Guide, another document in this set. Use the SLA type credit_control
when loading the SLA. For information about Credit Control Interceptor and SLAs, see System Administrator's Guide, another document in this set.
The AVPs are defined in the avpAttributeDefinitions
elements in the credit control SLA. Define this as a sibling to the CCInterceptions
element.
The SLA has the following structure:
<CCInterceptions>
<avpAttributeDefinitions>
<avpAttribute></avp:avpAttribute>
...
</avpAttributeDefinitions>
<CCInterception>
<SubscriptionId>...</SubscriptionId>
<OCSGChargeDescription>...</OCSGChargeDescription>
<ServiceContextId>...</ServiceContextId>
<Amount>...</Amount>
<Currency>...</Currency>
<ServiceIdentifier>...</ServiceIdentifier>
<CallingPartyAddress>...</CallingPartyAddress>
<CalledPartyAddress>...</CalledPartyAddress>
<AsynchronousCommit></AsynchronousCommit>
<customizedAvpValues>...</customizedAvpValues>
</CCInterception>
<CCInterception>
...
</CCInterception>
</CCInterceptions>
The CCInterceptions
element contains a sequence of CCInterception
and avpAttributeDefinitions
elements. It has no attributes.
The CCInterception
element defines the data to set in an AVP and it specifies which method and interface the request that the AVPs are valid for.
It has the following attributes:
interfaceName
Required. Type is String. The Java representation of the Parlay X interface name. For example, com.bea.wlcp.wlng.px21.plugin.SendSmsPlugin
.
methodName
Required. Type is String. The method name. For example, sendSms
.
pluginId
Optional. Type is String. The Id of the plug-in instance the AVP is defined for and serves as a default definition. If it is not present, it is valid for all plug-in instances. If it is present, it overrides the default AVP definition.
The avpAttribute
element is identical to the avpAttribute
element for the Payment plug-in, see "Configuring Customized AVPs for Parlay X 3.0 Payment/Diameter".
The CDR Diameter listener converts CDRs emitted by Services Gatekeeper to Diameter Requests.
The mapping from a CDR to Diameter AVPs is defined in the XML file mapping.xml. The file is located in the EAR files cdr_to_diameter-single.ear and cdr_to_diameter.ear, in the APP-INF\classes directory.
You can define two types of AVPs; dynamic and static.
Dynamic AVPs take fields in the CDR and defines which AVP it is mapped to. The Static AVPs define static values.
The XML file has the following structure:
<mappings>
<mapping/>
...
<mapping/>
</mappings>
The mappings element contains a sequence of mapping. It has no attributes
The mapping element has the following attributes:
edr
Optional. Type is String. Defines the EDR ID to convert.
avp
Required. Type is String. Defines the AVP attribute name part, for example Called-Party-Address.
avpType
Required. Type is String. Defines the data type of the AVP. Possible values are:
INTEGER32
INTEGER64
FLOAT32
FLOAT64
STRING
ADDRESS
GROUPED
BYTES
vendorId
Optional. Type is int. Defines the vendor-ID included in the Diameter request. For example, Oracle's vendor-ID is 111.
mandatory
Optional. Type is Boolean. Defines if the AVP is mandatory or not.
vendorSpecific
Optional. Type is Boolean. Specifies if the AVP is specific for the vendor or if it is a standard AVP.
endToEndEncryption
Optional.Type is Boolean. Specifies if end-to-end encryption shall be used for the request.
avpCode
Required. Type is int. Specifies the numeric value for the AVP attribute part.
mapper
Optional. Type is String. Specifies the class that performs the mapping. Use the fully qualified class name, including he package name.
avpValue
Optional. Type is String. Specifies the value-part of the AVP.
The following rules apply:
If the specified edr
attribute exists, the value in the EDR is forwarded in the Diameter ACR (account request).
f the value in the EDR is an array, all entries are sent as comma-separated values.
If there is no EDR attribute that matches edr, the value set in avpValue
is used.
To define a dynamic EDR to AVP mapping for the time stamp, use the following XML:
<mapping edr="Timestamp" avp="Event-Timestamp" mandatory="true" avpCode="55" avpType="INTEGER32" mapper="com.bea.wlcp.wlng.cdrdiameter.xmlmapper.avpmapper.TimeStampAVPMapper"/>
To define a static AVP, use the following XML:
<mapping edr="CustomizedAVP1" avp="Ocsg-Customized-1" mandatory="false" avpCode="3001" vendorId="111" avpType="STRING" avpValue="test"/>
Applications can define customized AVPs to be sent in the Diameter requests. Applications use tunneled parameters (x parameters) that define the AVPs to be added. The AVPs need to be configured in the SLAs using the same key name as used in the tunneled parameter.
Set the value for the key in the tunneled parameter to the value of the paramName
attribute in the SLA to use a configured AVP.
When you use the SOAP interfaces, the values should be encoded in the SOAP header as follows:
<soapenv:Header>
...
<xparams>
<param key="template1" value="10" />
...
</xparams>
</soapenv:Header>
When you use the Restful interfaces, the values should be encoded in the HTTP header as follows:
X-Plugin-Param-Keys:template1,template2
X-Plugin-Param-Values:10,10
The key and the value for the tunnelled parameters are ordered so the first occurrence in X-Plugin-Param-Keys is for the first occurrence of X-Plugin-Param-Values, and so on.
AVPs are also forwarded in the responses to requests from the SOAP and RESTful interfaces for requests to the Payment communication service.
When you use the SOAP interfaces, the AVPs are returned in the SOAP header in a tunneled parameter with the attribute key
set to AVP_LIST and the attribute value
set to an XML encoded string representing the AVP. An example is:
<param key="
AVP_LIST" value="
AVP_list_in_XML" />
When you use the RESTful interfaces, the AVPs are returned in the HTTP response header in an tunneled parameter with the attribute X-Plugin-Param-Keys set to AVP_LIST and the attribute X-Plugin-Param-Values set to an XML encoded string representing the AVP. An example is:
X-Plugin-Param-Keys:
AVP_LIST
X-Plugin-Param-Values:
AVP_list_in_XML
Below is an example AVP list expressed in XML:
<Avp-List>
<Session-Id>;1280993750;3</Session-Id>
<Origin-Host>ocag.oracle.com</Origin-Host>
<Origin-Realm>oracle.com</Origin-Realm>
<Result-Code>2001</Result-Code>
<CC-Request-Type>4</CC-Request-Type>
<CC-Request-Number>0</CC-Request-Number>
</Avp-List>
When the XML is returned in a SOAP header, values are escaped. For example the < character is converted to <.
When the XML is returned in the HTTP header, all <CR> (carriage return) and <LF> (line feed) characters are removed.