16 Adding RESTful Quality of Service Support

This chapter describes the RESTful interface for the Oracle Communications Services Gatekeeper Quality of Service (QoS) communication service.

About the QoS Interface

An application can use the QoS RESTful interface to apply a QoS policy, query, modify and remove that policy and register as well as unregister for QoS-related notifications. A Policy Control and Charging Rules Function (PCRF) provider can also return QoS events to registered applications.

See Services Gatekeeper Communication Service Reference Guide for details on using the Extended Web Service Quality of Service/Diameter communication service.

REST Service Descriptions Available at Run-time

When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of QoS operations can be found at

http://host:port/application.wadl

where host and port are the host name and port of the system on which Services Gatekeeper is installed.

Example QoS Scenario

A typical QoS scenario involves a subscriber using a handset to access a video feed using a video application installed on the handset. Initially, because the default QoS is set to a low bandwidth, the video stops and stutters frequently as it is buffered repeatedly over the low speed connection. The subscriber requests a faster QoS through the application, presumably with a corresponding billing charge. Services Gatekeeper forwards that request to a PCRF which then applies the upgraded QoS. The subscriber's video now streams at the upgraded speed, without stuttering.

Note:

While QoS frequently refers to raw bandwidth speed, it can apply to any factors that affect network performance: for example, connection latency and time-out.

Figure 16-1 shows a detailed QoS call flow sequence.

Figure 16-1 Example QoS Call Sequence

Description of Figure 16-1 follows
Description of ''Figure 16-1 Example QoS Call Sequence''

In Figure 16-1:

  1. A user logs in to the video server.

  2. The video server initiates an initial Credit Check Request (CCR) to the PCRF.

  3. The PCRF returns a Credit Check Authorization (CCA) to the video server and the low bandwidth, 256Kbps, QoS plan is applied.

  4. The user plays the video using the low bandwidth QoS plan; video playback is low quality with stuttering and continual buffering requests.

  5. The user requests a better QoS plan using the applyQos RESTful request from the handset's host application.

  6. Upon receiving the applyQoS request, Services Gatekeeper issues an Authorization and Authentication Request (AAR) to the PCRF which then returns an Authorization and Authentication Answer (AAA).

  7. The PCRF issues a Re-Authorization Request (RAR) to Services Gatekeeper, which then returns a Re-Authorization Answer (RAA), and the high bandwidth, 5Mbps QoS plan is applied.

  8. The user plays the video, and the new 5Mbps QoS plan is enforced. The video plays smoothly, without stuttering or continued buffering.

Configuring QoS for Services Gatekeeper

Before you can implement QoS functionality, a QoS plug-in must be deployed and configured in Services Gatekeeper. For information on deploying and configuring QoS plug-ins, see Services Gatekeeper Communication Service Reference Guide.

Using OAuth with QoS

The Services Gatekeeper QoS communication service fully supports OAuth 2.0 authentication between the QoS communication service itself and an AT application.

To establish OAuth authentication between the QoS communication service and your application, do the following:

  1. From your application, contact the QoS communication service and request an OAuth token.

    The QoS communication service will return an OAuth token to your application.

  2. Add the access_token (UUID) to your application's request header:

    access_token: 3ddc24b2-5b17-4d46-8818-6e14726b217c

  3. In addition, add the Authorization parameter to your application's HTTP header:

    Authorization: Bearer 3ddc24b2-5b17-4d46-8818-6e14726b217c

For more information on using OAuth authentication, see Services Gatekeeper OAuth Guide.

Apply QoS

The Apply QoS operation requests that a QoS plan be applied to end user IDs as specified in a Services Gatekeeper QoS plug-in regular expression matching rule.

Authorization

Basic or OAuth 2.0

HTTP Method

POST

URI

http://host:port/ApplicationQoSService/${endUserId}/qos

where:

  • host and port are the host name and port of the system on which Services Gatekeeper is installed.

  • endUserId is a valid end user identifier.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

The request body for the Apply QoS operation accepts the following parameters:

  • duration: Unsigned Long. Optional. The duration of the applied QoS in seconds. If no duration is specified, the QoS session will not time out and will end only when it is explicitly removed.

  • applicationIdentifier: String. Optional. Identifies the service to which the application-facing service session belongs.

  • mediaComponentDescription: Complex. Optional. Service information for a single media component within an application-facing session.

    See "mediaComponentDescription" for details on each of the mediaComponentDescription parameters.

  • serviceInfoStatus: Complex. Optional. Indicates the status of the service information that the application facing interface is providing to the PCRF. If this parameter is not provided, the value FINAL_SERVICE_INFORMATION is assumed. The service info status is specified as one of the following:

    • FINAL_SERVICE_INFORMATION

    • PRELIMINARY_SERVICE_INFORMATION

  • chargingIdentifier: String. Optional. Application facing charging identifier.

  • sipForkingIndication. Enumerated. Optional. Indicates if multiple SIP dialogs are related to a single Diameter session. If this parameter is not provided, the value SINGLE_DIALOGUE is assumed. The SIP forking indication is specified as one of the following:

    • SINGLE_DIALOGUE

    • SEVERAL_DIALOGUES

  • subscriptionId: Complex. Optional. An end user's subscription ID.

    See "subscriptionID" for details on each of the subscriptionId parameters.

  • supportedFeatures: Complex. Optional. If present, informs the destination host about the features that the origin host requires to successfully complete the command exchange.

    See "supportedFeatures" for details on each of the supportedFeatures parameters.

  • reservationPriority. Enumerated. Optional. Applies to all IP flows within the media component and describes the relative importance of the IP flow as compared to other IP flows. If this parameter is not specified, the default value is 0. The reservation priority is specified as one of the following:

    • 0

    • 7

  • framedIPAddress: String. Optional. The valid routable IPv4 or IPv6 address that is applicable for the IP flows toward the user equipment at the PCEF.

  • framedIPv6Prefix: String. Optional. A valid full IPv6 address that is applicable to one or more IP flows toward the user equipment at the PCEF.

  • calledStationId: String. Optional. If a private IP address is being used, the ID of the packet data network.

  • serviceURN. Enumerated. Optional. Indicates that the application function (AF) session is used for emergency traffic. The service URN is specified as one of the following:

    • counseling

    • counseling.children

    • counseling.mental-health

    • counseling.suicide

    • sos

    • sos.ambulance

    • sos.animal-control

    • sos.fire

    • sos.gas

    • sos.marine

    • sos.mountain

    • sos.physician

    • sos.poison

    • sos.police

  • sponsoredConnectivityData: Complex. Optional. Indicates the data associated with the sponsored data connectivity that the AF is providing to the PCRF.

    See "sponsoredConnectivityData" for details on each of the sponsoredConnectivityData parameters.

  • mPSIdentifier: String. Optional. Indicates that an assured-forwarding (AF) session relates to a Malware Protection Systems (MPS) session. It contains the national variant for the MPS service name, for example, Next Generation Network GETS/priority service (NGN GETS).

  • applicationIdentifier: String. Optional. Identifies the particular service to which the media component belongs. If the parameter is not present, the applicationIdentifier from the main body of the request is used.

