29 About the Supported SOAP Parlay X 4.0 Facades

This chapter describes the Oracle Communications Services Gatekeeper interfaces in the supported Parlay X 4.0 facades and contains information specific to Services Gatekeeper not found in the specifications. For detailed descriptions of the interfaces, methods, and parameters, refer to the specifications, see the ETSI OSA Parlay X 4.0 specifications at:

http://www.3gpp.org/DynaReport/29199-01.htm

Parlay X 4.0 Part 17 Application-Driven QoS

The application driven QoS communication service interfaces follow.ETSI ES 202 504-17 V1.1.1 (2008-05) Open Service Access (OSA); Parlay X Web services; Part 17: Application-driven Quality of Service (QoS); Parlay X 3.

See the specification at the ETSI website:

http://www.etsi.org/deliver/etsi_es/202500_202599/20250417/01.01.01_60/es_20250417v010101p.pdf

See the discussion on Parlay X 4.0 application-driven quality of service (QoS) in Services Gatekeeper Communication Service Reference Guide for details on the supported operations.

There are two interfaces available for this specification:

Interface: Application-driven QoS
Interface: ApplicationQoSNotificationManager

Interface: Application-driven QoS

The Application-driven Quality of Service interface endpoint is:

http://host:port/parlayx40/qos/ApplicationQoS

Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.

These operations are available to applications to manage QoS requests. These operations are also available from the Platform Test Environment (PTE) graphical user interface:

applyQoSFeature
getQoSHistory
getQoSStatus
modifyQoSFeature
notifyQoSEvent
removeQoSFeature

applyQoSFeature

Applications use this operation to apply the connection settings in a temporary QoS feature profile to a subscriber connection.

Table 29-1 lists the applyQoSFeature request parameters.

Table 29-1 applyQoSFeature Request Parameters

