13 Customizing Diameter AVPs

This section describes how to customize Diameter AVPs (Attribute-Value Pairs) for:

• Parlay X 3.0 Payment Diameter communication service

• Credit Control Interceptor

• CDR Diameter listener

Introduction

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.

Configuring Customized AVPs for Parlay X 3.0 Payment/Diameter

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 13-1 illustrates a custom AVP definition for Payment. It defines three AVP attributes and shows how to set the values for these.

Example 13-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>

Configuring Customized AVPs for Credit Control Interceptor

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

Configuring Customized AVPs for CDR Diameter Listener

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"/>

How Applications Can Customize AVPs Dynamically

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 &lt;.

When the XML is returned in the HTTP header, all <CR> (carriage return) and <LF> (line feed) characters are removed.