mediaComponentDescription

These are the parameters for the optional mediaComponentDescription.

  • mediaComponentNumber: Unsigned Integer. Required. Ordinal number of the media component.

  • mediaSubComponent: Complex. Optional. The requested bitrate and filters for the set of IP flows identified by their common flow identifier.

    See "mediaSubComponent" for details on each of the mediaSubComponent parameters.

  • applicationIdentifier: String. Optional. Identifies the particular service to which the media component belongs. If the parameter is not present, the applicationIdentifier from the main body of the request is used.

  • mediaType: Enumerated. Optional. Determines the media type of the session component. The media type is specified as one of the following:

    • AUDIO

    • VIDEO

    • DATA

    • APPLICATION

    • CONTROL

    • TEXT

    • MESSAGE

    • OTHER

  • maxRequestedBandwidthUL. Unsigned Integer. Optional. The maximum requested bandwidth in bits per second for an uplink IP flow.

  • maxRequestedBandwidthDL. Unsigned Integer. Optional. The maximum requested bandwidth in bits per second for a downlink IP flow.

  • minRequestedBandwidthUL. Unsigned Integer. Optional. The minimum requested bandwidth in bits per second for an uplink IP flow.

  • minRequestedBandwidthDL. Unsigned Integer. Optional. The minimum requested bandwidth in bits per second for a downlink IP flow.

  • flowStatus. Enumerated. Optional. Describes whether the IP flows are enabled or disabled. The flow status is specified as one of the following:

    • ENABLED-UPLINK

    • ENABLED-DOWNLINK

    • ENABLED

    • DISABLED

    • REMOVED

  • reservationPriority. Enumerated. Optional. Applies to all those IP flows within the media component and describes the relative importance of the IP flow as compared to other IP flows. If this parameter is not specified, the value is 0. The reservation priority is specified as one of the following:

    • 0

    • 7

  • rSBandwidth. Unsigned Integer. Optional. Indicates the maximum required bandwidth in bits per second for RTCP sender reports within the session component.

  • rBBandwidth. Unsigned Integer. Optional. Indicates the maximum required bandwidth in bits per second for RTCP receiver reports within the session component.

  • codecData: String. Optional. Codec-related information known at the AF. The encoding rule should follow 3gpp TS 29.214 [5.3.7].

mediaSubComponent

These are the parameters for the optional mediaSubComponent parameter.

  • flowNumber. Unsigned Integer. Required. Ordinal number of the IP flow.

  • flowDescription: String. Optional. Filters for an IP flow. The format must follow RFC3588 [4.3] IPFilterRule and 3gpp TS 29.214 [5.3.8].

  • flowStatus. Enumerated. Optional. Describes whether the IP flows are enabled or disabled. The flow status is specified as one of the following:

    • ENABLED-UPLINK

    • ENABLED-DOWNLINK

    • ENABLED

    • DISABLED

    • REMOVED

  • flowUsage. Enumerated Optional. Provides information about the usage of IP flows. The flow usage is specified as one of the following:

    • NO_INFORMATION

    • RTCP

    • AF_SIGNALLING

  • maxRequestedBandwidthUL. Unsigned Integer. Optional. The maximum requested bandwidth in bits per second for an uplink IP flow.

  • maxRequestedBandwidthDL. Unsigned Integer. Optional. The maximum requested bandwidth in bits per second for a downlink IP flow

  • signallingProtocol. Enumerated. Optional. Indicates the protocol used for signalling between the UE and the AF. If this parameter is absent, the value NO_INFORMATION is assumed. The signalling protocol is specified as one of the following:

    • NO_INFORMATION

    • SIP

subscriptionID

These are the parameters for the optional subscriptionID parameter.

  • subscriptionIdType. Enumerated. Required. Type of the end user's subscription ID. The subscription ID type is specified as one of the following:

    • END_USER_E164

    • END_USER_IMSI

    • END_USER_SIP_URI

    • END_USER_NAI

    • END_USER_PRIVATE

  • subscriptionIdData: String. Required. Value of the end user's subscription ID.

supportedFeatures

These are the parameters for the optional supportedFeatures parameter.

  • vendorId. Unsigned Integer. Required. The vendor ID.

  • featureListID. Unsigned Integer. Required. The feature list ID.

  • featureList. Unsigned Integer. Required. A list of the application's supported features.

sponsoredConnectivityData

These are the parameters for the optional sponsoredConnectivityData parameter.

  • sponsorIdentity: String. Optional. String identifying the sponsor.

  • applicationServiceProviderIdentity: String. Optional. String identifying the application service provider.

  • grantedServiceUnit: Complex. Optional. Provides a usage threshold level to the PCRF if the volume of traffic allowed during the sponsored data connectivity is monitored.

    See "grantedServiceUnit" for details on each of the grantedServiceUnit parameters.

  • usedServiceUnit: Complex. Optional. Provides the number of used units from the point at which the service became active, or, if interim measurements are used during the session, the point at which the previous session ended.

    See "grantedServiceUnit" for details on each of the usedServiceUnit parameters. Note that the parameters are identical to those of grantedServiceUnit.

grantedServiceUnit

These are the parameters for the optional grantedServiceUnit parameter.

  • tariffTimeChange: Enumerated. Optional. Determines the timing of the unit relative to a tariff time change. The tariff time change parameter can take the following values:

    • UNIT_BEFORE_TARIFF_CHANGE

    • UNIT_AFTER_TARIFF_CHANGE

    • UNIT_INDETERMINATE

  • cCTime. Unsigned Integer. Optional. Indicates the length of requested, granted or used time in seconds.

  • cCMoney: Complex. Optional. Specifies the monetary amount in a given currency. See "cCMoney" for details.

  • cCTotalOctets. Unsigned 64-bit Integer. Optional. Specifies the total number of the granted, requested or used octets, regardless of the flow direction.

  • cCInputOctets. Unsigned 64-bit Integer. Optional. Specifies the total number of the granted, requested or used octets, that either can be or have been received from an end user.

  • cCOutputOctets. Unsigned 64-bit Integer. Optional. Specifies the total number of the granted, requested or used octets, that either can be or have been sent to an end user.

  • cCServiceSpecificUnits. Unsigned 64-bit Integer. Optional. Specifies the number of service specific units provided in a particular service.

cCMoney

These are the parameters for the optional ccMoney parameter.

  • unitValue. Decimal. Required. Specifies a multiplier that converts between units of a particular unit type and abstract units within the service credit pool.

  • currencyCode. Unsigned Integer. Optional. Specifies in which currency the cost was given. Must follow the numeric values defined in the ISO 4217 standard.

