This feature performs a list of predefined HTTP PUT operations to update subscriber data in an XCAP server.

Feature Cheat Sheet

B2BUA Instance SAS Support Originating / Terminating Point(s) in Session Plan Network Operator Data Subscriber Data Stateful or Stateless POJO Feature or SBB Feature Other notes

MMTel

Yes

Originating

  • SipAccess_SubscriberCheck in XCAP_User_Data session plan.

Yes

Updated

Stateless

POJO

Will only run if indicated by Vertical Service Code feature

Prerequisite Features

Configuration

Feature configuration defines the XCAP server and document, and success and failure responses. It is common to all update actions.

Action configuration maps the named actions to details of which part of the XCAP document is to be updated and with what value.

Feature Configuration

The profiles within the XcapDataUpdateConfigProfileTable are selected using the SentinelSelectionKey and have the following fields:

Parameter Type Description 
xcapServer
 
String

XCAP server to send HTTP requests to

 
xcapServerPort
 
int

XCAP server port, a value of 0 will use the default port

 
xcapServerPath
 
String

Path of the XCAP server application e.g. /rem/sentinel/xcap

 
auid
 
String

Application Unique ID e.g. simservs.ngn.etsi.org

 
Document
 
String

XCAP Document to update, e.g. simservs.xml

 
successResponseStatusCode
 
int

SIP Response status code to use following a successful HTTP response. Because the SIP session is ended using this code, it should be a SIP error response (300+)

 
failureResponseStatusCode
 
int

SIP Response status code to use following a failure HTTP response

 
failureAnnouncementID
 
int

Announcement ID to play on document update failure. Use 0 to not play an announcement if the update fails

 
useHttps
 
boolean

Whether to use HTTPS

Action Configuration

The profiles within the XcapDataUpdateActionConfigProfileTable are selected using the SentinelSelectionKey and action name and have the following fields:

Parameter Type Description 
actionName
 
String

Name of the action

 
documentPath
 
String

An XCAP Node Selector (subset of XPath) expression to select the element or attribute to update

 
XMLNS
 
String

XCAP definitions for any XML namespaces used in documentPath e.g. xmlns(cp=urn:ietf:params:xml:ns:common-policy). Empty if no namespaces are used

 
isElement
 
boolean

Whether the field to update is an element. If false it is treated as an attribute.

 
elementName
 
String

The name of the field to update if it is an element

 
useDialledDigitsAsParameter
 
boolean

Whether the dialled digits should be used as the new value of the XCAP Node

 
parameter
 
String

The new value of the XCAP Node when not using dialled digits

If isElement is true it is expected the documentPath node selector will select an element whose name is elementName.

if isElement is true and useDialledDigitsAsParameter is false, it is expected that parameter will be serialised replacement content of the selected element.

if isElement is false and useDialledDigitsAsParameter is false, it is expected that parameter will be a serialised attribute value and the documentPath node selector will select an element’s attribute.

Session Input Variables

Session State variable name Type Comments 
SentinelSelectionKey

SentinelSelectionKey

Determines which configuration to use.

 
XcapDataUpdateActionsQueueAsString

String

A comma separated list of Actions to be performed (spaces not ignored)

 
DialledSuffix

String

Can be used as the replacement value in the xcap update request

 
Subscriber

String

Used as the XUI to identify the user in the XCAP server.

Session Variables

These fields are used internally to maintain state while each XCAP request is in progress.

Session State variable name Type Comments 
XcapDataUpdateActionsQueue

List<String>

Remaining actions to perform after the current one

 
XcapDataUpdateActionInProgress

String

The action currently in progress

 
XcapDataUpdateAci

ActivityContextInterface

The activity context associated with the current HTTP request

 
XcapDataUpdateNormalizedDialledSuffix

String

Cached normalized version of DialledSuffix

Session Output Variables

Session State variable name Type Comments 
EndSessionAfterAnnouncement

int