Name	Data Type/Values	Mandatory?	Description
endUserIdentifier	xsd:anyURI	Yes	Identifies the network subscriber for which to apply the QoS feature profile for. Uses the standard URI format: tel:[0-9]
qoSFeatureIdentifier	xsd:string	Yes	The name of the QoS feature profile to apply to the subscriber connection. The QoS feature profile must exist before use, so use the Operation: loadQoSRequestTemplate MBean operation to create it first.
defaultQoSFeature	xsd:boolean	Yes	Always set to false.
modifyExistingSession	xsd:boolean	No	Always set to false.
qosFeatureProperties	QoSFeatureProperties	No	Specifies values for the configurable service attributes that apply to the temporary QoS feature profile.
qosFeatureProperties.Duration	common:TimeMetri	No	The duration of the QoS feature profile being applied. Supported units of measurement are Second, Minute, Hour, Day, Week, Month, Year. A 0 or negative value extends the duration for the entire session.
qosFeatureProperties.UpStreamSpeedRate	xsd:string	No	The upload speed rate of the QoS feature profile. The format is [0-9]bps\|Kbps\|Mbps\|Gbps\|Tbps. The maximum value is 4294967295bps.
qosFeatureProperties.DownStreamSpeedRate	xsd:string	No	The download speed rate of the QoS feature profile. The format is [0-9]bps\|Kbps\|Mbps\|Gbps\|Tbps. The maximum value is 4294967295bps..
qosFeatureProperties.OtherProperties	Property[0..unbounded	No	The attribute-value pairs that replace the default values defined in QoS feature profile. For example, you can define an application identifier variable in the QoS feature profile: <applicationIdentifier parameterName="$APP_ID">test_appId</applicationIdentifier> And then specify a value for the variable by setting applicationIdentifier to app_id: "$APP_ID=app_id"

Request Example

This example shows a request that attempts to apply a QoS feature profile named pxt to the tel:555012 subscriber, for a duration of 7200 seconds (120 minutes, or 2 hours). The upload rate is 1000 Mbps and the download rate is 1000 Kbps:

<S:Body>      <ns2:applyQoSFeature
          xmlns:ns2="http://www.csapi.org/schema/parlayx/adq/v4_0/local"
          xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v4_0">
          <ns2:endUserIdentifier>tel:555012</ns2:endUserIdentifier>
          <ns2:qoSFeatureIdentifier>pxt</ns2:qoSFeatureIdentifier>
          <ns2:defaultQoSFeature>false</ns2:defaultQoSFeature>
          <ns2:modifyExistingSession>false</ns2:modifyExistingSession>
          <ns2:qosFeatureProperties>
          <duration>
               <metric>Second</metric>
               <units>7200</units>
          </duration>
          <upStreamSpeedRate>1000 Mbps</upStreamSpeedRate>
          <downStreamSpeedRate>1000 kbps</downStreamSpeedRate>
          </ns2:qosFeatureProperties>
     </ns2:applyQoSFeature>
 </S:Body>

Response Parameters

Table 29-3 lists the applyQoSFeature response parameters.

Table 29-2 applyQoSFeature Response Parameters

Name	Data Type	Mandatory?	Description
result	QoSFeatureData	Yes	Details of the actions taken as a result of the QoS feature profile request.
result.requestID	XSD:string	Yes	A unique request identifier generated by this communication service and used by the application to identify this specific invocation of the applyQoSFeature operation.
result.qoSFeatureIdentifier	XSD:string	Yes	A name that uniquely identifies the QoS feature profile being applied temporarily to the subscriber's connection.
actualProperties	QoSFeatureProperties	No	The AVPs returned by the PCRF.

Response Example

This example shows a response to an applyQoSFeature request. It identifies the pxt feature profile that the QoS applies to, and Diameter Rx session details.

<env:Body>
     <loc:applyQoSFeatureResponse
     xmlns:loc="http://www.csapi.org/schema/parlayx/adq/v4_0/local">
     <loc:result>
          <requestId>localhost;1385973500;0-1386001353054</requestId>
          <qoSFeatureIdentifier>pxt</qoSFeatureIdentifier>
          <actualProperties>
               <duration>
                    <metric>Second</metric>
                    <units>6000</units>
               </duration>
                    <upStreamSpeedRate>1000000000bps</upStreamSpeedRate>
                    <downStreamSpeedRate>1000000bps</downStreamSpeedRate>
                    <otherProperties>
                         <name>supportedFeatures[0].vendorId</name>
                         <value>10415</value>
                    </otherProperties>
                    <otherProperties>
                         <name>supportedFeatures[0].featureListID</name>
                         <value>1</value>
                    </otherProperties>
                    <otherProperties>
                         <name>ratType</name>
                         <value>WLAN</value>
                    </otherProperties>
                    <otherProperties>
                         <name>ipcanType</name>
                         <value>_3GPP-GPRS</value>
                    </otherProperties>
                    <otherProperties>
                         <name>supportedFeatures[0].featureList</name>
                         <value>2</value>
                    </otherProperties>
               </actualProperties>
          </loc:result>
     </loc:applyQoSFeatureResponse>
</env:Body>

getQoSHistory

Applications use this operation to return a list of the QoS transactions (feature profile requests and responses) for a subscriber. You can filter the list by specifying:

A QoS feature profile identifier
A maximum number of transactions
A date and time limit
Additional custom criteria that you create

After a request/response, there is approximately a 20-second delay before its record is available to getQoSHistory. To avoid filling up the database, request/response records are maintained for a period of 30 days and then deleted.

Request Parameters

Table 29-3 lists the getQoSHistory request parameters.

Table 29-3 getQoSHistory Request Parameters

Name	Data Type	Mandatory?	Description
endUserIdentifier	XSD:anyURI	Yes	Identifies the subscriber for which to get a history. Uses the standard URI format.
qosFeatureIdentifier	XSD:string	No	The name of the QoS feature profile this operation returns a history for. If not specified, a history is returned for all feature profiles for this subscriber.
date	XSD:datTime	No	Limits the history returned to the date and time specified. If not specified, a history is returned for this subscriber for the previous minute only.
maxEntries	XSD:Integer	No	Specifies the maximum number of QoS feature profile requests and responses to return. If not specified (or a value of 0 is specified) the maximum is set to 10. The largest value allowed is 100.
additionalCriteria	Property[0..unbounded]	No	Not implemented in this release.

Request Example

This example shows a request for a QoS feature profile history of requests and responses for the subscriber tel:555012, for the pxt feature, that transpired on December 12th, 2013 at 01:33:53.

 <S:Body>
     <ns2:getQoSHistory
          xmlns:ns2="http://www.csapi.org/schema/parlayx/adq/v4_0/local"
          xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v4_0">
          <ns2:endUserIdentifier>tel:555012</ns2:endUserIdentifier>
          <ns2:qoSFeatureIdentifier>pxt</ns2:qoSFeatureIdentifier>
          <ns2:date>2013-12-05T01:33:53Z</ns2:date>
          <ns2:maxEntries>10</ns2:maxEntries>
     </ns2:getQoSHistory>
</S:Body>

Response Parameters

Table 29-4 lists the getQoSHistory response parameters.

Table 29-4 getQoSHistory Response Parameters

Name	Data Type	Mandatory?	Description
transactionDateTime	XSD:dateTime	Yes	Specifies the transaction time.
transactionDetails	XSD:string	Yes	Specifies the request/response details. The details name the portion of the name/value pairs separated by the # symbol. The name portion of the name/value pairs include: startTime endTime requstId duration featureName A list of request/response records, including the transaction time and a list of the modified variables.

Name

Data Type

Mandatory?

Description

transactionDateTime

XSD:dateTime

Yes

Specifies the transaction time.

transactionDetails

XSD:string

Yes

Specifies the request/response details.

The details name the portion of the name/value pairs separated by the # symbol. The name portion of the name/value pairs include:

startTime
endTime
requstId
duration
featureName
A list of request/response records, including the transaction time and a list of the modified variables.

Response Example

This example shows an example of a history returned to the application:

<env:Body>
     <loc:getQoSHistoryResponse
          xmlns:loc="http://www.csapi.org/schema/parlayx/adq/v4_0/local">
          <loc:result>
            <transactionDateTime>2013-12-05T09:33:53.522+08:00</transactionDateTime>
 <transactionDetails>requestId=localhost;1386206978;0-1386207233485#duration=7200
seconds#endTime=2013-12-05 09:53:42#featureName=pxt#modification:time=
1386207684611#duration=9600seconds#$FLOW_DESCRIPTION_0=permit out ip from any to 
any#</transactionDetails>
     </loc:result>
     </loc:getQoSHistoryResponse>
</env:Body>

getQoSStatus

Applications use this operation to retrieve the status and details of a subscriber's current QoS feature profile.

Request Parameters

Table 29-5 lists the getQoSStatus request parameters.

Table 29-5 getQoSStatus Request Parameters

Name	Data Type	Mandatory?	Description
endUserIdentifier	XSD:any URI	Yes	Identifies a subscriber to obtain QoS details for.

Request Example

This example requests QoS details for subscriber tel:555012.

<S:Body>
     <ns2:getQoSStatus xmlns:ns2="http://www.csapi.org/schema/parlayx/adq/v4_0/local"
          xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v4_0">
          <ns2:endUserIdentifier>tel:555012</ns2:endUserIdentifier>
     </ns2:getQoSStatus>
</S:Body>

Response Parameters

Table 29-6 lists the getQoSStatus response parameters.

Table 29-6 getQosStatus Response Parameters

Name	Data Type	Mandatory?	Description
result	QosStatus	Yes	Returns the status of a subscriber connection, including information about the temporary QoS feature profile details that are currently activated.
result.userIsConnected	XSD:Boolean	Yes	Specifies whether the subscriber account is currently connected (true or false).
result.defaultQoSFeatureIdentifier	XSD:string	No	Not used because setting a default QoS feature profile is not supported.
trafficClasses	TrafficClass[0..unbounded]	No	Not used because setting a default QoS feature profile is not supported.
qosFeatureStatuses	QoSFeatureData[0..unbounded]	No	An array of the QoS feature profile details for the subscriber.

Response Example

This example shows the QoS status details returned for a subscriber:

<env:Body>
     <loc:getQoSStatusResponse
          xmlns:loc="http://www.csapi.org/schema/parlayx/adq/v4_0/local">
          <loc:result>
               <userIsConnected>true</userIsConnected>
               <qosFeatureStatuses>
                    <requestId>localhost;1386206978;0-1386207233485</requestId>
                    <qoSFeatureIdentifier>pxt</qoSFeatureIdentifier>
                    <actualProperties>
                         <duration>
                              <metric>Second</metric>
                              <units>9600</units>
                         </duration>
                         <upStreamSpeedRate>1000000000bps</upStreamSpeedRate>
                         <downStreamSpeedRate>1000000bps</downStreamSpeedRate>
                         <otherProperties>
                              <name>supportedFeatures[0].vendorId</name>
                              <value>10415</value>
                         <otherProperties>
                         <otherProperties>
                              <name>supportedFeatures[0].featureListID</name>
                              <value>1</value>
                         </otherProperties>
                         <otherProperties>
                              <name>ratType</name>
                              <value>WLAN</value>
                         </otherProperties>
                         <otherProperties>
                              <name>ipcanType</name>
                              <value>_3GPP-GPRS</value>
                         </otherProperties>
                         <otherProperties>
                              <name>supportedFeatures[0].featureList</name>
                              <value>2</value>
                         </otherProperties>
                    </actualProperties>
               </qosFeatureStatuses>
          </loc:result>
</loc:getQoSStatusResponse>
</env:Body>

modifyQoSFeature

Applications use this operation to alter a QoS feature profile that has already been applied using "applyQoSFeature". Specify the attributes you want to change in the QoS feature profile. Any other attributes remain as originally set. Remember that the new values only take effect for the time limit set by the qosFeatureProperties.Duration attribute of "applyQoSFeature"

This operation must take place inside an active application session, and you must send in the request ID generated by applyQosFeature.

Request Parameters

Table 29-7 lists the modifyQoSFeature request parameters:

Table 29-7 modifyQoSFeature Request Parameters

Name	Data Type	Mandatory?	Description
requestID	XSD:string	Yes	Specifies the unique request identifier generated by this communication service from the original "applyQoSFeature" operation.
requestProperties	QoSFeatureProperties	Yes	Specifies new values of the attributes of the QoS feature profile.

Request Example

This example shows a request that modifies the QoS feature profile identified as localhost;1386206978;0-1386207233485. It changes the values of the upStreamSpeedRate, downStreamSpeedRate, and flow description attributes.

<S:Body>
     <ns2:modifyQoSFeature
          xmlns:ns2="http://www.csapi.org/schema/parlayx/adq/v4_0/local"
          xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v4_0">
          <ns2:requestId>localhost;1386206978;0-1386207233485</ns2:requestId>
          <ns2:requestProperties>
               <duration>
                    <metric>Second</metric>
                    <units>9600</units>
               </duration>
               <upStreamSpeedRate>1000 Mbps</upStreamSpeedRate>
               <downStreamSpeedRate>1000 kbps</downStreamSpeedRate>
               <otherProperties>
                    <name>$FLOW_DESCRIPTION_0</name>
                    <value>permit out ip from any to any</value>
                    <description></description>
               </otherProperties>
          </ns2:requestProperties>
     </ns2:modifyQoSFeature>
</S:Body>

Response Parameters

Table 29-8 lists the modifyQoSFeature response parameters.

Table 29-8 modifyQoSFeature Response Parameters

Name	Data Type	Mandatory?	Description
result	QoSFeatureProperties	Yes	Specifies the attributes that have been modified and their values.

Response Example

This example shows the attributes changed by modifyQoSFeature. The modified attributes are returned in the result array.

<env:Body>
          <loc:modifyQoSFeatureResponse
               xmlns:loc="http://www.csapi.org/schema/parlayx/adq/v4_0/local">
               <loc:result>
                    <duration>
                         <metric>Second</metric>
                         <units>9600</units>
                    </duration>
                    <upStreamSpeedRate>1000 Mbps</upStreamSpeedRate>
                    <downStreamSpeedRate>1000 kbps</downStreamSpeedRate>
                    <otherProperties>
                         <name>$FLOW_DESCRIPTION_0</name>
                         <value>permit out ip from any to any</value>
                         <description></description>
                    </otherProperties>
              </loc:result>
          </loc:modifyQoSFeatureResponse>
</env:Body>

notifyQoSEvent

Your PCRF uses this operation to report certain network events that occurred against one or more subscriber's active QoS features profiles.

Request Parameters

Table 29-9 lists the notifyQoSEvent request parameters.

Table 29-9 notifyQoSEvent Request Parameters

Name	Data Type	Mandatory?	Description
correlator	xsd:string	yes	The correlator identifying the original notification registration.
endUserIdentities	xsd:anyURI[1..unbounded]	Yes	The network subscribers associated with the event.
eventType	QoSEvent	Yes	The event being reported.

Response Parameters

There are no response parameters.

removeQoSFeature

Applications use this operation to remove an active temporary QoS feature profile, and return the QoS values to the state they were in before the temporary QoS feature profile was applied.

This operation must take place inside an active session.

Request Parameters

Table 29-10 lists the removeQoSFeature request parameters.

Table 29-10 removeQoSFeature Request Parameters

Name	Data Type	Mandatory?	Description
requestID	XSD:String	Yes	Contains the unique request ID generated by the original applyQoSFeature call.

Request Example

This example shows a removeQoSFeature request that removes the temporary QoS feature profile identified as localhost;1386206978;0-1386207233485:

<S:Body>
     <ns2:removeQoSFeature
          xmlns:ns2="http://www.csapi.org/schema/parlayx/adq/v4_0/local"
          xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v4_0">
          <ns2:requestId>localhost;1386206978;0-1386207233485</ns2:requestId>
     </ns2:removeQoSFeature>
</S:Body>

Response Parameters

Table 29-11 lists the removeQoSFeature response parameters.

Table 29-11 removeQoSFeature Response Parameters

Name	Data Type	Mandatory?	Description
result	XSD:boolean	Yes	Returns true if the QoS feature profile was successfully removed.

Response Example

This example shows a response to a request to remove a temporary QoS feature profile in which the removal was successful:

<env:Body>
     <loc:removeQoSFeatureResponse
          xmlns:loc="http://www.csapi.org/schema/parlayx/adq/v4_0/local">
          <loc:result>true</loc:result>
     </loc:removeQoSFeatureResponse>
</env:Body>

Interface: ApplicationQoSNotificationManager

The Application-driven Quality of Service interface endpoint is:

http://host:port/parlayx40/qos/ApplicationQoSNotificationManager

Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.

These operations are available to applications to manage start and stop QoS notification. These operations are also available from the Platform Test Environment (PTE) graphical user interface:

startQoSNotification
stopQoSNotification

startQoSNotification

Applications use this operation to register interest in receiving notifications of specific event types for a subscriber.

Request Parameters

Table 29-12 lists the startQoSNotification request parameters.

Table 29-12 startQoSNotification Reqeust Parameters

Name	Data Type	Mandatory?	Description
reference	common:SimpleReference	Yes	The application end point to receive event notifications.
reference.Endpoint	xsd:anyURI	Yes	The end point address.
reference.InterfaceName	xsd:string	Yes	The interface name.
reference.Correlator	xsd:string	Yes	Correlation information.
endUserIdentities	xsd:anyURI[1..unbounded]	Yes	The subscriber for which to monitor events.
eventCriteria	QoSEvent[1..unbounded]	Yes	The events to be monitored.

Table 29-13 lists the event definitions that you use for the events request parameter to startQoSNotifiation.

Table 29-13 startQoSNotification event Definitions

Event Name	Description	Trigger Condition
AbnormalConnectionTermination	The subscriber connections were terminated abnormally by a network fault that released all temporary QoS feature profile requests.	This communication service can not detect this kind of event, so you must use this event definition for all abnormal terminations.
NormalConnectionTermination	The subscriber connections were terminated normally (for example, the subscriber logged off), which automatically released all of the temporary QoS feature profile requests.	This event is triggered by a Diameter Rx abort session request (ASR) message.
TemporaryQoSFeatureReleased	An active temporary QoS feature profile request on a subscriber connection was released, because it reached a threshold specified by one of the service attributes.	This event is triggered by this communication service when a QoS feature profile duration expires.

Request Example

This example shows an application requesting notifications for the subscriber tel:555012 for both normal network connection terminations and temporary QoS feature profiles released.

<S:Body>
     <ns2:startQoSNotification
          xmlns:ns2="http://www.csapi.org/schema/parlayx/adq/notification_manager/v4_0/local"
          xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v4_0">
          <ns2:reference>
             <endpoint>http://endpoint_host.port/jaxws/QoSNotification</endpoint>
             <interfaceName>interfaceName</interfaceName>
             <correlator>987654321</correlator>
          </ns2:reference>
          <ns2:endUserIdentities>tel:555012</ns2:endUserIdentities>
          <ns2:eventCriteria>NormalConnectionTermination</ns2:eventCriteria>
          <ns2:eventCriteria>TemporaryQoSFeatureReleased</ns2:eventCriteria>
     </ns2:startQoSNotification>
</S:Body>

Response Parameters

There are no response parameters because the connections have been terminated.

stopQoSNotification

Applications use this operation to cancel notification registrations started by startQoSNotification.

Request Parameters

Table 29-14 lists the stopQoSNotification request parameters.

Table 29-14 stopQoSNotification Request Parameter

Name	Data Type	Mandatory?	Description
correlator	XSD:string	Yes	The correlator identifying the original notification registration.

Response Parameters

There are no response parameters.