Custom AVPs in QoS Requests

In addition to the preset elements, Services Gatekeeper QoS requests can accommodate custom AVP definitions as long as they are supported by the Diameter server. Such custom AVP definitions can be added to the following elements in any number:

  • mediaSubComponent

  • supportedFeatures

  • sponsoredConnectivityData

  • grantedServiceUnit

  • usedServiceUnit

Example 16-1 shows a portion of a JSON request specifying a parameter with the name myCustomDiameterParameter and the value My diameter parameter value.

Example 16-1 Custom JSON AVP Request

  "parameter": {
    "name": "myCustomDiameterParameter"
    "value": "My diameter parameter value"
  }

Request Example

Example 16-2 shows an example of an apply QoS request body.

Example 16-2 Apply QoS Request Body

{
  "qoSFeatureProperties": {
    "duration": 3600,
    "applicationIdentifier": "test_app_id",
    "mediaComponentDescription": [
      {
        "mediaComponentNumber": 1,
        "mediaSubComponent": [
          {
            "flowNumber": 1,
            "flowDescription": [
              "test_flow"
            ],
            "flowStatus": "ENABLED-UPLINK",
            "flowUsage": "NO_INFORMATION",
            "maxRequestedBandwidthUL": 3300,
            "maxRequestedBandwidthDL": 2200,
            "signallingProtocol": "SIP"
          }
        ],
        "applicationIdentifier": "test",
        "mediaType": "AUDIO",
        "maxRequestedBandwidthUL": 1000,
        "maxRequestedBandwidthDL": 1000,
        "minRequestedBandwidthUL": 10,
        "minRequestedBandwidthDL": 10,
        "flowStatus": "ENABLED-UPLINK",
        "reservationPriority": 1,
        "rSBandwidth": 10,
        "rRBandwidth": 10,
        "codecData": [
          "codec"
        ]
      }
    ],
    "serviceInfoStatus": "FINAL_SERVICE_INFORMATION",
    "chargingIdentifier": "charging_id",
    "sIPForkingIndication": "SINGLE_DIALOGUE",
    "subscriptionId": [
      {
        "subscriptionIdType": "END_USER_E164",
        "subscriptionIdData": "861013388991111"
      }
    ],
    "supportedFeatures": [
      {
        "vendorId": 1,
        "featureListID": 1,
        "featureList": 333
      }
    ],
    "reservationPriority": 1,
    "framedIPAddress": "0A987898",
    "calledStationId": "adsf",
    "serviceURN": "counseling",
    "sponsoredConnectivityData": {
      "sponsorIdentity": "1adsf",
      "applicationServiceProviderIdentity": "1ss",
      "grantedServiceUnit": {
        "tariffTimeChange": 122,
        "cCTime": 444,
        "cCMoney": {
          "unitValue": 1,
          "currencyCode": 11
        },
        "cCTotalOctets": 1,
        "cCInputOctets": 1,
        "cCOutputOctets": 1,
        "cCServiceSpecificUnits": 1
      }
    },
    "mPSIdentifier": "mps_id"
  }
}

Response Header

In addition to the standard header fields, two additional fields are returned:

  • X-Plugin-Param-Keys. Comma-separated keys that map to the values returned in X-Plugin-Param-Values. Two values are returned:

    • AVP_LIST. Key matching the Avp-List XML structure returned in X-Plugin-Param-Values.

    • session-id. Key matching the session ID returned in X-Plugin-Param-Values.

  • X-Plugin-Param-Values. Comma-separated values that are mapped to their respective keys returned in X-Plugin-Param-Keys.

For the Avp-List XML structure, different Diameter servers may return different elements and values, the only required element being the Result-Code. For detailed information on the possible elements and values, see the UMTS Policy and charging control over Rx reference point (ETSI TS 129 214 V10.6.0) available at .

http://www.etsi.org/deliver/etsi_ts/129200_129299/129214/10.06.00_60/ts_129214v100600p.pdf

Likewise, the session-id format is dependent upon your Diameter server.

Example 16-3 shows a possible response header.

Example 16-3 Response Header

HTTP/1.1 201 Created
Date: Mon, 11 Mar 2013 03:29:11 GMT
Transfer-Encoding: chunked
Location: http://localhost:8001/ApplicationQoSService/tel%3A88888888/qos/localhost%3B
1362972174%3B0-1362972554169
Content-Type: application/json
X-Plugin-Param-Keys: AVP_LIST,session-id
X-Plugin-Param-Values: <Avp-List><Session-Id>localhost;1362972174;0</Session-Id><Origin-Host>MINFXU-CN</
Origin-Host><Origin-Realm>oracle.com</Origin-Realm><Result-Code>2001</Result-Code>
<IP-CAN-Type>0</IP-CAN-Type><RAT-Type>0</RAT-Type></Avp-List>,localhost;1362972174
;0
X-Powered-By: Servlet/2.5 JSP/2.1

If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".

Response Body

The response body contains an array of structures as the value for applyQoSFeatureResponse. Each element in the array contains values for the following parameters.

  • requestId: String. The request ID. Used to uniquely identify the QoS session.

  • actualProperties: Complex. Additional properties resulting from the request.

    See "actualProperties" for details on each of the actualProperties parameters.

actualProperties

These are the values returned for the actualProperties parameter.

  • accessNetworkChargingIdentifier: Complex. Contains a charging identifier within the accessNetworkChargingIdentifierValue AVP along with information about the flows transported within the corresponding bearer within the flows AVP. If no flows AVP is provided, the accessNetworkChargingIdentifierValue applies to all flows within the AF session.

  • accessNetworkChargingAddress: String. Indicates the IP address of the network entity that handles charging within the access network.

  • acceptableServiceInfo: Complex. Contains the maximum bandwidth for an AF session and/or for specific media components that will be authorized by the PCRF.

  • iPCANType. Enumerated. Indicates the type of Connectivity Access Network (CAN) to which a user is connected. The CAN type is specified as one of the following:

    • _3GPP-GPRS

    • DOCSIS

    • xDSL

    • WiMAX

    • _3GPP2

    • _3GPP-EPS

    • Non-3GPP-EPS

  • rATType. Identifies the Radio Access Technology (RAT) that is servicing the user equipment. The RAT type is specified as one of the following:

    • WLAN

    • VIRTUAL

    • UTRAN

    • GERAN

    • GAN

    • HSPA_EVOLUTION

    • EUTRAN

    • CDMA2000_1X

    • HRPD

    • UMB

    • EHRPD

  • flows: Complex. Indicates IP flows using their flow identifiers.

    See "flows" for details on each of the flows parameters.

  • supportedFeatures: Complex. See "supportedFeatures" for detailed information.