SuccessResponseStatusCode of the feature config, when there is an announcement scheduled and all XCAP updates succeed. FailureResponseStatusCode of the feature config when a FailureAnnouncementID is configured and an XCAP update fails. Unchanged otherwise.

 
EarlyMediaAnnouncementInfoQueue

List<SipAnnouncementInformation>

Unmodified when all XCAP updates succeed.

When an XCAP update fails

  • if FailureAnnouncementID is not 0 in the feature config, this field is set to only contain that announcement

  • otherwise, this field is cleared.

Statistics

XcapDataUpdate statistics are tracked by the sentinel.volte.sip SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.volte.sip service → sentinel.volte.sip SBB → feature → XcapDataUpdate
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.volte.sip,vendor=OpenCloud,version=2.9.0].SbbID[name=sentinel.volte.sip,vendor=OpenCloud,version=2.9.0].feature.XcapDataUpdate"

Statistic Incremented when…​ 
Started

the feature runs

 
FailedToStart

Sentinel VoLTE encounters an error while attempting to start the feature

 
IssuedWarning

a non-fatal problem is encountered and the feature and issues a warning

 
FailedDuringExecution

a fatal problem is encountered and the feature cannot execute correctly

 
TimedOut

the feature takes too long to complete and Sentinel VoLTE aborts execution

 
SentXcapUpdate

the feature sends an XCAP request

 
ReceivedXcapUpdateSuccess

the features receives a success response to an XCAP update request

 
ReceivedXcapUpdateFailure

the feature receives a failure response to an XCAP update request

Behaviour

The feature assumes that any appropriate announcements to indicate successful update of subscriber data have already been enqueued by Vertical-Service-Code feature.

The feature extracts the action names from XcapDataUpdateActionsQueueAsString.

For each action name sequentially

  • The feature sends an XCAP request for the action and waits for a response. See [Sending an XCAP request]

  • If a failure response is received

    • no further actions are processed

    • the announcement queue is cleared

    • if a FailureAnnouncementID is configured, that announcement is queued and the SIP session is ended with FailureResponseStatusCode after the announcement plays

    • otherwise the SIP session is ended with FailureResponseStatusCode immediately.

If all actions succeed…​

  • if there are queued announcements the session state field EndSessionAfterAnnouncement is set to the value of SuccessResponseStatusCode

  • otherwise the SIP session is ended immediately using SuccessResponseStatusCode

Sending an XCAP Request

The action name is used to read the appropriate action profile. If the profile cannot be found, the feature fails to execute with Invalid Configuration cause.

The URL for the request is generated from feature configuration, the action profile and the session state as follows:

  • The URL’s protocol is set according to the feature config’s UseHttps value.

  • The URL’s host and port are set from the feature config’s XCAPServer and XCAPServerPort values.

  • The URL’s path is set to contain the following segments

    • The config’s XCAPServerPath value

    • The config’s AUID value

    • The constant value users

    • The session state’s Subscriber value percent encoded

    • The config’s Document value percent encoded

    • If the action’s DocumentPath is set,

      • the action’s DocumentPath value percent encoded and prefixed with ~~

  • The URL’s query is set to the action’s XMLNS value if present

Additional headers are set:

  • X-3GPP-Asserted-Identity is set to the value of session state’s Subscriber field

  • If the action’s IsElement is true Content-Type is set to application/xcap-el+xml

  • otherwise Content-Type is set to application/xcap-att+xml

The request body is generated:

  • if action’s IsElement is true the body is a serialized XML element.

    • The element name is the action’s ElementName value.

    • The element has no attributes.

    • If the action’s UseDialledDigitsAsParameter is true the content of the element is a tel: URI of the normalized value of the session state field DialledSuffix

    • Otherwise the content of the element is the action’s Parameter value.

  • Otherwise

    • If the action’s UseDialledDigitsAsParameter is true the body is the normalized value of the session state field DialledSuffix.

    • Otherwise the body is the action’s Parameter value.

The request including those headers and that body is sent to that URL.

Session state is updated so that the HTTP response can handled.

Previous page Next page
Sentinel VoLTE Version 2.9.0