accessNetworkChargingIdentifier

These are the values returned for the accessNetworkChargingIdentifier parameter.

  • accessNetworkChargingIdentifierValue: String. Includes the charging identifier.

  • flows: Complex. Indicates IP flows using their flow identifiers. See "flows" for details on each of the flows parameters.

flows

These are the values returned for the flows parameter.

  • mediaComponentNumber. Unsigned Integer. Ordinal number of the media component.

  • flowNumber. Integer. Indicates the number of the flow. If no flowNumber AVPs are supplied, this refers to all flows matching the media component number.

  • finalUnitAction. Enumerated. When reporting an out of credit condition, the finalUnitAction indicates the termination action applied to the impacted flows. Indicates to the credit-control client the action to be taken when a user's account cannot cover the service cost. The final unit action is specified as one of the following:

    • TERMINATE

    • REDIRECT

    • RESTRICT_ACCESS

acceptableServiceInfo

These are the values returned for the acceptableServiceInfo parameter.

  • mediaComponentDescription: Complex. See "mediaComponentDescription" for detailed information.

  • maxRequestedBandwidthUL. Unsigned Integer. The maximum requested bandwidth in bits per second for an uplink IP flow.

  • maxRequestedBandwidthDL. Unsigned Integer. The maximum requested bandwidth in bits per second for a downlink IP flow

Response Body Example

Example 16-4 shows an example of an apply QoS response body.

Example 16-4 Apply QoS Response Body

{"applyQoSFeatureResponse": {
    "requestId": "localhost;1362972174;0-1362972554169",
    "actualProperties": {
      "iPCANType": "_3GPP-GPRS",
      "rATType": "WLAN"
    }
  }
}

Apply Template-Based QoS

An operation to apply a template-based QoS requires that a QoS plan based upon a template stored in Services Gatekeeper be applied to end user IDs. The QoS plan is specified as a Services Gatekeeper QoS plug-in regular expression matching rule.

QoS Templates

QoS templates must be formatted according to the XSD found in the xsd subdirectory in the plugin_qos_diameter.jar file, which itself is contained within the wlng_nt_qos.ear archive located in Middleware_Home/ocsg_release/applications directory, where release is the release version of Services Gatekeeper. Example 16-10 shows a reference template containing all of the possible elements and attributes for a request.

Following is a sample QoS template:

Example 16-5 QoS Template Example

<QoSTemplate xmlns="http://oracle/ocsg/rest/qos/template"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://oracle/ocsg/rest/qos/template ../xsd/qosTemplate.xsd"
  templateId="default_template">
  <applicationIdentifier parameterName="$APP_ID">4d6f62696c655456</applicationIdentifier>
  <!--Zero or more repetitions: -->
  <mediaComponentDescription>
    <mediaComponentNumber>0</mediaComponentNumber>
    <!--Zero or more repetitions: -->
    <mediaSubComponent>
      <flowNumber parameterName="$FLOW_NUMBER_0">1</flowNumber>
      <!--0 to 2 repetitions: -->
      <flowDescription parameterName="$FLOW_DESCRIPTION_0">
 <![CDATA[permit out 8001 from assigned 34 to 24.2.1.6/18 8000]]></flowDescription>
    </mediaSubComponent>
                <mediaType parameterName="$MED_TYPE">VIDEO</mediaType>
    <flowStatus parameterName="$FLOW_STATUS">ENABLED</flowStatus>
  </mediaComponentDescription>
  <!--Optional: -->M
  <serviceInfoStatus parameterName="$SERV_INFO_STATUS">PRELIMINARY_SERVICE_INFORMATION</serviceInfoStatus>
  <!--Optional: -->
  <chargingIdentifier parameterName="$CHG_ID">charging-id-555</chargingIdentifier>
  <!--Optional: -->
  <sIPForkingIndication parameterName="$SIP_FORK_IND">SINGLE_DIALOGUE</sIPForkingIndication>
  <subscriptionId>
    <subscriptionIdType parameterName="$SUB_ID_TYPE">END_USER_E164</subscriptionIdType>
    <subscriptionIdData parameterName="$SUB_ID_DATA">14128771501</subscriptionIdData>
  </subscriptionId>
  <serviceURN parameterName="$SERV_URN">sos.police</serviceURN>
</QoSTemplate>

In Example 16-5, each element has a parameterName attribute whose value maps to the request's parameter name. The parameterName attribute identifier must be unique throughout the entire template. For example, if you have two instances of the element applicationIdentifier (one for the whole template and one for a sub-component), you can use the following names for each instance: $APP_ID_0 and $APP_ID_1.

If a parameter is set dynamically in a request, its value replaces the default value configured in the template. For example, if a request sets the $FLOW_DESCRIPTION_0 parameter value to "modified flow description", the PCRF will receive that value rather than the one defined in the template.

Custom AVPs in QoS Templates

In addition to the preset elements, QoS templates can accommodate custom AVP definitions, both simple and enumerated, as long as they are supported by the Diameter server. Any number of such custom AVP definitions can be added to the following elements:

  • mediaSubComponent

  • supportedFeatures

  • sponsoredConnectivityData

  • grantedServiceUnit

  • usedServiceUnit

Example 16-6 shows a simple custom AVP template in which the type of the custom parameter is set to String, the parameterName is set to $MY_CUSTOM_DIAMETER_PARAMETER, and the value of the custom parameter is set to My Diameter value.

Example 16-6 Custom AVP Template Element

<avp name="myCustomDiameterParameter" description="This is a sample AVP" 
code="234567" may-encrypt="true" mandatory-flag="optional" vendor-id="Oracle 
Corporation" constrained="false">
   <type type-name="Integer32"/>
   <value parameterName="$MY_CUSTOM_DIAMETER_PARAMETER">"My Diameter Value"</value>
</avp>

Example 16-7 shows a custom enumerated AVP element where the AVP name is myCustomDiameterParameter, and two possible enumerated values are defined:

  • ENUM_1, the logical name associated with the enumerated type, 0.

  • ENUM_2, the logical name associated with the enumerated type, 1.

The parameterName, $ENUM_VAL, can be replaced like any standard template parameter with a value of either ENUM_1 or ENUM_2.

Note:

For custom enumerated AVPs, the type element's type-name attribute is always Integer32.

Example 16-7 Custom Enumerated AVP Template Element

<avp name="myCustomEnumDiameterParameter" description="This is a sample AVP" 
code="12345" may-encrypt="true" mandatory-flag="required" vendor-id="Oracle 
Corporation" constrained="false">
   <type type-name="Integer32"/>
   <enum name=”ENUM_1” code=”0”/>
   <enum name=”ENUM_2” code=”1”/>
   <value parameterName=”$ENUM_VAL”>ENUM_1</value>
</avp>

Managing QoS Templates in Services Gatekeeper

You use the Services Gatekeeper Administration Console or the Platform Test Environment to load, modify and query QoS templates using MBeans. Table 16-1 lists the available MBean operations and their descriptions:

Table 16-1 QoS Template Management MBean Operations

Operation Description

listQoSRequestTemplateMatchRules

Lists all of the match rules that have been defined for the QoS plug-in.

loadQoSRequestTemplate

Loads a QoS template.

retrieveQoSRequestTemplate

Retrieves a QoS template associated with a particular subscriber ID or a range of subscriber IDs.

deleteQoSRequestTemplate

Deletes a QoS template associated with a particular subscriber ID or a range of subscriber IDs.

For more information on loading, retrieving, listing, and deleting QoS templates, see Services Gatekeeper Communication Service Reference Guide.

Authorization

Basic or OAuth 2.0

HTTP Method

POST

URI

http://host:port/ApplicationQoSService/${endUserId}/qos/templatebased

where:

  • host and port are the host name and port of the system on which Services Gatekeeper is installed.

  • endUserId is a valid end user identifier.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

The request body for the operation to apply template-based QoS accepts the following parameters:

  • duration: Unsigned Long. Required. The duration of the applied QoS in seconds.

  • applicationIdentifier: String. Optional. Identifies the service to which the application-facing service session belongs.

  • framedIPAddress. Hexadecimal Binary. Optional. The valid routable IPv4 or IPv6 address that is applicable for the IP Flows toward the user equipment at the PCEF.

  • framedIPv6Prefix. Hexadecimal Binary. Optional. A valid full IPv6 address that is applicable to an IP flow or IP flows toward the user equipment at the PCEF.

  • calledStationId: String. Optional. If a private IP address is being used, the ID of the packet data network.

  • parameter: Complex. Optional. An array of JSON objects that define which template parameters will be replaced and what the replacement values will be.

    The array of JSON objects are a collection of one or more AVPs labeled name and value that determine which parameters in the QoS template will be replaced and what the replacement values will be. In Example 16-8, the values for the template parameters $CHG_ID and $MAX_REQ_BAND_DL will be replaced with the values "charging_id_test" and 2048 respectively.

Request Body Example

Example 16-8 shows a request body associated with an example Template-based QoS request.

Example 16-8 Example Request Body when a Template-Based QoS is Applied

{
  "templateQoSFeatureProperties": {
    "duration": 3600,
    "applicationIdentifier": "app_id",
    "framedIPAddress": "0A0B9899",
    "calledStationId": "called_station_id",
    "parameter": [
      {
        "name": "$CHG_ID",
        "value": "charging_id_test"
      },
      {
        "name": "$MAX_REQ_BAND_DL",
        "value": 2048
      }
    ]
  }
}

Response Header

For details on the response header, see the Apply QoS "Response Header" section.

Response Body

The response body parameters for the request to apply template-based QoS are the same as those for the Apply QoS operation. See the Apply QoS "Response Body" section for details.

Response Body Example

Example 16-9 shows the response body associated with an example Template-based QoS request.

Example 16-9 Example Response Body for Template-Based QoS Request

{
  "applyQoSFeatureResponse": {
    "requestId": "localhost;1362972174;1-1362973261091",
    "actualProperties": {
      "iPCANType": "_3GPP-GPRS",
      "rATType": "WLAN"
    }
  }
}

Reference: Complete QoS Template

Example 16-10 is a QoS template containing all of the available elements and attributes from the reference XSD.

Example 16-10 A Complete QoS Template

<QoSTemplate xmlns="http://oracle/ocsg/rest/qos/template"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://oracle/ocsg/rest/qos/template ../xsd/qosTemplate.xsd"
  templateId="default_template">
  <applicationIdentifier parameterName="$APP_ID">test_appId</applicationIdentifier>
  <!--Zero or more repetitions: -->
  <mediaComponentDescription>
    <mediaComponentNumber>0</mediaComponentNumber>
    <!--Zero or more repetitions: -->
    <mediaSubComponent>
      <flowNumber parameterName="$FLOW_NUMBER_0">0</flowNumber>
      <!--0 to 2 repetitions: -->
      <flowDescription parameterName="$FLOW_DESCRIPTION_0">flow0_Description</flowDescription>
      <!--Optional: -->
      <flowStatus parameterName="$FLOW_STATUS_0">ENABLED</flowStatus>
      <!--Optional: -->
      <flowUsage parameterName="$FLOW_USAGE_0">NO_INFORMATION</flowUsage>
      <!--Optional: -->
      <maxRequestedBandwidthUL parameterName="$MAX_REQ_BAND_UL_0">1000</maxRequestedBandwidthUL>
      <!--Optional: -->
      <maxRequestedBandwidthDL parameterName="$MAX_REQ_BAND_DL_0">1000</maxRequestedBandwidthDL>
      <!--Optional: -->
      <signallingProtocol parameterName="$SIG_PROTOCOL_0">SIP</signallingProtocol>
    </mediaSubComponent>
    <!--Optional: -->
    <applicationIdentifier parameterName="$MED_DES_APP_ID">test_appId</applicationIdentifier>
    <!--Optional: -->
    <mediaType parameterName="$MED_TYPE">AUDIO</mediaType>
    <!--Optional: -->
    <maxRequestedBandwidthUL parameterName="$MAX_REQ_BAND_UL">1000</maxRequestedBandwidthUL>
    <!--Optional: -->
    <maxRequestedBandwidthDL parameterName="$MAX_REQ_BAND_DL">1000</maxRequestedBandwidthDL>
    <!--Optional: -->
    <minRequestedBandwidthUL parameterName="$MIN_REQ_BAND_UL">10</minRequestedBandwidthUL>
    <!--Optional: -->
    <minRequestedBandwidthDL parameterName="$MIN_REQ_BAND_UL">10</minRequestedBandwidthDL>
    <!--Optional: -->
    <flowStatus parameterName="$FLOW_STATUS">ENABLED</flowStatus>
    <!--Optional: -->
    <reservationPriority parameterName="$RES_PRI">0</reservationPriority>
    <!--Optional: -->
    <rSBandwidth parameterName="$RS_BAND">1000</rSBandwidth>
    <!--Optional: -->
    <rRBandwidth parameterName="$RR_BAND">1000</rRBandwidth>
    <!--0 to 2 repetitions: -->
    <codecData parameterName="$CODEC_DATA">CODEC</codecData>
  </mediaComponentDescription>
  <!--Optional: -->
  <serviceInfoStatus parameterName="$SERV_INFO_STATUS">FINAL_SERVICE_INFORMATION</serviceInfoStatus>
  <!--Optional: -->
  <chargingIdentifier parameterName="$CHG_ID">test_charging</chargingIdentifier>
  <!--Optional: -->
  <sIPForkingIndication parameterName="$SIP_FORK_IND">SINGLE_DIALOGUE</sIPForkingIndication>
  <!--Zero or more repetitions: -->
  <subscriptionId>
    <subscriptionIdType parameterName="$SUB_ID_TYPE">END_USER_E164</subscriptionIdType>
    <subscriptionIdData parameterName="$SUB_ID_DATA">13693312888</subscriptionIdData>
  </subscriptionId>
  <!--Zero or more repetitions: -->
  <supportedFeatures>
    <vendorId parameterName="$VENDOR_ID">654321</vendorId>
    <featureListID parameterName="$FEATURE_LIST_ID">654320</featureListID>
    <featureList parameterName="$FEATURE_LIST">654322</featureList>
    <!--Zero or more repetitions: -->
    <avp name="test_supported_feature" description="test supported feature avp"
      code="688788" may-encrypt="true" mandatory-flag="required" vendor-id="87349"
      constrained="false">
      <grouped>
        <!--1 or more repetitions: -->
        <gavp name="grouped_avp" />
      </grouped>
      <avps name="avps_name" code="96785">
        <type type-name="String"/>
        <value parameterName="$customer_avps_name">xmf</value>
      </avps>
    </avp>
  </supportedFeatures>
  <!--Optional: -->
  <reservationPriority parameterName="$RESV_PRI">0</reservationPriority>
  <!--Optional: -->
  <framedIPAddress></framedIPAddress>
  <!--Optional: -->
  <framedIPv6Prefix></framedIPv6Prefix>
  <!--Optional: -->
  <calledStationId></calledStationId>
  <!--Optional: -->
  <serviceURN parameterName="$SERV_URN">sos.fire</serviceURN>
  <!--Optional: -->
  <sponsoredConnectivityData>
    <!--Optional: -->
    <sponsorIdentity parameterName="$SPON_ID">spon_id</sponsorIdentity>
    <!--Optional: -->
    <applicationServiceProviderIdentity
      parameterName="$SPON_APP_SERV_PROV_ID">spon_serv_prov_id</applicationServiceProviderIdentity>
    <!--Optional: -->
    <grantedServiceUnit>
      <!--Optional: -->
      <tariffTimeChange parameterName="$TARIF_TIME_CHG">1</tariffTimeChange>
      <!--Optional: -->
      <cCTime parameterName="$CC_TIME">60</cCTime>
      <!--Optional: -->
      <cCMoney>
        <unitValue parameterName="$UNIT_VAL">6.28</unitValue>
        <!--Optional: -->
        <currencyCode parameterName="$CUR_CODE">80</currencyCode>
      </cCMoney>
      <!--Optional: -->
      <cCTotalOctets parameterName="$CC_TOTAL_OCTS">1000000</cCTotalOctets>
      <!--Optional: -->
      <cCInputOctets parameterName="$CC_INPUT_OCTS">500000</cCInputOctets>
      <!--Optional: -->
      <cCOutputOctets parameterName="$CC_OUTPUT_OCTS">500000</cCOutputOctets>
      <!--Optional: -->
      <cCServiceSpecificUnits parameterName="$CC_SERV_SPEC_UNIT">1</cCServiceSpecificUnits>
    </grantedServiceUnit>
  </sponsoredConnectivityData>
  <!--Optional: -->
  <mPSIdentifier parameterName="$MPS_ID">mps_id</mPSIdentifier>
  <!--Zero or more repetitions: -->
  <avp name="myRandomAVP" description="This is a sample AVP" code="93222" may-encrypt="true" mandatory-flag="required" vendor-id="Oracle Corporation" constrained="false">
    <type type-name="Integer32"/>
    <enum name="ENUM_1" code="0"/>
    <enum name="ENUM_2" code="1"/>
    <value parameterName="$ENUM_VAL">ENUM_1</value>
  </avp>
</QoSTemplate>

Modify QoS

The Modify QoS operation lets you modify the parameters of an existing QoS plan.

Authorization

Basic or OAuth 2.0

HTTP Method

PUT

URI

http://host:port/ApplicationQoSService/qos/${requestId}

where:

  • host and port are the host name and port of the system on which Services Gatekeeper is installed.

  • requestId is a valid QoS request ID.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

To modify a QoS session, create a request body with the parameters you want changed. See the Apply QoS "Request Body" section for a complete listing of request body parameters.

Request Body Example

Example 16-11 shows an example of a modify QoS request body.

Example 16-11 Modify QoS Request Body

{
  "qoSFeatureProperties": {
    "applicationIdentifier": "654321"
  }
}

Response Header

For details on the response header, see the Apply QoS "Response Header" section.

Response Body

The response body contains an array of structures as the value for actualProperties. See "actualProperties" for complete details.

Response Body Example

Example 16-12 shows an example of a modify QoS response body.

Example 16-12 Modify QoS Response Body

{
  "actualProperties": {
    "iPCANType": "_3GPP-GPRS",
    "rATType": "WLAN"
  }
}

Template-Based Modify QoS

The Template-based Modify QoS operation requests a modification to an existing template-based QoS plan.

Authorization

Basic or OAuth 2.0

HTTP Method

POST

URI

http://host:port/ApplicationQoSService/qos/${requestId}/templatebased

where:

  • host and port are the host name and port of the system on which Services Gatekeeper is installed.

  • requestId is a valid QoS request ID.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

To modify a template-based QoS session, create a request body with the parameters you want changed. See the Apply Template-based QoS "Request Body" section for a complete listing of request body parameters.

Request Body Example

Example 16-13 shows an example of a modify template-based QoS request body.

Example 16-13 Modify Template-Based QoS Request Body

{
  "templateQoSFeatureProperties": {
    "parameter": [
      {
        "name": "$FLOW_DESCRIPTION_0",
        "value": "permit out 8001 from assigned 34 to 24.2.1.6/18 8000"
      }
    ]
  }
}

Response Header

For details on the response header, see the Apply QoS "Response Header" section.

Response Body

See "actualProperties" for details on the response body parameters for a Modify Template-based QoS requests.

Response Body Example

Example 16-14 shows an example of a Modify Template-based QoS response body.

Example 16-14 Modify Template-Based QoS Response Body

{
  "actualProperties": {
    "iPCANType": "_3GPP-GPRS",
    "rATType": "WLAN"
  }
}

Get QoS Status

The Get QoS Status operation returns detailed information on the currently applied QoS plan.

Authorization

Basic or OAuth 2.0

HTTP Method

GET

URI

http://host:port/ApplicationQoSService/qos/${requestId}

where:

  • host and port are the host name and port of the system on which Services Gatekeeper is installed.

  • requestId is a valid QoS session identifier.

Request Header

Standard header fields.

Request Body

There is no request body.

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".

Response Body

The response body contains an array of structures as the value for qoSStatus. Each element in the array contains values for the following parameters.

  • userIsConnected. Boolean. True indicates a user is connected. False indicates a user is disconnected.

  • actualProperties: Complex. Additional properties resulting from the request.

    See "actualProperties" for details on each of the actualProperties parameters.

  • qosFeatureProperties: Complex. Additional properties resulting from the request.

    See the "Request Body" section of the "Apply QoS" operation for details on each of the qosFeatureProperties parameters.

Response Body Example

Example 16-15 shows an example of a QoS status response body.

Example 16-15 QoS Status Response Body

{
  "qoSStatus": {
    "userIsConnected": true,
    "actualProperties": {
      "iPCANType": "_3GPP-GPRS",
      "rATType": "WLAN"
    },
    "qosFeatureProperties": {
      "duration": 3600,
      "applicationIdentifier": "654321",
      "mediaComponentDescription": [
        {
          "mediaComponentNumber": 0,
          "mediaSubComponent": [
            {
              "flowNumber": 1,
              "flowDescription": [
                "flow_1"
              ],
              "flowStatus": "ENABLED-UPLINK",
              "flowUsage": "NO_INFORMATION",
              "maxRequestedBandwidthUL": 100,
              "maxRequestedBandwidthDL": 500,
              "signallingProtocol": "NO_INFORMATION"
            }
          ],
          "applicationIdentifier": "test_app_id",
          "mediaType": "VIDEO",
          "maxRequestedBandwidthUL": 200,
          "maxRequestedBandwidthDL": 1000,
          "minRequestedBandwidthUL": 10,
          "minRequestedBandwidthDL": 100,
          "flowStatus": "ENABLED",
          "reservationPriority": 1
        }
      ],
      "serviceInfoStatus": "FINAL_SERVICE_INFORMATION",
      "chargingIdentifier": "charging_id",
      "subscriptionId": [
        {
          "subscriptionIdType": "END_USER_E164",
          "subscriptionIdData": "88888888"
        }
      ],
      "framedIPAddress": "0A999899",
      "calledStationId": "EE-AA-CD-AF-09"
    }
  }
}

Remove QoS

The Remove QoS operation removes a current QoS plan identified by a request ID.

Authorization

Basic or OAuth 2.0

HTTP Method

DELETE

URI

http://host:port/ApplicationQoSService/qos/${requestId}

where:

  • host and port are the host name and port of the system on which Services Gatekeeper is installed.

  • requestId is a valid QoS session identifier.

Request Header

The MIME-type for the Content-Type header field is application/x-www-form-urlencoded.

Request Body

There is no request body.

Response Header

For details on the response header, see the Apply QoS "Response Header" section.

Response Body

There is no response body.

Register for QoS Notifications

The Register for QoS Notifications operation lets an application to register to receive QoS events. A QoS event notification is generated by a PCRF when an event is triggered for which an application has registered to receive notifications.

Table 16-2 shows the events an application can register to receive.

Table 16-2 QoS Event Types

Event Type Trigger Condition

QOS_FEATURE_RELEASED

Triggered when the AF session times out. Controlled by the duration parameter in the QoS session request.

CHARGING_CORRELATION_EXCHANGE

If different Access Network Charging Information is applicable to the IP-CAN session, the PCRF will notify the AF about the Access Network Charging Information that applies to each authorized flow.

INDICATION_OF_LOSS_OF_BEARER

The server reports a loss of a bearer to the AF.

INDICATION_OF_RECOVERY_OF_BEARER

The server reports a recovery of a bearer to the AF.

INDICATION_OF_RELEASE_OF_BEARER

The server reports the release of a bearer to the AF.

IP_CAN_CHANGE

The server indicates a change in the IP-CAN type or RAT type (if the IP-CAN type is GPRS).

INDICATION_OF_OUT_OF_CREDIT

The PCRF reports to the AF that the SDFs have run out of credit and that the termination action determined by the finalUnitAction AVP applies.

INDICATION_OF_SUCCESSFUL_RESOURCES_ALLOCATION

The PCRF reports that the requested resources have been successfully allocated.

INDICATION_OF_FAILED_RESOURCES_ALLOCATION

The PCRF reports that the requested resources could not be successfully allocated.

INDICATION_OF_LIMITED_PCC_DEPLOYMENT

The server reports limited PCC deployment—dynamically allocated resources are not available.

USAGE_REPORT

The PCRF reports accumulated usage volume when the usage threshold provided by the AF has been reached.

Authorization

Basic or OAuth 2.0

HTTP Method

POST

URI

http://host:port/ApplicationQoSNotification/registration

where:

  • host and port are the host name and port of the system on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

The request body for the Apply QoS operation accepts the following parameters:

  • reference: Complex. Required. Defines the application endpoint, interfaceName and correlator used to notify the application.

  • endUserIdentities. Array. Required. Network end users to be monitored for events. An array of one or more end user IDs.

  • eventCriteria. Array. Required. One or more events to be monitored. Events are specified by their numeric event ID. Table 16-3 shows the mapping of numeric event IDs to logical event IDs. For definitions of these events, see Table 16-2.

    Table 16-3 Numeric to Logical QoS Event Mapping

    Numeric Event Logical Event Name

    1

    CHARGING_CORRELATION_EXCHANGE

    2

    INDICATION_OF_LOSS_OF_BEARER

    3

    INDICATION_OF_RECOVERY_OF_BEARER

    4

    INDICATION_OF_RELEASE_OF_BEARER

    6

    IP-CAN_CHANGE

    7

    INDICATION_OF_OUT_OF_CREDIT

    8

    INDICATION_OF_SUCCESSFUL_RESOURCES_ALLOCATION

    9

    INDICATION_OF_FAILED_RESOURCES_ALLOCATION

    10

    INDICATION_OF_LIMITED_PCC_DEPLOYMENT

    11

    USAGE_REPORT

    12

    QOS_FEATURE_RELEASED

reference

These are the parameters for the reference parameter.

  • endpoint: String. Required. The notification end point expected by the AF.

  • interfaceName: String. Required. The interface name. Rarely used.

  • correlator: String. Required. A unique ID for the message.

Request Body Example

Example 16-16 shows an example of a Register for QoS Notifications request body.

Example 16-16 Register for QoS Notifications Request Body

{
  "startQoSNotification": {
    "reference": {
      "endpoint": "http://endpt_host:port/jaxrs/QoSNotification",
      "interfaceName": "interfaceName",
      "correlator": "987654321"
    },
    "endUserIdentities": [
      "tel:88888888", "tel:123456", "tel:234567"
    ],
    "eventCriteria": [
      "1", "2", "6", "7"
    ]
  }
}

Response header

For details on the response header, see the Apply QoS "Response Header" section.

Response Body

There is no response body.

Unregister for QoS Notifications

The Unregister for QoS Notifications operation requests that the server cease sending an application QoS notifications.

Authorization

Basic or OAuth 2.0

HTTP Method

DELETE

URI

http://host:port/ApplicationQoSNotification/registration/${correlator}

where:

  • host and port are the host name and port of the system on which Services Gatekeeper is installed.

  • correlator is the unique identifier of the original notification request.

Request Header

The MIME-type for the Content-Type header field is application/x-www-form-urlencoded.

Request Body

There is no request body.

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".

Response Body

There is no response body.

QoS Event Notification

A QoS event notification is generated by a PCRF when an event is triggered for which an application has registered to receive notifications.

Authorization

Basic or OAuth 2.0

HTTP Method

POST

URI

http://host:port/QoSNotification

where:

  • host and port are the host name and port of the system on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

The request body for the QoS Event Notification operation accepts the following parameters:

  • correlator: String. Required. The duration of the applied QoS in seconds.

  • endUserIdentities. URI. Required. Identifies the service to which the application-facing service session belongs.

  • eventType: Complex. Required. The valid routable IPv4 address that is applicable for the IP Flows toward the user equipment at the PCEF.

  • subscriptionId: Complex. Optional. A valid full IPv6 address that is applicable to an IP flow or IP flows toward the user equipment at the PCEF.

  • accessNetworkChargingIdentifier: Complex. Optional. Contains a charging identifier within the accessNetworkChargingIdentifierValue AVP along with information about the flows transported within the corresponding bearer within the flows AVP. If no flows AVP is provided, the accessNetworkChargingIdentifierValue applies to all flows within the AF session.

    See "accessNetworkChargingIdentifier" for details on each of the accessNetworkChargingIdentifier parameters.

  • accessNetworkChargingAddress: String. Optional. Indicates the IP address of the network entity that handles charging within the access network.

  • iPCANType. Enumerated. Optional. Indicates the type of Connectivity Access Network (CAN) to which a user is connected. The CAN type is specified as one of the following:

    • _3GPP-GPRS

    • DOCSIS

    • xDSL

    • WiMAX

    • _3GPP2

    • _3GPP-EPS

    • Non-3GPP-EPS

  • rATType. Enumerated. Optional. Identifies the Radio Access Technology (RAT) that is servicing the user equipment. The RAT type is specified as one of the following:

    • WLAN

    • VIRTUAL

    • UTRAN

    • GERAN

    • GAN

    • HSPA_EVOLUTION

    • EUTRAN

    • CDMA2000_1X

    • HRPD

    • UMB

    • EHRPD

  • flows: Complex. Indicates IP flows using their flow identifiers.

    See "flows" for details on each of the flows parameters.

  • abortCause. Enumerated. Optional. Determines the cause of an Abort Session Request (ASR) or of a Resource Access Restriction (RAR) indicating a bearer release. The abort cause is specified as one of the following:

    • BEARER_RELEASED

    • INSUFFICIENT_SERVER_RESOURCES

    • INSUFFICIENT_BEARER_RESOURCES

    • PS_TO_CS_HANDOVER

    • SPONSORED_DATA_CONNECTIVITY_DISALLOWED

  • sponsoredConnectivityData: Complex. Optional. A set of AVPs that define which template parameters will be replaced and what the replacement values will be.

    See "sponsoredConnectivityData" for details on each of the sponsoredConnectivityData parameters.

Request Example

Example 16-17 shows an example of a QoS Event Notification request body.

Example 16-17 Notify QoS Event Request Body

{
  "notifyQoSEvent": {
    "correlator": "987654321",
    "eventType": 6,
    "accessNetworkChargingAddress": "127.0.0.1",
    "iPCANType": "WiMAX",
    "rATType": "WLAN"
  }
}

Response header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".

Response Body

There is no response body.

List QoS Event Notifications

The List QoS Event Notifications operation returns a list of QoS events that are registered either to a single correlator, if a correlator is specified in the request, or a complete list of registered events for all correlators if no correlator is specified.

Authorization

Basic or OAuth 2.0

HTTP Method

GET

URI

http://host:port/ApplicationQoSNotification/registration/[${correlator}]

where:

  • host and port are the host name and port of the system on which Services Gatekeeper is installed.

  • correlator is the optional unique identifier of the original notification request.

Request Header

Standard request headers.

Request Body

There is no request body.

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".

Response Body with No Correlator

The response body for the List QoS Event Notifications operation when an optional correlator parameter is specified, returns the following parameters:

  • correlators. Array. An array of correlators that are registered to receive QoS events.

Response Body Example

Example 16-18 shows an example of a List QoS Notifications response body when no correlator is specified in the request.

Example 16-18 List QoS Notifications Response Body Without a Correlator

{
  "correlators": {
    "correlator": [
      "987654321", "12345676", "1272638"
    ]
  }
}

Response Body with Optional Correlator

The response body for the List QoS Event operation when an optional correlator parameter is specified, returns the following parameters:

  • reference: Complex. Defines the application endpoint, interfaceName and correlator used to notify the application. See "reference" for detailed information on the reference parameters.

  • endUserIdentities: Array. Network end users to be monitored for events. An array of one or more end user IDs.

  • eventCriteria: Array. One or more events to be monitored. Events are specified by their numeric event ID. Table 16-3 shows the mapping of numeric event IDs to logical event IDs. Table 16-2 lists these event IDs.

    Table 16-4 Numeric to Logical QoS Event Mapping

    Numeric Event Logical Event Name

    1

    CHARGING_CORRELATION_EXCHANGE

    2

    INDICATION_OF_LOSS_OF_BEARER

    3

    INDICATION_OF_RECOVERY_OF_BEARER

    4

    INDICATION_OF_RELEASE_OF_BEARER

    6

    IP-CAN_CHANGE

    7

    INDICATION_OF_OUT_OF_CREDIT

    8

    INDICATION_OF_SUCCESSFUL_RESOURCES_ALLOCATION

    9

    INDICATION_OF_FAILED_RESOURCES_ALLOCATION

    10

    INDICATION_OF_LIMITED_PCC_DEPLOYMENT

    11

    USAGE_REPORT

    12

    QOS_FEATURE_RELEASED

reference

These are the parameters for the reference parameter.

  • endpoint: String. The notification end point expected by the AF.

  • interfaceName: String. The interface name. Rarely used.

  • correlator: String. A unique ID for the message.

Response Body Example

Example 16-19 shows an example of a List QoS Notifications response body when a correlator is specified in the request.

Example 16-19 List QoS Notifications Response Body with Correlator

{
  "startQoSNotification": {
    "reference": {
      "endpoint": "http://endpt_host:port/jaxrs/QoSNotification",
      "correlator": "987654321"
    },
    "endUserIdentities": [
      "tel:88888888"
    ],
    "eventCriteria": [
      "6", "7", "1", "2"
    ]
  }
}