This guide explains how to configure and provision the Sentinel framework.

Topics

  • Getting Started — describes how to get a Sentinel Express installation up and running

  • Configuring Sentinel Services — describes the configuration options for each of the Sentinel services

  • Sentinel Components — a comprehensive description of each Sentinel component

  • Provisioning — describes how to provision Sentinel using the Sentinel Element Manager

  • Sentinel Alarms — describes the alarms raised by Sentinel

  • Charging Information — describes the format and content of CDRs, and of AVPs present in the Diameter Ro interface

For more information

Getting Started

This section explains how to set up a standalone version Sentinel Express on a Rhino SDK.

In this section…​

Preparing to Install Sentinel Express

Before you install Sentinel Express, you need to download the SDK package, and get other required software.

You can then either:

  • let the built-in installer install both the Rhino SDK and Sentinel Express, or

  • install and configure Rhino and the JVM manually, then use the installer to install Sentinel Express into your Rhino.

In both cases you need to get a license.

Allowing the installer to install both the Rhino SDK and Sentinel Express software is recommended for functional testing or experimentation with Sentinel Express. For production installs and/or load testing it is recommended to manually install and configure Rhino and the JVM.

Finally, if you are planning to install Sentinel Express on an existing OpenCloud Rhino installation, it makes sense to refer to other OpenCloud product dependencies

Download the Sentinel Express SDK package

To get the latest Sentinel Express SDK package contact your support agent for details on downloading.

The SDK package contains an installer, that can install Sentinel Express as an out-of-the-box system. It is also an SDK allowing customisation of the product.

Get required software

You’ll need the following software to run Sentinel Express:

Software Download Link Documentation Link

Java 11

Refer to Rhino Compatibility Guide

Apache Tomcat 9.0.x

Tomcat 9.0.x Download Page

Tomcat 9.0.x Documentation

Rhino 3.2.0 or later - optional - to be used when installing and configuring Rhino manually

Included with the sdk.zip in ./repositories/opencloud-offline-mirror/com.opencloud.rhino.rhino/rhino-package

Rhino Documentation

Rhino Element Manager 3.2.0 or later

REM Download Page

REM Documentation

Sentinel Express SDK including out of the box installer

Contact your support agent

Sentinel Express SDK

(Optional) Cassandra Database, version 2.1.17 or later version from the 2.1.x series

http://cassandra.apache.org/download/

http://wiki.apache.org/cassandra/GettingStarted

Install and configure Rhino and the JVM

Optionally you can install and configure Rhino and the JVM for use with Sentinel Express. This is recommended for production deployments, and clustered setups.

Alternatively for Proof of Concept and lab functional testing it is recommended to use the Installer documented in Installing Sentinel Express Services

Install Rhino

1

Start by choosing a location to extract the contents of the Rhino package.

We’ll refer to this directory as RHINO_HOME.

2

Rhino must be started at least once to generate the necessary configuration files. To start Rhino, in the RHINO_HOME directory, execute:

$ ./start-rhino.sh

(or start-rhino.bat on Microsoft Windows).

3

Wait until Rhino is ready. It prints the following message in its log when ready:

SLEE successfully started on node(s) [101]

4

Stop Rhino by executing in the RHINO_HOME directory:

$ ./stop-rhino.sh --nice
Tip For more about installing and configuring the Rhino TAS, please see the Rhino 3.2 Documentation.

Configure Rhino and the JVM

If you want to install Sentinel Express on top of an already running Rhino then this step must be performed. If you are letting the installer configure the Rhino SDK for you, this step can be skipped.

The following settings are needed:

Setting Configuration

Management database size

For a full Sentinel Express install, the default Rhino 3.2 management database size is insufficient and should be increased to at least 300MB. To do this, edit RHINO_HOME/config/rhino-config.xml on all nodes, increasing the <committed-size> in the following section:

    <memdb>
      <jndi-name>ManagementDatabase</jndi-name>
      <message-id>10003</message-id>
      <group-name>rhino-db</group-name>
      <committed-size>300M</committed-size>
      <stripe-count>1</stripe-count>
      ...
    </memdb>

JVM

You’ll also need to configure the JVM:

  • The Rhino HEAP_SIZE setting should be set to 2048m at a minimum.

  • The recommended MAX_NEW_SIZE and NEW_SIZE setting for a Rhino node running Sentinel Express is 1/4th of the total heap size (for example, 512m when the HEAP_SIZE is 2048m).

  • The MaxMetaspaceSize size should be increased from its default, to at least 384MB. To do this in Rhino 3.2, modify the flags -XX:MaxMetaspaceSize= and -XX:MetaspaceSize= in RHINO_HOME/config/jvm_args.

All of these settings can be found in RHINO_HOME/config/config_variables after running Rhino for the first time.

Socket permissions

You will need to add the host address where the installer is running to the mlet configuration file.

  • For RhinoSDK the configuration file is RHINO_HOME/config/mlet.conf

  • For Rhino Production the configuration file is RHINO_HOME/node-xxx/config/permachine-mlet.conf

  • In the configuration file look for the XML tag <security-permission-spec> and add the following entry, replacing <IP ADDRESS> with your installer’s IP address:

<mlets>
    <mlet enabled="true">
        <classpath>
            <jar-url>$${rhino.dir.base.url}/lib/jmxr-adaptor.jar</jar-url>
            <security-permission-spec>
                .... other entries

                permission java.net.SocketPermission "<IP ADDRESS>", "accept,resolve";

                .... other entries
            </security-permission-spec>
        </classpath>
    </mlet>
</mlets>
Important
Start Rhino to load the new configuration

To start Rhino, in the RHINO_HOME directory run start-rhino.sh (or start-rhino.bat on Microsoft Windows).

This applies the Rhino and JVM configuration.

Get a license

Warning To install Sentinel Express you need a license to run SIS, CGIN, and Sentinel Express from OpenCloud. In order to obtain a license file, please contact OpenCloud.

If you allow the installer to install both Rhino SDK and Sentinel Express for you, it will prompt you for the location of the license file.

If you prefer to set up Rhino manually, then you need to install the license file prior to installing Sentinel Express.

To install your license file:

1

Make sure Rhino is started and running.

2

Go to the RHINO_HOME/client/bin directory.

3

In this directory, start the Rhino Console with the rhino-console script (or rhino-console.bat in Microsoft Windows).

4

In the Rhino Console execute, this command:

installlicense [PATH_TO_LICENSE_FILE]

([PATH_TO_LICENSE_FILE] should be relative to the RHINO_HOME/client/bin directory.)

Ports

If using the standard configuration, the following ports need to be open on the Express TAS host’s firewall.

Port Purpose

5060

SIP traffic

5061

Secure SIP traffic

8080

REM GUI

1199-1203

RMI Access

If using other configuration the firewall should be configured for those non-standard ports. Other ports may be opened as needed. For example if ssh is used to administer a node, then port 22 would be opened

Metaswitch product dependencies

Sentinel Express is built on top of other Metaswitch products. For compatibility with Rhino and other Rhino products, please see the Rhino Compatibility Matrix.

The 4.1 series depends on the following series:

Product Series

Rhino

3.2.x

REM

3.2.x

SIP

3.1.x

CGIN

3.1.x

SIS

3.2.x

SIS-EM

3.2.x

Diameter

4.1.x

CDR-RA

3.1.x

HTTP-RA

3.1.x

DB-Query-RA

2.1.x

FSM Tool

2.1.x

CQL-RA

2.1.x

Installing Sentinel Express Services

Sentinel Express is installed through the use of an installer program.

The installer can run in interactive and non-interactive modes - suitable for manual and automated installs respectively. When running in interactive mode it will prompt you for various necessary settings and save them.

Tip The installer will offer to install the Rhino SDK for you, or allow you to specify an existing Rhino installation. Once either a new Rhino SDK install, or an existing installation is selected the installer will install Sentinel Express into your Rhino or Rhino SDK.

The installer prepares configures for a single node Sentinel Express system.

For more advanced configurations, such as clustering, or multiple signalling peers, it is recommended the you become familiar with the Rhino platform, SIS and Sentinel Express products.

To install Sentinel Express services in interactive mode:

  1. Unzip sentinel-express-sdk-VERSION.zip

  2. Run the installer

For further information on installation read:

1. Unzip sentinel-express-sdk.zip

To unzip sentinel-express-sdk.zip:

1

Copy the downloaded SDK zip file to a machine where Rhino and Sentinel Express will run.

Tip It’s easiest if you create a new directory in the home directory. 
user@machine$ mkdir ~/sentinel-express

2

Unzip.

user@machine$ cp ~/sentinel-express-sdk.zip ~/sentinel-express
user@machine$ cd ~/sentinel-express
user@machine$ unzip sentinel-express-sdk.zip

2. Run the installer

The install program is split into several "phases".

These are:

  • initialisation of the environment

  • question and answer (in interactive mode)

  • execution of installation

Tip the installer captures full logging from the various tools that it uses, and writes these logs into the sentinel-express-sdk/build/target/log directory.

To run the installer:

1

The installer command is in the build/bin directory of the extracted Sentinel Express SDK .

testuser@machine$ cd ~/sentinel-express/sentinel-express-sdk
testuser@machine$ ./build/bin/installer

The installer first initialises the environment. It typically shows output similar to the following

Initialising the SDK ...
Retrieving Installer dependencies ... done.

2

Question and answer to determine necessary settings

The installer will prompt the user for various values. A value inside square brackets, if present, is the default answer for that question. When the user presses the Enter key without entering any value the default is used if it is present. If the default isn’t present, the prompt will be repeated. In subsequent runs of the installer, the default will reflect the values that the user has previously entered.

Explanations of all of the questions the installer will ask are laid out over the next few steps. Note that some of the questions will only appear under certain circumstances, so not all of them will be seen in a given installer run.

3

Basic SDK Questions

Your organization's name, e.g. Rocket Communications Inc.
sdk.component.vendor [UNSET] >

This value will be used for the vendor portion of the SLEE Component ID for all SLEE components published by the SDK.

sdk.component.version [1.0] >

This value will be used for the version portion of the SLEE Component ID for all SLEE components published by the SDK.

The name of the platform operator, e.g. Rocket.
sdk.platform.operator.name [UNSET] >

The name of the platform operator for the system. It is used extensively throughout configuration profiles.

An Ivy organization field, recommended lower case with no whitespace e.g. "rocket".
sdk.ivy.org [UNSET] >

This value is used as the org value for all Ivy artifacts created by the SDK.

sdk.ivy.publish.revision [1.0.0] >

This value is used as the base of the revision value for all Ivy artifacts created by the SDK. When an artifact is actually published, additional letters and numbers will be appended to this number to identify specific releases, snapshots and milestones.

5

Install Rhino Questions

You can either have the installer set up a Rhino SDK for you or point it at an existing Rhino installation, SDK or production.
Note: If you want to use an existing Rhino installation it has to be running and a proper license has to be installed when finishing the installation after the configuration. Also make sure that you have adjusted the memory settings and created a tcapsim-gt-table.txt file as detailed in the documentation.
Set up a Rhino SDK installation automatically? y/[N] >

If you allow the installer to set up a new Rhino SDK installation, it will prompt for a license file.

Enter the path to your Rhino license file > /home/testuser/Downloads/opencloud.license

It then installs the Rhino SDK and starts it.

If you instruct the installer to use an existing Rhino, the installer will prompt for the path to the Rhino client directory.

Enter the path to your Rhino client directory > /home/testuser/rhino/{prd-majorversion-rhino}/client

If the associated installation is a Rhino production then additional information is required to complete configuration.

You can either have the installer deploy against Rhino SDK or production.
Does the specified client point to a production installation? y/[N] >

If you choose Yes, then the installer prompts for details of the cluster nodes and hosts.

Enter your Rhino node setup.
It has to be formatted like this: {nodeId,nodeId}host,{nodeId}host
Examples:
  {101}localhost
  {101,102}host1,{103}host2
Node setup [{101}localhost] > {101}hostname1,{102}hostname2

6

Review settings

Once all questions have been answered, the user is provided the opportunity to review and if happy, accept the settings. TIP: settings are saved to disk, so that they can be read later.

Review settings
***************


Basic SDK properties
====================

  sdk.component.vendor: Rocket Communications Inc
  sdk.component.version: 1.0
  sdk.platform.operator.name: Rocket
  sdk.ivy.org: rocket
  sdk.ivy.publish.revision: 1.0.0

... edited for brevity

Accept these values? [Y]/n > y

Updating file {sdk-path}/sdk.properties

Configuration changes written.

If the user presses the n key then the questions are asked again. Note that the list of configuration files that have been modified are printed out by the configuration portion.

7

Which product(s) to deploy

The user can choose which Sentinel products to deploy as part of the installation, any combination of Sentinel SIP, Sentinel SS7 and Sentinel Diameter can be specified.

This installer can be used to create deployment modules for one or more of the following Sentinel products: "diameter", "sip" and "ss7". Please enter the products you would like to deploy as a comma-separated list.
Which products do you want to deploy? [sip,ss7,diameter] >

For each option the user specifies, a deployment module will be created to deploy the specified product.

8

Sentinel SS7 with SIS

If Sentinel SS7 was one of the products selected for deployment, the user will be presented with an option to install Sentinel SS7 with SIS.

Do you want to install sentinel-ss7 with SIS? y/[N] >

If the user enters y then Sentinel Express will install and configure SIS for use with the Sentinel SS7 service.

9

Creation of a deployment module

The installer will now create the required deployment module(s). This may take several minutes.

10

Execution phase

Now that the installer has gathered all necessary information it provides the user with the option to install Sentinel Express immediately.

Install now? [Y]/n >

If the user wants to install at a later time, they can press the n key. The installer exits having saved settings that the user has entered. I.e. the installer can be run later if desired.

Installing Rhino ... done.
Starting Rhino in the background ... done.
Publishing deployment module deploy-sentinel-diameter ... done.
Publishing deployment module deploy-sentinel-sip ... done.
Publishing deployment module deploy-sentinel-ss7 ... done.

Creating deployment module deploy-sentinel ... done.
Publishing deployment module deploy-sentinel ... done.
Deploying; this is going to take a while ... done.
Binding; this is going to take a while ... done.
Configuring; this is going to take a while ... done.

Installation completed successfully in 8 minutes and 38 seconds. Rhino has been left running to finish applying configuration changes.

The installation has now completed successfully.
Important A properties file is automatically created when the interactive installer is run. This file is located in the sentinel-express-sdk directory and named install.properties. In this way an interactive installations settings are saved, and can be distributed through the install.properties file. You can later use this file for a new installation using the Non-interactive mode.

Non-interactive mode

To run the installer in non-interactive mode a properties file must be passed to the installer program.

testuser@machine$ cd ~/sentinel-express/sentinel-express-sdk
testuser@machine$ ./build/bin/installer -p my-install.properties

SIS and CGIN

During installation SIS and CGIN versions are extracted into the SDK directory structure. This is so that SIS can be configured as necessary.

The CGIN connectivity pack is extracted into the sentinel-express-sdk/cgin/cgin-connectivity-full-CGIN_VERSION directory. The SIS is extracted into the sentinel-express-sdk/sis/SIS_VERSION directory. Here CGIN_VERSION and SIS_VERSION are the release versions for each product respectively (e.g. 3.1.0 and 3.2.0)

The SIS console command is located at sentinel-express-sdk/sis/SIS_VERSION/admin/sis-console.

Background information

The installer sits on top of the Sentinel Express SDK infrastructure

The installer works by creating "deployment modules" for the products within Sentinel Express. These modules are named "deploy-sentinel", "deploy-sentinel-sip", "deploy-sentinel-ss7" and "deploy-sentinel-diameter". They are located in the root of the Sentinel Express SDK directory.

A deployment module can be created through the use of the sdkadm create-deployment-module command.

The deployment modules are then published, and the deployer, binder and configurer are invoked in order to install/bind/configure the application in Rhino.

This means that the the installer is part of the Sentinel Express SDK, and that there is no technology difference between the SDK and an "off the shelf install". Therefore custom configurations can easily be made through modifying the deployment modules, publishing them, and running the configurer.

Installer log files

The installer captures full logging from the various tools that it uses, and writes these logs into the sentinel-express-sdk/build/target/log directory. This output is more verbose than the user sees when running the installer.

Each time an install is done, a file called installer.log is created in this directory. If there is a previous installer.log file, it is moved to installer_[date].log. The value of [date] is the time of the last write timestamp in the file.

Therefore running the installer three times results in three installer log files.

Installing the Sentinel Express Provisioning Module

The Sentinel Express provisioning module is distributed as a Rhino Element Manager (REM) plugin.

It requires REM 3.2 or compatible. REM can be installed with Jetty or Apache Tomcat. For Sentinel Express, the Apache Tomcat method is required.

To install the Sentinel Express Provisioning module you will need:

  • the REM distribution package — rhino-element-manager-<version>.zip; expanded to a location of your choice

  • an Apache Tomcat installation — either downloaded and configured manually, or installed via a package manager. Use the latest release from the Tomcat 9.x series.

  • the Sentinel Express REM plugin — sentinel-express-element-manager-<version>.em.jar

    • included with the downloaded sdk.zip file inside the repositiories directory ./repositories/opencloud-offline-mirror/com.opencloud.rhino.sentinel-pack/sentinel-express-element-manager

Below are the procedures to:

Important
REM restart required

After installing and configuring the plugin, you will need to restart REM, for example by restarting the Tomcat webapp it is running in:

${CATALINA_BASE}/bin/catalina.sh stop
${CATALINA_BASE}/bin/catalina.sh start

Set up Tomcat

To set up Apache Tomcat for the Sentinel Express Provisioning module:

1

Follow the instructions for running REM on Apache Tomcat in the REM Guide.

2

Create the rem_home/plugins directory.

cd apache-tomcat-<version>
mkdir -p rem_home/plugins

Install the REM plugin

To install the REM plugin for the Sentinel Express Provisioning Module:

1

Copy sentinel-express-element-manager-<version>.em.jar into rem_home/plugins.

cd apache-tomcat-<version>
cp /full/path/to/sentinel-express-element-manager-<version>.em.jar rem_home/plugins/

2

(Optional) Copy sis-em-<version>.em.jar into rem_home/plugins.

cd apache-tomcat-<version>
cp /full/path/to/sis-em-<version>.em.jar rem_home/plugins/

Customize plugin logging

1

Unzip log4j2.properties from rem.war:

cd apache-tomcat-<version>
mkdir rem-tmp
cd rem-tmp
unzip ../webapps/rem.war WEB-INF/classes/log4j2.properties

2

Edit WEB-INF/classes/log4j2.properties with this content:

rootLogger.level=INFO
rootLogger.appenderRef.console.ref=CONSOLE
rootLogger.appenderRef.file.ref=FILE

appender.CONSOLE.type=Console
appender.CONSOLE.name=CONSOLE
appender.CONSOLE.layout.type=PatternLayout
appender.CONSOLE.layout.pattern=%d{ABSOLUTE} %-5p <%t> [%c] %m%n

appender.FILE.type=RollingFile
appender.FILE.name=FILE
appender.FILE.filename=${rem.home}/rem.log
appender.FILE.layout.type=PatternLayout
appender.FILE.layout.pattern=%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p <%t> [%c] %m%n

logger.rem.name=rem
logger.rem.level=INFO
logger.openjpa.name=openjpa
logger.openjpa.level=INFO
logger.wink.name=org.apache.wink
logger.wink.level=INFO

# Uncomment for subscriberdata cache eviction logging
#logger.subscriberdatacache.name = rem.server.sentinel.subscriberdata.cache
#logger.subscriberdatacache.level = TRACE

logger.audit.name=sentinel.audit
logger.audit.level=INFO
logger.audit.additivity=false
logger.audit.appenderRef.audit.ref=AUDIT

appender.AUDIT.type = RollingFile
appender.AUDIT.name = AUDIT
appender.AUDIT.fileName = ${rem.home}/sentinel-audit.log
appender.AUDIT.layout.type = PatternLayout
appender.AUDIT.layout.pattern = "%d{yyyy-MM-dd HH:mm:ss,SSS}", "%c{1}", %m%n

3

Replace WEB-INF/classes/log4j2.properties in rem.war:

zip ../webapps/rem.war WEB-INF/classes/log4j2.properties

4

Remove temporary files:

cd ..
rm -rf rem-tmp

Import Rhino trust certificate

This can also be done using the REM web UI.

1

Import a Rhino Trust Certificate into REM:

"${JAVA_HOME}/bin/keytool" -importcert -file ${RHINO_HOME}/rhino-trust.cert -keystore "${TOMCAT_HOME}/rem_home/rhino-ems.ks" -storepass changeit -noprompt

Security considerations

Below are recommendations for securely running the Sentinel Express Provisioning Module.

Use https

To prevent your credentials going over the network unencrypted, run REM over https.

Set up SSL

See the Tomcat 9 - SSL How-To docs for help setting up SSL in Apache Tomcat 9.

Configuring Sentinel Services

There are configuration options for these Sentinel services:

Note All service configuration can be managed using the Sentinel Element Manager web-based interface.

Sentinel Common Configuration

  • Core Configuration — The Sentinel Core Configuration defines global parameters used by all services in Sentinel.

  • Mediation Layer Configuration — The Diameter Mediation Layer Configuration tables define parameters which are applicable to all service frontends using the Sentinel-internal Diameter Mediation Layer (currently SS7, SIP, Diameter services).

  • Configuration Common to SS7 and SIP Services — Configuration common to the SS7 and SIP services.

Core Configuration

Description

Configuration name

Sentinel Core Configuration

Applicable contexts

All

The Sentinel Core Configuration defines global parameters used by all services in Sentinel.

Configuration

The Sentinel Core Configuration includes:

Parameters Description

PlatformOperator

The platform operator for this Sentinel installation

DefaultNetworkOperator

The default network operator for this Sentinel installation

NetworkOperators

The list of network operators that may be used in the configuration

HttpParameterForHttpDetermineNetworkOperator

The HTTP parameter that is used the HTTP Determine Network Operator feature

DefaultOcsEntityID

The default OCS entity ID

MaximumCallDuration

The maximum permitted call duration. If set to 0 the call duration is unlimited. Must be a whole multiple of the reservation time as set in the OcsParameterConfiguration feature RequestUnitsSeconds. It is recommended that the multiple is 2 or greater. Maximum call duration is intended to prevent excess call durations and is not intended as a way to limit normal calls

FeatureTimeOut

The feature timeout in milliseconds. May be configured between -1 and 1800000. -1 turns off feature timers. Feature timeout under 1 sec (1000) is not recommended

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SentinelConfigurationTable

Core configuration

Fixed name

Provisioning interfaces

The configuration is provisioned using the web interface.

Mediation Layer Configuration

The Diameter Mediation Layer Configuration tables define parameters which are applicable to all service frontends using the Sentinel-internal Diameter Mediation Layer (currently SS7, SIP, Diameter services).

  • Diameter Mediation Configuration — The DiameterMediation Configuration contains some general settings for the mediation layer.

  • OCS Configuration — The OCS Configuration contains default settings for OCS connections which are used when no specific OCS Destination Configuration has been set.

  • OCS Destination Configuration — The OCS Destination Configuration specifies connection properties and settings for specific OCSes which can be accessed by Sentinel during the course of a session.

  • TccTimer Configuration — The TccTimer configuration determines how the Sentinel-internal Tcc timer will be set when a CreditControlAnswer is received from the OCS.

Diameter Mediation Configuration

Description

Configuration name

Diameter Mediation

Applicable contexts

SS7/SIP/Diameter service

The DiameterMediation Configuration contains some general settings for the mediation layer.

Configuration

The DiameterMediation configuration includes:

Parameters Description

CloseSessionOnErrorBehaviour

String value, either ERRORS_END_SESSION or CCR_T_ENDS_SESSION. Determines if the Diameter Mediation layer ends sessions to the OCS after receiving an update CreditControlAnswer (CCA-U) with an error code in the Result-Code AVP on command level, or leaves sessions open to be terminated explicitly via a termination CreditControlRequest (CCR-T)

VtTimerEnabled

Boolean value Determines if the Diameter Mediation layer performs charging refresh based on the Validity-Time

VTTimerOffset

Integer value Offset value used to compute Validity-Time timer expiry. timeInMs = (VT + offset) * 1000
Note CCR_T_ENDS_SESSION will only produce the expected results if the Quirks RA entity configuration property of the RA entity used to connect to the OCS is set to CONTINUE_SESSION_ON_NON_SUCCESS_UPDATE_RESULT.
Note The Tcc Timer and Validity-Time timers are armed redundantly if the session is replicated.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

DiameterMediationConfigurationTable

Diameter Mediation configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

OCS Configuration

Description

Configuration name

OCS Configuration

Applicable contexts

SS7/SIP/Diameter service

The OCS Configuration contains configuration for default OCS connections used when no specific OCS Destination Configuration has been set.

Whenever Sentinel has to interact with an OCS during the course of a session, it determines the connection to be used from an OCS configuration. First, it tries to find the OCS Destination Configuration referenced by the current value of the OcsId session state field. If no such OcsId is found in session state, Sentinel looks up the default OCS Configuration profile.

Configuration

The OCS configuration includes:

Parameters Value Description

DestinationRealm

String

The value to be used in the Destination-Realm-AVP for outgoing Credit-Control-Requests.

DestinationHost

String

The value to be used in the Destination-Host-AVP for outgoing Credit-Control-Requests.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

DiameterMediationOcsConfigurationTable

OCS default configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

OCS Destination Configuration

Description

Configuration name

OCS Destination Configuration

Applicable contexts

SS7/SIP/Diameter service

The OCS Destination Configuration references specific OCS connections which can be used by Sentinel during the course of a session.

Whenever Sentinel has to interact with an OCS during the course of a session, it determines the connection to be used from an OCS configuration. First, it tries to find the OCS Destination Configuration referenced by the current value of the OcsId session state field. If no such OcsId is found in session state, Sentinel looks up the default OCS Configuration profile.

Configuration

The OCS Destination configuration includes:

Parameters Value Description

OcsId

String

The ID of this OCS Destination configuration. If the OcsId session state field is set and matches this field, then this OCS Destination configuration will be used when establishing the connection to the OCS.

DestinationRealm

String

The value to be used in the Destination-Realm-AVP for outgoing Credit-Control-Requests to this OCS.

DestinationHost

String

The value to be used in the Destination-Host-AVP for outgoing Credit-Control-Requests to this OCS.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

DiameterMediationOCSDestinationTable

OCS Destination configuration

SentinelSelectionKey:OcsId (for example, OpenCloud:::::Ocs1)

Diameter RA configuration profile

The Destination Realm and Destination Host in each OCS configuration must reference a Realm and Host defined in the diameter RA Peer and realm configuration.

Provisioning interfaces

The configuration can be provisioned using the web interface.

TccTimer Configuration

Description

Configuration name

Tcc Timer

Applicable contexts

SS7/SIP/Diameter service

The TccTimer configuration determines how the Sentinel-internal Tcc timer will be set when a CreditControlAnswer is received from the OCS.

Each time a CreditControlAnswer from the OCS is received by the mediation layer and subsequently passed on to the frontend layer (Diameter, SS7 or SIP service), Sentinel starts the Tcc timer which is supervising the responsiveness of the frontend/client. The duration of this timer is determined by the TccTimer configuration. It can be:

  • via a formula based on the Granted-Service-Units (GSU) AVP of the received CreditControlAnswer and configuration parameters for offsets and multipliers:

    Duration = (GsuScaleFactorMultiplier * GSU)/GsuScaleFactorDivisor + GsuOffset

  • calculated via a formula based in a similar way on the Validity-Time (VT) AVP:

    Duration = (VtScaleFactorMultiplier * VT)/VtScaleFactorDivisor + VtOffset

  • switched off completely

  • set to a constant value.

Configuration

The TccTimer configuration includes:

Parameters Value Description

DefaultTccTimeout

Long

The timer duration if USE_DEFAULT_TIMEOUT is set

TccOption

String

one of NO_TCC, USE_DEFAULT_TIMEOUT, USE_VT, USE_GSU. Determines what option shall be used to calculate the Tcc timer duration.

GsuScaleFactorMultiplier

Integer

Used when tccOption is set to USE_GSU.

GsuScaleFactorDivisor

Integer

Used when tccOption is set to USE_GSU.

GsuOffset

Integer

Used when tccOption is set to USE_GSU.

VtScaleFactorMultiplier

Integer

Used when tccOption is set to USE_VT.

VtScaleFactorDivisor

Integer

Used when tccOption is set to USE_VT.

VtOffset

Integer

Used when tccOption is set to USE_VT.

TccMinValue

Long

The outcome of any of the Tcc calculation options above is capped at this value; in other words, the Tcc timer duration cannot fall below this threshold value.
Note The Tcc Timer is armed redundantly if the session is replicated.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

TccTimerConfigurationTable

TccTimer configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

Configuration Common to SS7 and SIP Services

Configuration common to the SS7 and SIP services.

  • Activity Test Configuration — The Activity Test configuration determines when Sentinel will test for the continued liveness of a session that has had a period of inactivity.

Activity Test Configuration

Description

Configuration name

Activity Test

Applicable contexts

SS7 service, SIP service

The Activity Test configuration determines when Sentinel will test for the continued liveness of a session that has had a period of inactivity.

Whilst a session is being monitored, Sentinel runs a timer where the duration is based on the Activity Test configuration. The timer is stopped each time Sentinel receives incoming traffic on the session. If the session is still active once the message has been processed, then the timer is restarted again. If the timer expires, Sentinel tests the activity/liveness/validity of the session using an appropriate protocol specific method. If this test fails, the session is terminated.

Configuration

The Activity Test configuration includes:

Parameters Value Description

TimerModeType

String

Either ‘chargingPeriodMultiple’ or ‘fixedDuration’.

ChargingPeriodMultiple

Decimal

If the Timer Mode Type is set to ‘chargingPeriodMultiple’ and the call is chargeable, this value specifies a multiple of the charging period duration to use as the timer duration.

FixedDuration

Long

If the Timer Mode Type is set to ‘fixedDuration’, or the call is not chargeable, this value specifies a fixed timer duration in seconds.

ActivityTestInvokeTimeout

Long

Specifying the period of time to wait, in milliseconds, for a successful response to an Activity Test. If a successful response is not received within this time period, the Activity Test is regarded as failed.

RandomPeriod

Long

Specifying the basis for an additional random period that will be added to the calculated duration. The concrete period added will be in the range of [0..RandomPeriod]

ChargingPeriodOffset

Long

Specifying an offset to be added to the calculated timer duration for the initial activity test when using ‘chargingPeriodMultiple’, in seconds. Used to prevent early firing of Activity Test timer before a call is answered when using ‘chargingPeriodMultiple’ with a small initial time allocation.

Configuration Profile Naming

Configuration Profile Table Name Description Profile Naming

ActivityTestConfigurationTable

Service configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

Sentinel for Diameter

Description

Configuration name

Diameter Sentinel

Applicable contexts

Diameter service

The Diameter Sentinel configuration contains general configuration properties for Sentinel’s Diameter-to-Diameter mediation service.

Configuration

The DiameterSentinel configuration includes:

Parameters Value Description

CreditFinalisationWaitingTime

Long

Number of milliseconds Sentinel will wait for receipt of a CCR-T after having received an ASA. If the CCR-T is not received within this timeframe Sentinel will send a synthesized CCR-T to the OCS to finalise the OCS-session and will simply terminate the client-session

SuppressAbortSessionRequest

Boolean

When false, the Diameter service sends received Abort-Session-Request messages on to the Diameter CTF client peer; when true, the Diameter service responds immediately with an ASA, without sending the Abort-Session-Request to the CTF peer, closing the CTF session, and sending a final CCR-T with zero used service units.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

DiameterSentinelConfigurationTable

Service configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

Sentinel for SIP

Note See Sentinel Common Configuration for configuration options applicable to all Sentinel services.

Activity Test Configuration for SIP

Description

Configuration name

Activity Test

Applicable contexts

SIP service

The Activity Test configuration determines when Sentinel will test for the continued liveness of a SIP session that has had a period of inactivity.

During the active call period, Sentinel runs a timer where the duration is based on the Activity Test configuration. The timer is stopped each time Sentinel receives a message from the external SIP UAC/UAS; and if the call is still active then the timer is restarted again. If the timer expires, Sentinel sends re-Invite messages to test that the connection to the external SIP UAC/UAS is still active. If the Activity Test fails, the session is terminated.

Note The configuration is in common with the SS7 service. See Activity Test Configuration.

Registrar Cassandra Subscriber Data Store Config

Description

The configuration table for Cassandra data storage is CassandraSubscriberDataStoreConfig and it is scoped under Platform Operator Name. The following table shows the major parameters to configure Sentinel Volte Registrar.

Field Name Description

CassandraTTL

The time-to-live (ms) for each row in the Cassandra database

CassandraTracing

Whether tracing should be enabled for Cassandra queries

Provisioning interfaces

The configuration can be provisioned using the web interface.

Registrar Configuration Table

Description

The major configuration table for Sentinel VoLTE Registrar is RegistrarConfigurationTable and is scoped under Platform Operator Name. The following table shows the major parameters to configure Sentinel Volte Registrar.

Field Name Description

AtcfUpdateTimeout

Time (ms) to wait before we consider the ATCF update has failed.

AtuSti

The ATU-STI the registrar should report.

CSRNPrefixForCorrelationMSISDN

Prefix to strip from CSRN to get the C-MSISDN.

ShHssDestinationHost

HSS destination host to use in Sh requests.

ShHssDestinationRealm

HSS destination realm to use in Sh requests.

ShOriginHost

Origin host to use in Sh requests.

ShOriginRealm

Origin realm to use in Sh requests.

SubscriberDataFacadeType

Indicates the data storage type: HssCache or Cassandra.

WriteAuditCdr

If audit CDRs should be written

AuditCdrPrivateIdFilter

A private-id for which an audit CDR should be written. This setting over-rides 'WriteAuditCdr'. Values of null or "" are ignored.

CdrStreamName

The cdr stream where audit CDRs are written

UsePrivateIdAsRegistrarDataPrimaryKey

Specifies whether the private-id is used as the primary key for registration data stored in Cassandra.

Provisioning interfaces

The configuration can be provisioned using the web interface.

SDP Comparison for Rating Condition Change Determination

Description

Configuration name

SDP Media Codec Profile Table

Applicable contexts

SIP service

The SIP Sentinel SDP Media Codec Profile Table declares the codecs recognised by the SDP comparision function and the equivalence classes to which they belong.

The table is a configurable map of encoding name to charging equivalence class. Sentinel SIP inspects the SDP rtpmap lines to provide the rtpmap encoding name for purposes of looking up the charging equivalence class by encoding name key.

Encoding names with the same equivalence class will be considered equal in terms of charging.

Configuration

The Sentinel SIP configuration includes:

Parameters Description

EncodingName

the encoding name; typically represented in an rtpmap attribute (for example, G723)

EquivalenceClass

the equivalance class to which this codec belongs (for example, Audio8KHzSingleChannel)

Channels

the number of channels for the media attribute encoding (for example, 1)

ClockRate

the clock rate for the media attribute encoding (for example, 8000)

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SDPMediaCodecProfileTable

SDP Media Codec equivalance class configuration

SentinelSelectionKey + EncodingName/ClockRate/Channels (for example, OpenCloud::::G723/8000/1)

Provisioning interfaces

The configuration can be provisioned using the web interface.

SIP Sentinel Configuration

Description

Configuration name

Sip Sentinel Configuration

Applicable contexts

SIP service

The SIP Sentinel Configuration defines the home network IDs and home country codes for a Sentinel selection key.

An example usage of this configuration is where the Sentinel SIP service feature DetermineIfRoamingFeature uses the HomeNetworkID to determine if a SIP Session is a roaming scenario.

Configuration

The Sentinel SIP configuration includes:

Parameters Description

HomeNetworkIDs

Indicates the home network IDs for a network or platform operator as defined by the Sentinel selection key.

MaxEventDeliveryCycles

Indicates maxinum number of event delivery cycles. Used to prevent infinite loops of local events and abort session when it is exceeded.

IcscfUri

Indicates the SIP URI of the I-CSCF. Used when the AS needs to communicate directly with the I-CSCF.

ISOCode

Indicates the ISO country code for a network or platform operator as defined by the Sentinel selection key.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SipSentinelConfigurationTable

Service configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

SIP Session Control Configuration

Description

Configuration name

SIP Session Control

Applicable contexts

SIP service

The SIP Session Control Configuration determines how the SIP Sentinel service controls the duration of sessions.

Configuration

The default behaviour of Sentinel is to: control session duration via SLEE timers.

If the configuration is missing or invalid, Sentinel defaults to ‘notControlled’ for the SipSessionControlMethod.

The SIP session control configuration includes:

Parameters Description

SipSessionControlMethod

Indicates how sessions should be controlled by the SIP Sentinel service. This may be set to ‘notControlled’ (if the service should not control session duration), or ‘controlViaSleeTimer’ (if session duration will be managed by SLEE timers).

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SipSessionControlMethodTable

Service configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

SIP Third Party Call Configuration

Description

Configuration name

Sip Third Party Call Configuration

Applicable contexts

SIP service

The SIP Third Party Call Configuration determines how the SIP Sentinel service behaves when initiating SIP sessions in response to a non-SIP triggering, e.g. SIP sessions set up via HTTP requests.

Configuration

The SIP Third Party Call configuration is mostly used to determine the form of the INVITEs sent when a third party SIP session is initiated.

The SIP Third Party Call configuration includes:

Parameters Value Description

ExpiresHeader

Integer

to use for the Expires header.

MaxForwardsHeader

Integer

to use for the MaxForwards header.

RouteHeaderURI

String

contains the URI to use for the Route header.

Tip This configuration value can be overridden in SentinelSipSessionState to allow features to perform their own destination determination. e.g. for load balancing.

SupportedHeader

String

to use for the Supported header.

UserAgentHeader

String

to use for the User Agent header.

TransportAsEnum

The Transport type to use. This may currently be ‘udp’ or ‘tcp’.

IsSipURIUsed

Boolean

A value determining whether the SIP URI configuration value is used.

SipURIDomain

String

A value containing the SIP URI, if used. (See IsSipURIUsed boolean above).

NoAnswerApplicationTimer

Integer

A value determining how long before the ‘no answer’ timer will fire.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SipThirdPartyCallConfigurationTable

Service configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

Sentinel for SS7

Note See Sentinel Common Configuration for configuration options that are applicable to all Sentinel services.

  • Activity Test Configuration for SS7 — The Activity Test configuration determines when Sentinel will test for the continued liveness of a dialog that has had a period of inactivity.

  • Call Information Report Configuration — The Call Information Report configuration determines if Sentinel will request Call Information Reports from the network for an SS7 first-party call and if call alerting time will be chargeable for Mobile Originating calls.

  • Handling GSM Call Forwarding Active on MTC

  • Relay Dialog Configuration — The Relay Dialog Configuration defines the destination SCCP address of the external network element for relayed dialogs.

  • Session Control Configuration — The Session Control Configuration determines how the charging shall be controlled during the session and whether Apply Charging Reports or Call Information Reports shall be used when the charging session to the OCS is finalised.

  • SS7 Call Configuration — The SS7 call configuration defines properties related to event requests and 3rd party call setup.

  • SS7 Diameter Configuration — The SS7 diameter configuration specifies the method used for event based charging scenarios.

Activity Test Configuration for SS7

Description

Configuration name

Activity Test

Applicable contexts

SS7 service

The Activity Test configuration determines when Sentinel will test for the continued liveness of a dialog that has had a period of inactivity.

During the active call period, Sentinel runs a timer where the duration is based on the Activity Test configuration. The timer is stopped each time Sentinel receives a message from the MSC such as an Apply Charging Report; and if the call is still active then the timer is restarted again. If the timer expires, Sentinel sends an Activity Test operation on the dialog to test that the connection to the MSC is still active. If the Activity Test fails, the session is terminated.

Note The configuration is in common with the SIP service. See Activity Test Configuration.

Call Information Report Configuration

Description

Configuration name

Call Information Report

Applicable contexts

SS7 service

The Call Information Report configuration determines if Sentinel will request Call Information Reports from the network for an SS7 first-party call and if call alerting time will be chargeable for Mobile Originating calls. Call Information Reports can be used for more accurate charging as they’re produced directly by the MSC/SSF controlling the call and are therefore not influenced by network or external resource latencies in the service.

Any Call Information Reports received by Sentinel are also included in the CDR produced for the call.

Configuration

The default behaviour of Sentinel is:

  • to request Call Information Reports from the network for both originating and terminating call parties

  • not to charge for call alerting time.

Note A-party or B-party Call Information Reports can be suppressed in order to reduce network traffic.

In the case where the terminating party report is not suppressed, Sentinel can use this report when finalising the amount of credit consumed by the subscriber. For a Mobile Originating (MO) call this report can also be used to charge the subscriber for the call alerting time.

The Call Information Report configuration includes:

Parameters Value Description

SuppressOriginatingPartyCallInformationReport

Boolean

Boolean, if true, stops Sentinel from sending a Call Information Report request for the originating call party.

SuppressTerminatingPartyCallInformationReport

Boolean

Boolean, if true, stops Sentinel from sending a Call Information Report request for the terminating call party.

CallAlertingTimeIsChargeable

Boolean

Boolean, if true, will cause Sentinel to also charge the subscriber for call alerting time (MO calls only). This option can only be set to true if SuppressTerminatingPartyCallInformationReport is also true.

CallAlertingTimePrereservationSeconds

The number of seconds of credit to pre-reserve in the initial credit reservation if call alerting time is chargeable. This value should be set to the maximum expected alerting time. This option is only relevant if CallAlertingTimeIsChargeable is set to true.

CirTimeout

The number of milliseconds to wait for CIRp before timeout and continuing the session. May be set between range 500 - 10000, with a default of 3000.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

CallInformationReportConfigurationTable

Service configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

Handling GSM Call Forwarding Active on MTC

Identifying GSM call forwarding active

Sentinel sets the LatestEventReportIndicatesCallForwarded session state variable to true if tBusy is received on an MT call with ‘call forwarded’ information element included in the event report.

Tip For more information see Noldus 4.3.2.2 Call Forwarding Not Reachable — MS Switched Off. (Refer to Noldus footnote below.)

Handling GSM call forwarding active

The typical operator configuration is to send CAN + CUE when call forwarding is active on an MT call. To configure this behaviour in Sentinel, logic similar to the follow must be included in the EndSession feature execution point:

if session.LatestEventReportIndicatesCallForwarded {
    run ContinueAndClose
} else {
    run ReleaseAndClose
}

References

NOLDUS

CAMEL INTELLIGENT NETWORKS FOR THE GSM, GPRS AND UMTS NETWORK

Rogier Noldus

2006

John Wiley & Sons, Ltd

Relay Dialog Configuration

Description

Configuration name

Relay Dialog Configuration

Applicable contexts

SS7 service

The Relay Dialog Configuration defines the destination SCCP address of the external network element for relayed dialogs.

Configuration

The Relay Dialog Configuration includes:

Parameters Description

RelayDestinationSccpAddress

The destination SCCP address string of the external network element for relayed dialogs

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

RelayDialogConfigurationTable

Service configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

SS7 Call Configuration

Description

Configuration name

SS7 Call Configuration

Applicable contexts

SS7 service

The SS7 call configuration defines properties related to event requests and 3rd party call setup.

Configuration

The SS7 Call Configuration includes:

Parameters Description

NoAnswerApplicationTimer

time (seconds) to use for the No Answer application timer when requesting event reports from the MSC

ThirdPartyCallSetupGmscAddress

SCCP address string of the GMSC used when setting up third party calls.

ThirdPartyCallSetupScfAddress

(optional) SCCP address string of the SCF used when setting up third party calls.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SS7CallConfigurationTable

Service configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

SS7 Diameter Configuration

Description

Configuration name

SS7 Diameter Configuration

Applicable contexts

SS7 service

The SS7 diameter configuration specifies the method used for event based charging scenarios.

Configuration

The SS7 Diameter Configuration includes:

Parameters Description

EventChargingMethod

One of:

  • reserveAndCharge (for ECUR)

  • chargeAndRefund (for IEC)

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

DiameterConfigurationTable

Service configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

Session Control Configuration

Description

Configuration name

Session Control

Applicable contexts

SS7 service

The Session Control Configuration determines how the charging shall be controlled during the session and whether Apply Charging Reports or Call Information Reports shall be used when the charging session to the OCS is finalised.

Configuration

The default behaviour of Sentinel is to use Apply Charging Reports:

  • for controlling the charging for the duration for the session

  • when the CCR-T is sent to the OCS to finalise the credit control session.

The Session Control configuration includes:

Parameters Description

SessionControlMethod

Whether charging during the session shall be performed via internal SLEE Timer, via Apply Charging Reports from the MSC, or via Call Information Report once at the very end of the session. Valid options are:

  • protocolDefault — Use a sensible default for the currently executing protocol.

  • notControlled — Don’t control call duration.

  • controlViaSleeTimer — Periodically perform charging queries based on configurable session timer.

  • controlViaApplyCharging — Use ApplyCharging messages to drive charging interactions. Default for CAP session control.

  • controlViaSleeTimerWithFinalACR — Send an initial ApplyChargingRequest and expect a final ApplyChargingReport. Use session timer to control charging interactions mid-call in the same way as controlViaSleeTimer. Default for CS1+ session control.

  • controlViaCallInformationReport — Use CallInformationReport-based charging interaction method.

PreferredEndCallChargingEvent

Whether to use Apply Charging Report or Call Information Report for credit finalisation, in the case where both these events are available at call end. Valid options are: ‘useACR’, ‘useCIRp’.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SessionControlMethodTable

Service configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The configuration can be provisioned using the web interface.

Sentinel Components

  • Resource adaptors — Sentinel comes with several resource adaptors that are used by features bundled with Sentinel and may also be used by new features added with the SDK.

  • Features — Sentinel comes with many existing features that can be used in feature execution scripts.

  • Utility components — Sentinel includes a number of utility software components that are used by features bundled with Sentinel and may also be used by new features added with the SDK.

  • Promotions — features in the mediation layer and related to promotions.

  • Mappers — Sentinel comes with many mappers that can be configured at various mapping points and scopes.

  • Address lists

  • SLEE usage parameter sets

Resource Adaptors

In the SLEE component model, a resource adaptor (RA) provides the interface between the application and the network. It adapts the physical resource to events which the SLEE can send and receive. Sentinel makes use of a number of resource adaptors, for purposes ranging from database connections to network integration.

OpenCloud Resource Adaptors used by Sentinel

Sentinel may install various Resource Adaptors and configure RA entities. This actual RAs and RA entities installed and configured varies based on which components are used.

The Resource Adaptors Entities may include:

  • diameterro-0 — adapts outbound sessions with multiple OCSes; speaks Diameter Gy and Ro

  • diameterro-1 — adapts inbound sessions with multiple Diameter clients; speaks Diameter Gy and Ro

  • cgin  — adapts inbound CAP sessions for CAMEL IN integration

  • http  — adapts inbound http triggers for things such as 3rd-party call initiation

  • cdr  — for writing of call detail records (or 3GPP Charging Data Records)

  • correlation-ra  — maps an item of data to a unique ID for lookup; currently used for call reorigination

  • dbquery-0  — manages relational database connections through JDBC

  • hector  — manages Cassandra connections

  • uid  — generates unique IDs for miscellaneous use by Sentinel features and services

  • sip-sis-ra  — adapts inbound SIP sessions for SIP network integration

Tip All these RAs can be viewed and configured using the Sentinel Element Manager. Future releases of Sentinel will have resource adaptors to support other protocols, such as Diameter CCA. Customers can also add their own resource adaptors, using the Sentinel SDK.

CGIN RA

The Sentinel SS7 service uses the CGIN RA for SS7 integration. For details on configuring the CGIN RA, see the CGIN documentation.

Resource Adaptor Overviews

Below are overviews of:

CDR Resource Adaptor

CDR resource adaptor entities

The Sentinel installer creates a CDR resource adaptor entity called cdr. This resource adaptor entity is used by all Sentinel services.

CDR resource adaptor configuration

Note Refer to the CDR RA Documentation for more information about the CDR RA.

The cdr resource adaptor entity is configured to use the cdr-stream profile of the CdrStreamConfiguration profile table by default.

The output behaviour of the CDR resource adaptor can be customised by modifying this profile in accordance with the CDR RA Documentation.

Sentinel configuration requirements

The cdr RA entity must be configured with CdrFileType=Binary.

For more information about CDRs in the Sentinel platform, refer to:

  • Working with CDRs section of this administration guide to learn about the content of Sentinel CDRs.

  • Customising CDRs in the Extending Sentinel with the SDK guide to learn how to customise the format of the CDRs that Sentinel creates, as well as customising the data included in the CDRs.

CGIN Resource Adaptor

CGIN resource adaptor entities

Note Refer to the CGIN documentation for more information about the CGIN resource adaptor.

There are two CGIN resource adaptor entities in Sentinel:

  • cginra — for CAP dialogs

  • cginmapra — for MAP dialogs.

CAP CGIN RA entity (cginra)

The cginra RA entity is used for initiating and third party CAP dialogs.

MAP CGIN RA entity (cginmapra)

The cginmapra is used by features to initiate MAP dialogs.

Configuring the local-sccp-address

Inter-operator MAP requests require an SSN of 147. The local-sccp-address of the cginmapra RA entity must be configured with sccp address including SSN=147.

Configuring the default-activity-timeout

By default the default-activity-timeout is set to 1800000 (30 minutes) by default. This is too long for the MAP features in Sentinel. It is recommended to set it to a shorter value in the cginmapra RA entity.

Set default-activity-timeout high enough so that the MAP invoke timeouts will be first, taking into account the granularity of signalware/telesys timers, but low enough that hung dialogs do not accumulate, which will cause the RA entity to run out of dialog identifiers while waiting for activity timeout to terminate the hung dialogs.

For instance, if Sentinel MAP features have a maximum invoke timeout of 5 seconds then 10 seconds (10000) would be sufficient for the default-activity-timeout.

Customising the CGIN RA entities used by Sentinel

It may be necessary to configure multiple RA entities to address specific operator network configuration requirements. Additional CGIN RA entities may be used in Sentinel for this purpose. Sentinel has the following link binding by default:

Link name Default Bound RA entity

sentinel-cgin

cginra

sentinel-cgin-atilookup

cginmapra

sentinel-cgin-flashsms

cginmapra

sentinel-cgin-mnplookup

cginmapra

sentinel-cgin-sribasiccall

cginmapra

sentinel-cgin-ussdnotification

cginmapra

A custom CGIN RA entity may be used by creating, configuring and binding the new RA entity.

Correlation RA Overview

What is the Correlation RA?

There are situations where Sentinel must correlate two independent sessions. The Correlation RA allocates a correlation ID with the first session, that can then be used to process a second session. The Sentinel service may associate a blob of data with an allocated correlation ID.

The Correlation RA is used for two cases in Sentinel:

  1. Playing an announcement using ETC/ARI. In this case, the Correlation RA is used to allocate the correlation ID that is included in the ETC message, which is then present in the ARI message sent on a second dialog.

  2. Roaming Re-origination Feature. In this case, the Correlation RA is used to allocate a special routing address that is used in the Connect message on the initial dialog. A second re-originated dialog will be received by Sentinel for this special address. Sentinel uses the Correlation RA on the re-originated dialog to retrieve data that was associated with the special address via the first dialog. The associated data includes relevant details from the InitialDP of the initial dialog.

For more information about the RA itself refer to the Correlation RA documentation.

DBQuery Resource Adaptor

DBQuery resource adaptor entities

The Sentinel installer creates a DBQuery resource adaptor entity called dbquery-0. The dbquery-0 resource adaptor entity is configured to connect to a local relational database.

Note See the DBQuery RA documentation for more about the DBQuery RA.

DBQuery database type

Before installing Sentinel, you can configure the DBQuery RA database type by adding the db.type property to sdk.properties or sdk.local.properties. Valid options for this property are postgres, oracle, and timesten. The Sentinel installation process compiles the DBQuery RA with the appropriate JDBC driver for that db.type.

Many features provided with Sentinel, and new features developed with the Sentinel SDK, may use the DBQuery resource adaptor.

Features that may use the DBQuery resource adaptor

The following features provided with Sentinel may be configured to use the DBQuery resource adaptor:

Note See Provisioning Configuration and Provisioning Data in TimesTen for how to manage data in an external database using the Sentinel Element Manager.

Diameter Resource Adaptor

Diameter RA documentation

View the Diameter RA documentation here.

Diameter resource adaptors

There are currently three diameter resource adaptor entities in Sentinel:

  • diameterro-0 — for OCS connections

  • diameterro-1 — for client connections

  • diameter-sentinel-internal — used as a message factory by mappers in Sentinel’s Diameter mediation layer.

diameterro-1 is available only to the Sentinel Diameter service. diameterro-0 and diameter-sentinel-internal are used by all Sentinel services.

Session timeouts

The default Sentinel configuration has a 10 minute timeout for diameterro-1 (client) and 13 minute timeout for diameterro-0 (OCS). This configuration ensures that if there are events dropped due to overload, the ActivityEndEvents fired on the RA entities will cause the client side to end first. The 3 minute gap is set to allow time for all the ActivityEndEvents on the client side to be delivered before any are fired on the OCS side due.

Diameter version configuration

The Diameter version spoken on the network to either the OCS or the Diameter client can be configured by setting two properties in the relevant resource adaptor. To change the version used in the OCS dialog, diameterro-0 should be reconfigured. Likewise, to change the version used on the client dialog (Sentinel Diameter only), diameterro-1 should be reconfigured. The Diameter version used by diameter-sentinel-internal should not be reconfigured, as it is tied to the internal implementation of Sentinel.

When reconfiguring the Diameter version of either of the external resource adaptors, two fields must be set - Slee3GPPVersion and 3GPPVersion. Slee3GPPVersion should always be set to Vcb0. This is the version of Diameter used by Sentinel internally. 3GPPVersion can be set to the desired protocol version to be used over the network, ranging from V820 to Vcb0.

OCS load balancing

Load balancing of OCS connections can be achieved using the diameterro-0 resource adaptor entity, by configuring multiple hosts within a realm and addressing messages to the realm only (not the host).

Example configuration for OCS load balancing

This example shows the diameterro-0 resource adaptor entity configured to load balance across two OCS nodes.

  • The resource adaptor entity config properties show that it is configured using a profile in the DiameterConfig table.

  • The config profile shows that the known OCS nodes are named diameterserver and diameterserver1.

  • The routing priority metric for both nodes is set to 1 to indicate equal priority, meaning that load balancing will be applied.

  • The DiameterMediationOcsConfigurationTable configuration profile at platform scope does not specify a host, so all outbound Diameter messages will not have the destination host set, but only the realm. This means the resource adaptor entity will round robin among all the hosts configured for the specified realm (in this case opencloud). However this behaviour can be overridden on a per-session basis by setting the OCSId field in session state using, for example, SubscriberDataLookup or a custom feature added with the SDK.

The following rhino-console session shows the complete configuration:

[Rhino@localhost (#0)] listraentityconfigproperties diameterro-0
Configuration properties for resource adaptor entity diameterro-0:
 3GPPVersion (java.lang.String): Vcb0
 BaseMessageApplicationID (java.lang.Integer): 0
 CertificateKeyStore (java.lang.String):
 CertificateKeyStorePassword (java.lang.String):
 CipherSuites (java.lang.String):
 ConfigurationProfile (java.lang.String): DiameterConfig/DiameterRoOcsProfile
 ConfigurationProfilePollTime (java.lang.Integer): 0
 ConnectTimeout (java.lang.Long): 30000
 ExtendedTransportConfiguration (java.lang.String):
 ExtensionAvpSet (java.lang.String): DiameterExtensions/Charging
 ExtensionAvpSetPollTime (java.lang.Integer): 0
 ExtensionMessages (java.lang.Boolean): true
 FireToServiceID (java.lang.String):
 ForceReconnectAfterDPR (java.lang.Boolean): true
 IOClientWorkers (java.lang.Integer): 0
 IOServerWorkers (java.lang.Integer): 0
 Quirks (java.lang.String):
 ReconnectDelay (java.lang.Long): 5000
 RequestTimeout (java.lang.Long): 2000
 SSLSessionTimeout (java.lang.Integer): 0
 ServiceContextId (java.lang.String): session@opencloud.com
 SessionTimeout (java.lang.Long): 780000
 SupportedVendorIds (java.lang.String):
 ThreadPoolSize (java.lang.Integer): 0
 TrustKeyStore (java.lang.String):
 TrustKeyStorePassword (java.lang.String):
 WatchdogTimeout (java.lang.Long): 30000
 WorkQueueSize (java.lang.Integer): 0
 slee-vendor:com.opencloud.rhino_max_activities (java.lang.Integer): 0
 slee-vendor:com.opencloud.rhino_replicate_activities (java.lang.String): none
[Rhino@localhost (#1)] listprofileattributes DiameterConfig DiameterRoOcsProfile
Action=LOCAL
AllowUnknownPeers=true
ApplicationId=0
ApplicationVendorId=0
EnableMultiNodeConfig=false
Host=diameterclient
ListenAddress={null}
NodeIDs={null}
PeerAddress=127.0.0.1
PeerConnectAtStartup=true
PeerHost=diameterserver
PeerPort=3868
PeerTable=<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE peer-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Peer Table Configuration 1.1.0//EN" "http://www.opencloud.com/dtd/diameter-peer-table-1.1.0.dtd">

<peer-table allowUnknownPeers="true">
    <!-- If allowUnknownPeers is true, then any peer may connect to this node.
         If allowUnknownPeers is not true, peers connecting to this node as clients must be defined in the Peer Table.-->
    <peer connectAtStartup="true">
        <hostname>diameterserver</hostname> <!-- Will accept connections from this peer -->
        <port>3868</port>
        <address>127.0.0.1</address>
        <tls>false</tls>
        <option>
            <option-name>TCP_NODELAY</option-name>
            <option-type>java.lang.Boolean</option-type>
            <option-value>true</option-value>
        </option>
    </peer>
    <peer connectAtStartup="true">
        <hostname>diameterserver1</hostname> <!-- Will accept connections from this peer -->
        <port>3868</port>
        <address>192.168.2.100</address>
        <tls>false</tls>
        <option>
            <option-name>TCP_NODELAY</option-name>
            <option-type>java.lang.Boolean</option-type>
            <option-value>true</option-value>
        </option>
    </peer>
</peer-table>
PeerUri={null}
PerNodeHosts={null}
PerNodeListenAddresses={null}
PerNodePorts={null}
PerNodeSecondaryAddresses={null}
Port=3869
Product=OpenCloud Diameter
ProductVendorId=19808
Realm=opencloud
RealmTable=<?xml version="1.0" encoding="UTF-8"?>
                 <!DOCTYPE realm-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Realm Table Configuration 1.1//EN"
                    "http://www.opencloud.com/dtd/diameter-realm-table-1.1.dtd">
                 <realm-table>
                    <realm>
                      <realm-name>opencloud</realm-name>
                      <application-route>
                        <application>
                          <application-id>4</application-id> <!-- 4=CCA -->
                          <vendor-id>0</vendor-id> <!-- optional, default is zero -->
                        </application>
                        <action>LOCAL</action>
                        <peer-ref>
                          <hostname>diameterserver</hostname>
                          <metric>1</metric>
                        </peer-ref>
                        <peer-ref>
                          <hostname>diameterserver1</hostname>
                          <metric>1</metric>
                        </peer-ref>
                      </application-route>
                    </realm>

                    <default-route>
                      <peer-ref>
                        <hostname>diameterserver</hostname>
                        <metric>1</metric>
                      </peer-ref>
                        <peer-ref>
                          <hostname>diameterserver1</hostname>
                          <metric>1</metric>
                        </peer-ref>
                    </default-route>

                  </realm-table>
SecondaryAddresses={null}
Transports=tcp
UseTLS=false
ValidDN={null}
Version=1
[Rhino@localhost (#2)] listprofileattributes DiameterMediationOcsConfigurationTable UNSET::::
DestinationHost={null}
DestinationRealm=opencloud
TimeoutDuration=2000

SIP SIS Resource Adaptor

SIP SIS resource adaptor entity (sip-sis-ra)

Note Refer to the Service Interaction SLEE (SIS) documentation for more information about the SIP SIS resource adaptor.

The sip-sis-ra is used for initiating and third-party SIP dialogs for both the Sentinel SIP Service and the Sentinel Subscription Service.

Link name Default Bound RA entity

sentinel-sip

sip-sis-ra

Sentinel and SIS

The sip-sis-ra interacts directly with the SIS, which is configured with compositions for the Sentinel SIP Service. The Sentinel SIP Service is triggered by all events from the SIP SIS RA entity. This behaviour is configurable. See the Service Interaction SLEE (SIS) documentation for more information about compositions and triggers.

Configuring SIS

Use the sis-console or SIS REM Module to modify the default SIS and sip-sis-ra configuration properties; see the SIS Administration Guide and SIS REM Module User Guide for more details on managing the SIS instance.

Configuring the network interface

By default the sip-sis-ra is set to listen on localhost ports 5061 (secure) and 5060. It should be set to an external interface for network integration.

Unique ID Resource Adaptor

What is the Unique ID RA?

The Unique ID RA generates and returns guaranteed cluster-wide unique identifiers. New identifiers can be requested up to a limit of 512 per millisecond at a steady rate.

Note The identifiers are only guaranteed to be unique for a single Unique ID RA entity

Usage within Sentinel

The Sentinel SS7 Service uses the Unique ID RA to generate unique call reference numbers for non-SS7 triggered calls. All Sentinel services make a Unique ID RA provider available for injection into features, including custom features developed by third-party integrators using the Sentinel SDK. Sentinel Charge users can also make use of the Unique ID RA in their services.

Configuring the Unique ID RA entity

The Unique ID RA requires no configuration of any kind as it retrieves all the resources necessary for operation from Rhino. A Unique ID RA entity is ready for operation as soon as it is activated. The name of the standard RA entity used by Sentinel is uid.

Type and format of the IDs

The unique identifiers are of type java.lang.Long, utilising all 64 bits to maximize the range of unique identifiers possible.

Using the Unique ID RA

A feature or service uses the Unique ID RA by invoking the long generateUniqueID() method of the UniqueIDProvider interface. This method will block if the identifiers are requested continuously at a rate higher than 512 per millisecond.

Features

Sentinel comes with many features that can be used in feature execution scripts:

Feature category For…​

General

many networks

Query and Notification

querying network elements and sending notifications

CAMEL

CAMEL networks

SIP

SIP networks

Diameter Service

Diameter networks

Test

testing

General Features

Sentinel includes many features that are useable in many networks:

Do Not Charge Session Feature

Description

Feature name

DoNotChargeSession

Applicable contexts

SS7 Service, SIP Service

SAS Support

No

Prerequisite Features

None

Notifies the Sentinel core to not charge the session. If Sentinel decides to let the session proceed, it will be a free session. Sentinel may still monitor the session unless another feature instructs Sentinel to not monitor the session (see DoNotMonitorSession feature). This is an initial trigger feature which can run before or after the credit check. If run before the credit check, it will prevent the credit check taking place and Sentinel will not establish a session with the OCS. If run after the credit check, it will cause Sentinel to finalize the OCS session reporting 0 used units.

Note

Immediate Event Charging behaviour

When Immediate Event Charging (IEC) is used (for example, for SMS) then running this feature post-credit-check can result in a refund being sent to the OCS if the session was previously charged. Running this feature pre-credit-check will result in no OCS interactions. Session termination methods such as ConnectAndClose and ContinueAndClose will not refund credit by default, so if a refund is required in those cases then this feature must be run post-credit-check.

Session state inputs and outputs

This feature does not read from or write to session state.

Error scenarios

This feature has no error conditions.

Feature responses

Response Reason

doNotChargeSession

intended behaviour

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

HTTP Determine Network Operator Feature

Description

Feature name

HttpDetermineNetworkOperator

Applicable contexts

SS7 Service, SIP Service, Sentinel Charge Example

SAS Support

No

Prerequisite Features

None

Extracts the name of the Network Operator from an HTTP request. This feature searches the request URL parameters for a name-value pair with name identified in the HttpParameterForHttpDetermineNetworkOperator field of the SentinelPlatformConfiguration. The feature then attempts to map the discovered value to a network operator name by looking it up in the SentinelHttpParameterToNetworkOperatorProfileTable. If the parameter is not found in the URL or there is no mapping available in the SentinelHttpParameterToNetworkOperatorProfileTable, a default network operator is used, as configured in the DefaultNetworkOperator field of the SentinelPlatformConfiguration.

For example, consider an HTTP trigger containing the following URL:

https://acmenet.com/sentinel-ss7?subsn=6401231231&calledstationid=00102

HttpDetermineNetworkOperator will query the name of the HttpParameterForHttpDetermineNetworkOperator in the SentinelConfigurationTable by selection key. In this case it returns “calledstationid”. The corresponding parameter value 00102 is then extracted from the URL, and the profile of the same name is retrieved from the HttpParameterToNetworkOperatorProfileTable. From this profile, the NetworkOperator is retrieved and stored in session state.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

A selection key to be populated with the network operator for this session

Runtime exception handled by feature runner

Outputs

Name Type Format Description

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>:<network>:::)

A Sentinel selection key with a non-empty network operator field

Error scenarios

Scenario Handling

Trigger is not an HTTP request

Report featureCannotStart

Finish

Malformed name-value pair in HTTP request

Increment CouldNotDetermineNetworkOperator stat

Use SentinelConfiguration defaultNetworkOperator

Configured name-value pair not found in request

Increment CouldNotDetermineNetworkOperator stat

Use SentinelConfiguration defaultNetworkOperator

No configured mapping found for value in SentinelHttpParameterToNetworkOperatorProfileTable

Increment CouldNotDetermineNetworkOperator stat

Use SentinelConfiguration defaultNetworkOperator

Feature responses

Response Reason

featureCannotStart

Trigger event must be an HttpRequest

featureHasFinished

feature has finished

Configuration

The SentinelHttpParameterToNetworkOperatorProfileTable:

Parameter Description

NetworkOperator

Network operator this profile’s name is mapped to

Relevant fields of the SentinelPlatformConfigurationTable:

Parameter Description

HttpParameterForHttpDetermineNetworkOperator

Name of the HTTP parameter to search for in the request URL

DefaultNetworkOperator

Network operator to fall back to if the HTTP parameter is not found in the request URL, or no mapping is found in the SentinelHttpParameterToNetworkOperatorProfileTable

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SentinelHttpParameterToNetworkOperatorProfileTable

Mapping of HTTP parameter values to network operator names

HTTP parameter value (for example, 00102)

Provisioning interfaces

The feature is provisioned using the web interface.

OcsParameterConfiguration Feature

Description

Feature name

OcsParameterConfiguration

Applicable contexts

SS7 Service, SIP Service, Diameter Service

SAS Support

No

Prerequisite Features

None

Sets the value of two session state fields related to determining the number of units to request from the OCS. These values can be used by mappers which produce CCRs as output in a decentralized unit-determination scenario.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Do not set RequestUnitsSeconds or RequestUnitsServiceSpecificReport featureHasFinished

Outputs

Name Type Format Description

RequestUnitsSeconds

Long

Positive integer

Number of seconds to request from OCS in a decentralized unit determination scenario

RequestUnitsServiceSpecific

Long

Positive integer

Number of service-specific units to request from OCS in a decentralized unit determination scenario

Error scenarios

Scenario Handling

Missing configuration profile

Use session state defaults

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

The OcsParamConfigFeatureConfigProfileTable:

Parameter Type Description

RequestUnitsSeconds

Long

Units in seconds for Requested-Service-Unit/CC-Time Integer

RequestUnitsServiceSpecific

Long

Units as defined by the service for Requested-Service-Unit/CC-Service-Specific-Units Integer

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

OcsParamConfigFeatureConfigProfileTable

Selection of ocs parameters

SentinelSelectionKey (for example, OpenCloud:OpenCloud:::)

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

Platform Operator is Network Operator Feature

Description

Feature name

PlatformOperatorIsNetworkOperator

Applicable contexts

All Services

SAS Support

No

Prerequisite Features

None

Updates the Sentinel selection key so that the network operator is the same as the configured platform operator. This feature is an initial trigger feature which can be used as an alternative to any of the Determine Network Operator features.

For example, upon initializing a session the selection key might look like:

Platform Operator Network Operator Session Type Plan Subscriber

OpenCloud

Then running PlatformOperatorIsNetworkOperator will result in a selection key that looks like:

Platform Operator Network Operator Session Type Plan Subscriber

OpenCloud

OpenCloud

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

Selection key including platform operator (for example, <platform>::::)

Platform operator to copy into NetworkOperator field of key

Runtime exception handled by feature runner

Outputs

Name Type Format Description

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

Selection key including network operator equal to platform operator (for example, <platform>:<platform>:::)

Platform operator has been copied into NetworkOperator field

Error scenarios

This feature always succeeds.

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Session Tracing Activation Feature

This feature is used to determine if session tracing should be performed on this session or not, based on the subscriberId session state field.

Description

Feature name

SessionTracing

Applicable contexts

All services

SAS Support

No

Prerequisite Features

None

Two functions will be supported initially:

  • Prefix and exact match of the subscriber number based on Block/Allow lists

  • Percentage of Calls (not subscriber specific).

The subscriber number is determined by the SS7 Subscriber Determination Feature, Diameter Subscriber Determination Feature, or SIP Subscriber Determination Feature.

The address used for session tracing activation for each call type is the subscriber address associated with the call.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

Subscriber

String

SIP, Diameter, or SS7 Subscriber number format — see the respective Subscriber Determination features

The subscriber address for this session

Report featureCannotStart, featureHasFinished

Outputs

This feature does not write to SessionState.

Error scenarios

Scenario Handling

Missing entry in SessionTracingFeatureConfigProfileTable

Report featureCannotStart

Sessionstate Subscriber is null

Report featureCannotStart

Missing SessionTracingAddressPrefixList, addressListId, or addressList

Do not enable tracing

Feature responses

Response Reason

featureCannotStart

Configuration data is not found or subscriber address is not set in session state

featureHasFinished

feature has finished

Configuration

General feature configuration

Parameter Type Description

AverageNumberOfCallsToBeTraced

Integer

Calls per 10,000 traced: 0(0%), 1(0.01%), 10(0.1%), 100(1%), 1000(10%)

IsListScreeningModeUsed

Boolean

true/false. True selects list screening; false selects random tracing of sessions.

For the percentage of calls, a configuration profile will be maintained with the percentage of calls to be matched.

Percentage setting:

  • 0 — no calls are enabled

  • 1 — 1 in 10000 (or 0.01%) of calls are enabled

  • 10 — 10 in 10000 (or 0.1%) of calls enabled

  • 100 — 100 in 10000 (or 1%) of calls enabled

  • 1000 — 1000 in 10000 (or 10%) of calls enabled

  • No other configuration values valid

Note Any value above 10% of calls is out of the scope of this capability. 100% is already provided by the standard tracers.

Address list configuration

If list screening is activated, the Session Tracing Activation Feature uses a list of subscriberIds that, if matched to a session, will switch on tracing for the session. See Address lists for information on how to configure the address list data.

Tracing output

Tracing output will be sent to the parallel session branch of the trace key tree (that is, session.sentinel rather than sentinel). The level of the session tracing is determined by the trace levels of each key in that tree.

The session tracing prefix will be set to the value of subscriberId.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SessionTracingFeatureConfigProfileTable

Session tracing configuration parameters

SentinelSelectionKey (for example, OpenCloud::::)

${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:SessionTracing:AddressPrefixList

${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable

Feature specific Address List entry table

${SELECTIONKEY}:SessionTracing:AddressPrefixList:${ADDRESS}

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

Subscriber Data Lookup Feature

The Subscriber Data Lookup feature is a pre-credit check feature used to query subscriber-specific information from a relational database and store it in session state, for use by Sentinel features and mappers.

Description

Feature script name

SubscriberDataLookup

Applicable contexts

All services

SAS Support

No

Prerequisite Features

One of SS7 Subscriber Determination Feature, SIP Subscriber Determination Feature or Diameter Subscriber Determination Feature

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

Subscriber

String

SIP, Diameter, or SS7 Subscriber number format — see the respective Subscriber Determination features

The subscriber for this session whose data is to be retrieved from the subscriber database

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

Any sessionstate field

Supported types: String, Boolean, Integer, String[], Date[], Date

Any format

Data to be loaded into sessionstate from subscriber database

Error scenarios

Scenario Handling

Missing lookup type configuration

Report featureCannotStart

Sessionstate Subscriber is null

Report featureCannotStart

Exception while loading subscriber data from data source

Report featureCannotStart

No subscriber data found or empty record

Report featureFailedToExecute

Feature responses

Response Reason

featureCannotStart

invalid configuration

featureFailedToExecute

invalid subscriber

featureHasFinished

feature has finished

Configuration

Subscriber record field configuration:

The feature is configurable to allow additional fields to be added to the subscriber record and associate the additional or existing fields with with new or existing session state fields. These field definitions are configured in the ${SELECTIONKEY}SubscriberDataLookupFieldDefinitionProfileTable as follows:

Field Type Description

ColIdx

String

Indicates the column index of this field in a subscriber data record. Should match the profile name.

InsertParamIdx

int

Indicates the column index of this field in a subscriber data record. Should match the profile name.

ResFieldname

String

Name of the field when read into a result record

SessionStateFieldname

String

Name of the session state field this field should be loaded into

Type

String

The type of the field, both in session state and in the data source. Supported types: String, Boolean, Integer, String[], Date[], Date

UpdateParamIdx

int

Indicates the column index of this field in a subscriber data record. Should match the profile name.

The table of fields used for the mapping are scoped to the Sentinel selection key. The selection key may be configured at the following levels:

  • Platform operator

  • Network operator

  • Session type

  • The field definitions are configurable by Sentinel selection key.

The Subscriber Data Lookup feature may retrieve the subscriber record from:

  • MySQL via JDBC

  • TimesTen via JDBC

  • Oracle via JDBC

  • Cassandra database (experimental).

  • JSLEE profiles (testing purposes)

Data source configuration

The choice of data source type is configured in the SubscriberDataLookupConfigProfileTable:

Field Type Description

LookupType

String

One of dbQuery, profile, profileIms, or Cassandra
Lookup type Description

dbQuery

Uses the dbquery-0 ra entity to perform the subscriber data query. This option is used for all the different RDBMS types such as MySQL, Oracle, and TimesTen. The type of database used and the associated settings are configured in the {{dbquery-0}}resource adaptor entity configuration. See DBQuery Resource Adaptor for further configuration information.

profile

Uses the ${PLATFORMOPERATOR}_SubscriberDataRecordProfileTable for the lookup. Only suitable for small sets of subscribers for testing and development purposes.

profileIms

Uses the ${PLATFORMOPERATOR}SubscriberDataImsPublicUserIdentityProfileTable and ${PLATFORMOPERATOR}SubscriberDataRecordProfileTable for the query.

Cassandra

Experimental.

SQL statement configuration

For flexibility and ease of integration, the Subscriber Data Lookup Feature is agnostic regarding external SQL data schemas. The SQL queries for a particular network operator are stored in a configuration profile scoped by Sentinel selection key to support the correct mapping.

SubscriberDataLookupSqlConfigProfileTable:

Field Type Description

LoadSQL

String

The SQL query for loading subscriber data from the data source. For example:

SELECT * FROM OpenCloud_Subscribers WHERE MSISDN = ?

ListSQL

String

The SQL query for listing Subscriber Data record ids (msisdns). For example:

SELECT MSISDN FROM OpenCloud_Subscribers ORDER BY MSISDN

InsertSQL

String

The SQL query for inserting a new Subscriber Data record. For example:

INSERT INTO OpenCloud_Subscribers
    (MSISDN,IMSI,FirstCall,subscriberlanguage,Account,SubscriptionType,ValidityStart,
    ValidityEnd,HomeZoneEnabled,HomeZoneList,ocsId,FriendsAndFamilyEnabled,FriendsAndFamilyList,
    ClosedUserGroupEnabled,ClosedUserGroupList,ClosedUserGroupPreferred,CUGIncomingAccessAllowed,
    CUGOutgoingAccessAllowed,CfBusy,CfNoReply,PromotionList,PromotionValidityStartDates,
    PromotionValidityEndDates)
VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)

UpdateSQL

String

The SQL query for updating a Subscriber Data record. For example:

UPDATE OpenCloud_Subscribers
    SET IMSI = ?,FirstCall = ?,subscriberlanguage = ?,Account = ?,SubscriptionType = ?,
        ValidityStart = ?,ValidityEnd = ?,HomeZoneEnabled = ?,HomeZoneList = ?,ocsId = ?,
        FriendsAndFamilyEnabled = ?,FriendsAndFamilyList = ?,ClosedUserGroupEnabled = ?,
        ClosedUserGroupList = ?,ClosedUserGroupPreferred = ?,CUGIncomingAccessAllowed = ?,
        CUGOutgoingAccessAllowed = ?,CfBusy = ?,CfNoReply = ?,PromotionList = ?,
        PromotionValidityStartDates = ?,PromotionValidityEndDates = ?
    WHERE MSISDN = ?

DeleteSQL

String

The SQL query for deleting a Subscriber Data record. For example:

DELETE FROM OpenCloud_Subscribers WHERE MSISDN = ?

loadByImsPublicUserIdentitySQL

String

SQL statement for loading a subscriber data record by a subscriber’s IMS public user identity; for example:

SELECT subs.* FROM @platform.operator.name@_Subscribers subs
    INNER JOIN @platform.operator.name@_SubscriberImsPublicUserIdentity sipids
    ON subs.MSISDN = sipids.SubscriberId
    WHERE sipids.ImsPublicUserId = ?

listImsPublicUserIdentitiesSQL

String

SQL statement for listing a subscriber’s IMS public user identities based on their subscriber ID

insertImsPublicUserIdentitySQL

String

SQL statement for inserting a new IMS public user identity for a subscriber

deleteImsPublicUserIdentitySQL

String

SQL statement for deleting a single IMS public user identity for a subscriber

deleteAllImsPublicUserIdentitiesForSubscriberSQL

String

SQL statement for deleting all of a subscriber’s IMS public user identities

useImsPublicUserIdentities

boolean

Use IMS Public User Identity SQL statements?

DatabaseRequestTimeout

int

The timeout period for any SQL query. Must be greater than 0

AsynchronousQuery

boolean

Uses DBQuery RA events to return result sets if true otherwise blocks the staging thread waiting for DatabaseRequestTimeout period using futures.

Subscriber data schema

The subscriber data schema contains the following mandatory fields (i.e. a field definition for these MUST be present as part of the Subscriber Record Field configuration) for all service types:

Parameter name Parameter type Description

MSISDN

String

Identifies the subscriber record

Language

String

Language code set during first call handling

Account

String

Account code required by the OCS

The default Sentinel SS7 Service configuration will include the following fields in addition to the mandatory fields:

Parameter name Parameter type Description

IMSI

String

Required by some service features

OCSId

String

Id of the OCS for this subscriber

SubscriptionType

String

identifes the subscription type of the subscriber

ValidityStart

String

Time and timezone of subscription validity. See Subscriber Validity Feature

ValidityEnd

String

Time and timezone of subscription validity. See Subscriber Validity Feature

HomeZoneEnabled

Boolean

True when HomeZone feature is activated for this subscriber. See Home Zone Feature

HomeZoneList

String[]

List of zones for this subscriber. See Home Zone Feature

FriendsAndFamilyEnabled

Boolean

true when HomeZone feature is activated for this subscriber. See Friends and Family Feature

FriendsAndFamilyList

String[]

List of zones for this subscriber. See Friends and Family Feature

ClosedUserGroupEnabled

Boolean

true when HomeZone feature is activated for this subscriber. See Closed User Group Feature

ClosedUserGroupList

String[]

List of zones for this subscriber. See Closed User Group Feature

ClosedUserGroupPreferred

Integer

List of zones for this subscriber. See Closed User Group Feature

CUGIncomingAccessAllowed

Boolean

See Closed User Group Feature

CUGOutgoingAccessAllowed

Boolean

See Closed User Group Feature

CfBusy

String

Forwarding number on busy. See Default Call Forwarding Feature

CfNoReply

String

Forwarding number on no reply. See Default Call Forwarding Feature

PromotionList

String array

Used by the subscriberIsEligible promotion script function. See Scripted Promotions Feature

PromotionValidityStartDates

String[]

Used by the subscriberIsEligible promotion script function. See Scripted Promotions Feature, and Subscriber Validity Feature for the date format

PromotionValidityEndDates

String[]

Used by the subscriberIsEligible promotion script function. See Scripted Promotions Feature, and Subscriber Validity Feature for the date format

The default Sentinel Diameter Service configuration will include the following fields in addition to the mandatory fields:

Parameter name Parameter type Description

CURRENTLY NONE

In the case where a subscriber is a user of both SS7 and Diameter services, the record will contain fields from both; but the Subscriber Data Lookup feature will only load data from fields associated with the selection key.

Example:

MSISDN

34600000001

Language

English

Account

6325

IMSI

346000000021234

OCSId

1

SubscriptionType

No

ValidityStart

1299193200664

ValidityEnd

3161070000000

HomeZoneEnabled

false

HomeZoneList

[WgtnCBD]

FriendsAndFamilyEnabled

false

FriendsAndFamilyList

[34600000001]

ClosedUserGroupEnabled

false

ClosedUserGroupList

[CUG1Profile]

ClosedUserGroupPreferred

1

CfBusy

34600000002

CfNoReply

34600000003

PromotionList

[FreeOffpeakVoice]

PromotionValidityStartDates

[1299193200664]

PromotionValidityEndDates

[3161070000000]

IMS

Public User Identities
Parameter Name Parameter type Description

ImsPublicUserId

String

an IMS public user identity

SubscriberId

String

subscriber ID used as key to the subscriber data table

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_SubscriberDataRecordProfileTable

Per subscriber data records — use only for very small subscriber sets

MSISDN

${PLATFORMOPERATOR}_SubscriberDataImsPublicUserIdentityProfileTable

IMS public user identity to subscriber ID table — use only for very small subscriber sets

IMS Public User Identity, for example sip:user34600000002@opencloud.com

SubscriberDataLookupConfigProfileTableName

Field configuration and session state mapping

SentinelSelectionKey (for example, OpenCloud::::)

SubscriberDataLookupSqlConfigProfileTableName

SQL statement configuration

SentinelSelectionKey (for example, OpenCloud::::)

${SELECTIONKEY}_SubscriberDataLookupFieldDefinitionProfileTable

Table for mapping sql columns to session state; note that the SELECTIONKEY part has ‘^’ as separator character in this case for the table name!

Any name unique to the table

Database schemas

Database schemas for TimesTen and Oracle are available in the Sentinel release package.

Provisioning interfaces

The SubscriberDataLookup feature subscriber records and configuration may be provisioned using the web interface for the records and feature configuration.

Additional database support

For additional database support, please contact OpenCloud.

Subscriber Validity Feature

Description

Feature script name

SubscriberValidity

Applicable contexts

All services

SAS Support

No

Prerequisite features

SubscriberDataLookup

The Subscriber Validity feature performs a check that a subscriber is within a validity period within two inclusive dates. If the start date is not present, all dates prior to the end date are considered valid. If the end date is not present, then all dates from the start date are considered valid.

The validity dates are set on a per-subscriber basis.

If the current date at session initiation is within the valid period for the subscriber, the feature will have no effect on the call.

If the current date at session initiation is outside the valid period for the subscriber, the feature will release the call.

OCS interface

This feature has no interaction with the OCS (except for preventing the initial credit check by releasing the session).

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

ValidityStart

long

The time in UTC milliseconds from the epoch

Start of the subscriber’s validity period

value ⇐0 implies validity until ValidityEnd

ValidityEnd

long

The time in UTC milliseconds from the epoch

End of the subscriber’s validity period

value ⇐0 implies validity from ValidityStart

Outputs

This feature does not write to sessionstate.

Error scenarios

Scenario Handling

Invalid subscriber

Report featureFailedToExecute

Feature responses

Response Reason

featureFailedToExecute

invalid subscriber

featureHasFinished

feature has finished

Configuration

There are no general, feature-wide configuration parameters for this feature.

The subscriber validity fields are read using the Subscriber Data Lookup Feature.

Parameter Type Description

ValidityStart

String

Time and timezone of subscription validity

ValidityEnd

String

Time and timezone of subscription validity

  • The format of these parameters must follow the ISO 8601 standard, specifically the YYYY-MM-DDThh:mm:ss±hh:mm format.

  • ValidityEnd must be: the same day as ValidityStart or later; not set.

  • ValidityStart must be: the same day as ValidityEnd or earlier; not set.

Example:

ValidityStart

2011-03-04T12:00:00+02:00

ValidityEnd

2070-03-04T00:00:00-08:00

If neither ValidityEnd nor ValidityStart are set, the session is valid.

Provisioning interfaces

The Subscriber Validity Feature is provisioned using the Subscriber Data Lookup Feature.

Query And Notification Features

Sentinel includes many features for querying network elements and sending notifications:

ATI Lookup Feature

The ATI Lookup feature performs a MAP AnyTimeInterrogation lookup.

Description

Feature name

ATILookup

Applicable contexts

SS7 service

SAS Support

No

Prerequisite Features

Determine ATI Lookup Number Feature

The MAP AnyTimeInterrogation lookup is based on the address selected by a previous execution of the Determine ATI Lookup Number Feature. The ATI request contents and destination HLR are determined by the configuration associated with the feature.

The ATI response is saved in the Sentinel session state.

Feature parameters

The ATI Lookup feature supports the following parameters that may be passed in a feature execution script run statement:

Name Description

configQualifier

An additional string appended to the SentinelSelectionKey when determining the configuration profile used by the feature. For example, if the original configuration profile was OpenCloud::::, then the configuration profile used for a configQualifier parameter of “Config1” would be OpenCloud:::::Config1.

Session State inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

See error handling for ATILookupFeatureConfigProfileTable

ATILookupNumber

String

MSISDN string

Subscriber MSISDN to perform the ATI lookup for

See error handling

Outputs

Name Type Format Description

AnyTimeInterrogationRes

com.opencloud.slee.resources.cgin.map.MAPAnyTimeInterrogationRes

MAPAnyTimeInterrogationRes

The ATIResponse from the HLR for the ATILookup

Error scenarios

Scenario Handling

Missing entry in ATILookupFeatureConfigProfileTable

Increment SendFailures stat
Report featureFailedToExecute

Null sessionstate ATILookupNumber

Increment SendFailures stat
Report featureFailedToExecute

Error parsing ATILookupNumber

Increment SendFailures stat
Report featureFailedToExecute

Null sessionstate HLRAddress

Increment SendFailures stat
Report featureFailedToExecute

Null sessionstate GSMSCFAddress

Increment SendFailures stat
Report featureFailedToExecute

Failed to send request Increment

SendFailures stat
Report featureFailedToExecute

ATIResponse missing SubscriberInfo.MnpInfo

Increment MalformedResponses and ReceivedResponses stats
Do not set sessionstate AnyTimeInterrogationRes
End and detach from dialog

Feature responses

Response Reason

featureFailedToExecute

ATI response timeout or failed sending request

featureHasFinished

feature has finished

Configuration

The ATI Lookup configuration includes:

Parameters Type Description

SccpOriginatingAddress

SCCP address

Will be used as the TCAP Calling Party Address in dialogs initiated towards the HLR and MSC. May be null, in which case the local SCCP address configured for the platform is used. Example: type=c7,ri=gt,digits=34607012345,nature=national,national=true

InvokeTimeout

Long

AnyTimeInterrogation invoke timeout in milliseconds (for example, 5000). A ‘0’ value results in CGIN RA defaults being used.

RouteOnSubscriberNumber

Boolean

‘true’ will route based on the selected ATILookupNumber.

GSMSCFAddress

AddressString

Return address for responses (such as address of Sentinel)

HLRAddress

SCCP address

Static HLR address, or dynamic address template used when performing dynamic routing.

QueryLocationInfo

Boolean

Whether to include location info query in the ATI request.

QuerySubscriberState

Boolean

Whether to include subscriber state query in the ATI request.

QueryIMEI

Boolean

Whether to include IMEI query in the ATI request.

QueryMSClassmark

Boolean

Whether to include MS Classmark query in the ATI request.

HLR routing determination

The destination HLR for the MAP AnyTimeInterrogation request is determined based on routeOnSubscriberNumber configuration value. If true, the HLRAddress will not be considered a static address, and will instead be used as a template into which the ATILookupNumber (set by the Determine ATI Lookup Number Feature) digits are copied to determine the HLR address to route to.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

ATILookupFeatureConfigProfileTable

Feature configuration

SentinelSelectionKey (such as OpenCloud::::)

Provisioning interfaces

The feature is provisioned using the web interface.

Determine ATI Lookup Number Feature

Description

Feature name

DetermineATILookupNumber

Applicable contexts

SS7 service

SAS Support

No

Prerequisite Features

The Determine ATI Lookup Number feature is an initial trigger feature used to configure a subsequent execution of the ATI Lookup Feature. The feature extracts one of the CalledPartyNumber, CallingPartyNumber, or CalledPartBCDNumber from a CAP InitialDP, or the subscriber from session state, and saves it for later use.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report
featureCannotStart

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

InitialDP which triggered this session

Report
featureCannotStart

CallType

com.opencloud.sentinel.common.CallType

Session type of this call for determining from configuration which party address to look up

Report
featureCannotStart

Outputs

Name Type Format Description

ATILookupNumber

String

MSISDN string

The subscriber address to perform the ATI Lookup for

Error scenarios

Scenario Handling

Missing entry in DetermineATILookupNumberConfigProfileTable

Report featureCannotStart

Session state InitialDPArg is null

Report featureCannotStart

Session state InitialDPArg not CAP

Report featureCannotStart

Session state CallType is null

Report featureCannotStart

No configured lookup party for call scenario

Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

invalid or missing configuration

featureHasFinished

feature has finished

Configuration

The Determine ATI Lookup Number configuration includes:

Parameters Type Description

MobileOriginatingParty

LookupPartyEnum

The party to use for the subsequent ATI Lookup (via the ATI Lookup Feature) for mobile originating calls.

MobileTerminatingParty

LookupPartyEnum

The party to use for the subsequent ATI Lookup (via the ATI Lookup Feature) for mobile terminating calls.

MobileForwardedParty

LookupPartyEnum

The party to use for the subsequent ATI Lookup (via the ATI Lookup Feature) for mobile forwarded calls.

Each LookupPartyEnum property may be set to one of the following values:

Value name Description

CallingPartyNumber

Indicates to set the ATI Lookup number from the InitialDP.CallingPartyNumber

CalledPartyNumber

Indicates to set the ATI Lookup number from the InitialDP.CalledPartyNumber

CalledPartyBCDNumber

Indicates to set the ATI Lookup number from the InitialDP.CalledPartyBCDNumber

SessionSubscriber

Indicates to set the ATI Lookup number from the Sentinel session subscriber.

Using this value requires a previous execution of the SS7 Subscriber Determination Feature.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

DetermineATILookupNumberConfigProfileTable

Feature configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The feature is provisioned using the web interface.

Determine MNP Lookup Number Feature

Description

Feature name

DetermineMNPLookupNumber

Applicable contexts

SS7 service

SAS Support

No

Prerequisite Features

The Determine MNP Lookup Number feature is an initial trigger feature used to configure a subsequent execution of the MNP Lookup Feature. The feature extracts one of the CalledPartyNumber, CallingPartyNumber, or CalledPartBCDNumber from a CAP InitialDP, or the subscriber from session state, and saves it for later use.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

InitialDP which triggered this session, from which the lookup number will be read

Report featureCannotStart

CallType

com.opencloud.sentinel.common.CallType

Session type of this call for determining from configuration which party address to lookup

Report featureCannotStart

Outputs

Name Type Format Description

MNPLookupNumber

String

MSISDN string

The subscriber address to perform the MNP Lookup for

Error scenarios

Scenario Handling

Missing entry in DetermineMNPLookupNumberConfigProfileTable

Report featureCannotStart

Sessionstate InitialDPArg is null

Report featureCannotStart

Sessionstate InitialDPArg not CAP

Report featureCannotStart

Sessionstate CallType is null

Report featureCannotStart

No configured lookup party for call scenario

Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

invalid or missing configuration

featureHasFinished

feature has finished

Configuration

The Determine MNP Lookup Number configuration includes:

Parameters Type Description

MobileOriginatingParty

LookupPartyEnum

The party to use for the subsequent ATI Lookup (via the MNP Lookup Feature) for mobile originating calls

MobileTerminatingParty

LookupPartyEnum

The party to use for the subsequent ATI Lookup (via the MNP Lookup Feature) for mobile terminating calls

MobileForwardedParty

LookupPartyEnum

The party to use for the subsequent ATI Lookup (via the MNP Lookup Feature) for mobile forwarded calls

Each LookupPartyEnum property may be set to one of the following values:

Value name Description

CallingPartyNumber

Indicates to set the MNP Lookup number from the InitialDP.CallingPartyNumber

CalledPartyNumber

Indicates to set the MNP Lookup number from the InitialDP.CalledPartyNumber

CalledPartyBCDNumber

Indicates to set MNP ATI Lookup number from the InitialDP.CalledPartyBCDNumber

SessionSubscriber

Indicates to set the MNP Lookup number from the sentinel session subscriber. Using this value requires a previous execution of the SS7 Subscriber Determination Feature

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

DetermineMNPLookupNumberConfigProfileTable

Feature configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The feature is provisioned using the web interface.

Determine SRI Lookup Number Feature

Description

Feature name

DetermineSRILookupNumber

Applicable contexts

SS7 service

SAS Support

No

Prerequisite features

The Determine SRI Lookup Number feature is an initial trigger feature used to configure a subsequent execution of the SRI for Basic Call Routing Feature. The feature extracts one of the CalledPartyNumber, CallingPartyNumber, or CalledPartBCDNumber from a CAP InitialDP, or the subscriber from session state, and saves it for later use.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

InitialDP which triggered this session, from which the lookup number will be read

Report featureCannotStart

CallType

com.opencloud.sentinel.common.CallType

Session type of this call for determining from configuration which party address to lookup

Report featureCannotStart

Outputs

Name Type Format Description

SRILookupNumber

String

MSISDN string

The subscriber address to perform the SRI Lookup for

Error scenarios

Scenario Handling

Missing entry in DetermineSRILookupNumberConfigProfileTable

Report featureCannotStart

Sessionstate InitialDPArg is null

Report featureCannotStart

Sessionstate InitialDPArg not CAP

Report featureCannotStart

Sessionstate CallType is null

Report featureCannotStart

No configured lookup party for call scenario

Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

invalid or missing configuration

featureHasFinished

feature has finished

Configuration

The Determine SRI Lookup Number configuration includes:

Parameters Type Description

MobileOriginatingParty

LookupPartyEnum

The party to use for the subsequent SRI Lookup (via the SRI for Basic Call Routing Feature) for mobile originating calls.

MobileTerminatingParty

LookupPartyEnum

The party to use for the subsequent SRI Lookup (via the SRI for Basic Call Routing Feature) for mobile terminating calls.

MobileForwardedParty

LookupPartyEnum

The party to use for the subsequent SRI Lookup (via the SRI for Basic Call Routing Feature) for mobile forwarded calls.

Each LookupPartyEnum property may be set to one of the following values:

Value name Description

CallingPartyNumber

Indicates to set the SRI Lookup number from the InitialDP.CallingPartyNumber

CalledPartyNumber

Indicates to set the SRI Lookup number from the InitialDP.CalledPartyNumber

CalledPartyBCDNumber

Indicates to set the SRI Lookup number from the InitialDP.CalledPartyBCDNumber

SessionSubscriber

Indicates to set the SRI Lookup number from the Sentinel session subscriber. Using this value requires a previous execution of the SS7 Subscriber Determination Feature.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

DetermineSRILookupNumberConfigProfileTable

Feature configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The feature is provisioned using the web interface.

Flash SMS Notification Feature

This feature is a pre-credit-check, post-credit-check, or end-session feature.

Description

Feature name

FlashSms

Applicable contexts

  • SS7 service

SAS Support

No * Diameter service * SIP service

Prerequisite features

A feature to set the NotificationMessage and NotificationAddress session state variables

The notification information will be accessed from the NotificationMessage session state variable which was set by a prior feature. The supported data coding schemes are GSM_7BIT and UCS2 — the message will be sent using the GSM_7BIT coding scheme if it can be represented in the 7-bit alphabet; otherwise, the UCS2 coding scheme will be used.

The notification message will be sent to (in order of precedence):

  • Address in NotificationAddress session state variable (if set)

  • Address in Subscriber session state variable.

If neither of these variables are set then the message will not be sent.

The feature checks the IMSI and MSCAddress session state fields. When both are set the feature will not perform an SendRoutingInformationForSM but use the MSCAddress session state field instead.

Note MTForwardSM will return success if the handset is available and message delivered. If it’s not, then a error response will be returned that the message was not deliverable (absent subscriber, and so on). As the call is either in progress or has just ended, the message will be deliverable in the vast majority of cases so no special behaviour is required in the error cases after sending MTForwardSM. Sentinel will not attempt to retry sending the message if there is an error delivering the message for any reason.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Increment SmsDeliveryFailures, return

IMSI

String

IMSI

The subscriber’s IMSI address, which may require an SRI lookup if null

Perform an SRI lookup

MSCAddress byte[]

SCCP address

The subscriber’s current MSC address, which may require an SRI lookup if null

Perform an SRI lookup

NotificationMessage

String

Arbitrary text

The textual content of the flash SMS

Increment SmsDeliveryFailures, return

NotificationAddress

String

MSISDN

The flash SMS destination address

Fall back to session state Subscriber address

Subscriber

Outputs

Name Type Format Description

IMSI

String

IMSI

Determined through SRI lookup if previously null

MSCAddress

byte[]

SCCP address

Determined from SRI lookup if previously null

Error scenarios

This table applies if an SRI is required:

Scenario Handling

Null sessionstate selection key

Increment SmsDeliveryFailures

Missing entry in FlashSmsFeatureConfigProfileTable

Increment SmsDeliveryFailures

No notification address or subscriber address

Increment SmsDeliveryFailures

Null TemplateHlrSccpAddress in FlashSMS config

Increment SmsDeliveryFailures

Exception sending SRI

Increment SmsDeliveryFailures

OpenRefuse from HLR

Increment HlrSS7ProviderErrors or HlrSS7UserErrors
Increment SmsDeliveryFailures
Close dialog
Increment HlrSS7Errors

Abort from HLR

Increment HlrProviderAborts or HlrUserAborts
Increment SmsDeliveryFailures
Increment HlrAbortsReceived

Timeout waiting for HLR response

Increment HlrTimeouts
Increment HlrSS7ProviderErrors or HlrSS7UserErrors
Increment SmsDeliveryFailures
Close dialog

Exception closing dialog in any HLR dialog failure scenario

Increment SmsDeliveryFailures
Increment HlrSS7Errors

This table applies if the SRI succeeds or is not required:

Scenario Handling

No notification address or subscriber address in sessionstate

Increment SmsDeliveryFailures

Null sessionstate MSCAddress

Increment SmsDeliveryFailures

Null sessionstate IMSI

Increment SmsDeliveryFailures

Null sessionstate NotificationMessage

Increment SmsDeliveryFailures

Exception sending mtForwardSM request

Increment SmsDeliveryFailures

MessageEncodingFailure sending mtForwardSM request

Increment SmsDeliveryFailures
Increment EncodingFailure

OpenRefuse from MSC

Increment MscSS7ProviderErrors
or MscSS7UserErrors
Increment SmsDeliveryFailures
Close dialog
Increment MscSS7Errors

Abort from MSC

Increment MscProviderAborts or MscUserAborts
Increment SmsDeliveryFailures
Increment MscAbortsReceived

Timeout waiting for MSC response

Increment MscTimeouts
Increment MscSS7ProviderErrors or MscSS7UserErrors
Increment SmsDeliveryFailures
Close dialog

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

The Flash SMS Notification configuration includes:

Parameter Type Description

SccpOriginatingAddress

SCCP address

Will be used as the TCAP Calling Party Address in dialogs initiated towards the HLR and MSC. May be null in which case the local SCCP address configured for the platform will be used. Example: type=c7,ri=gt,digits=34607012345,nature=national,national=true

InvokeTimeout

Long

SRIforSM and MTForwardSM invoke timeouts in milliseconds (for example, 5000). A 0 value results in CGIN RA defaults being used.

TemplateHlrSccpAddress

SCCP address

A template address that will be used to address the HLR. Global title digits in the template address will be replaced with the relevant notification address. The encoding scheme will also be updated, if relevant for the GT indicator type, to indicate BCD_ODD or BCD_EVEN, depending on the number of address digits.

TemplateMscSccpAddress

SCCP address

A template address that will be used to address the MSC. Global title digits in the template address will be replaced with the MSC address from session state. The encoding scheme will also be updated, if relevant for the GT indicator type, to indicate BCD_ODD or BCD_EVEN, depending on the number of address digits.

SMSAddressOriginatingAddress

SMSAddress

Local SCCP address (for example, address=64600000002,nature=INTERNATIONAL,numberingPlan=ISDN)

AddressStringServiceCentreAddress

AddressString

Service centre address (for example, address=643434,nature=INTERNATIONAL,numberingPlan=ISDN)

ShortMsgMTApplicationContext

TcapApplicationContext

The MAP application context to be used for the dialog towards the MSC. Must be one of:

  • shortMsgMT-RelayContext-v1-ac

  • shortMsgMT-RelayContext-v2-ac

  • shortMsgMT-RelayContext-v3-ac

  • shortMsgMT-Relay-VGCS-Context-v3-ac

Call flow

There are two MAP requests as party of the MTForwardSM process:

  1. Obtaining the routing information from the HLR.

  2. Sending the MT SMS.

The first step is performed by sending an SendRoutingInformationForSM request to the HLR to determine the routing information for the MT Forward SM. This step is not performed if the IMSI and MSCAddress session state fields are set.

The HLR SCCP Address will be based on the MSISDN of the subscriber. (See MAP SPEC Section 4 Requirements concerning the use of SCCP and TC/4.1.3.3 The Home Location Register (HLR) — refer to MAP SPEC footnote). The MSISDN will be retrieved from SessionState.NotificationAddress or SessionState.Subscriber.

hlrSccpAddress.address={SessionState.NotificationAddress or SessionState.Subscriber)
hlrSccpAddress.nature=International
hlrSccpAddress.numberingPlan=ISDN
hlrSccpAddress.routingIndicator=(GT for extra/inter-PLMN, GT or SPC for intra-PLMN) default 0 (GT)
hlrSccpAddress.GTI=0100 (Global title indicator = 0100 (Global title includes translation type, numbering plan, encoding scheme and nature of address indicator)
hlrSccpAddress.type=C7
hlrSccpAddress.ssnIndicator=1 (MAP SSN always included)
hrlSccpAddress.ssn=(configured per network) default 6
hrlSccpAddress.pc=(configured per network) default not set
hlrSccpAddress.tt=0 (not used)
imsi = RoutingInfoForSM-Res.imsi
msc-number = RoutingInfoForSM-Res.locationInfoWithLMSI.networkNode-Number
IF RoutingInfoForSM-Res.locationInfoWithLMSI.gprsNodeIndicator not present OR
   (RoutingInfoForSM-Res.locationInfoWithLMSI.gprsNodeIndicator present AND
    RoutingInfoForSM-Res.LocationInfoWithLMSI.additional-Number is sgsn-Number) THEN
    mscAddress = RoutingInfoForSM-Res.LocationInfoWithLMSI.networkNode-Number
else
    mscAddress = RoutingInfoForSM-Res.LocationInfoWithLMSI.additional-Number
Note RoutingInfoForSM-Res.locationInfoWithLMSI.networkNode-Number renamed from msc-Number between R96 and R97. The networkNode-number can also contain an sgsn-number or IP-SM-GW number or SMS Router number.

The second step is to send the MTForwardSM:

Field Value

destination SCCP address

msc-number from the SRIforSM or MSCAddress session state field

sm-RP-DA.imsi

use the imsi from the SRIforSM or the IMSI session state field

sm-RP-OA.serviceCentreAddress

Sentinel address for response messages

sm-RP-UI

SMSDeliver as below

moreMessagesToSend

not set

extensionContainer

not set

smDeliveryTimer

not set

smDeliveryStartTime

not set

SMSDeliver:

Field Value

onlyHeader

not set

replyPath

false

userDataHeaderIndicator

true

statusReportIndication

false

moreMessagesToSend

NONE

loopPrevention

false

originatingAddress

configurable address — probably some service number

protocolId

0 (TelematicDevice.IMPLICIT)

dataCodingScheme

{MessageClass=SPARE_0, MessageCoding determined by encoded text, supports GSM_7BIT or UCS2}

serviceCentreTimeStamp

current time

userDataLength

length of encoded text based on data coding scheme

userData

encoded text

The SMS PDU of the message sent will be taken from the notification session state variables.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

FlashSmsFeatureConfigProfileTable

Selection of database implementation and rating group for the feature.

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The feature is provisioned using the web interface.

MAP SPEC

Digital cellular telecommunications system (Phase 2+); Mobile Application Part (MAP) specification (3GPP TS 09.02 version 5.17.0 Release 1996)

ETSI/3GPP

2002-03

ETSI

MNP Lookup Feature

Description

Feature name

MNPLookup

Applicable contexts

SS7 service

SAS Support

No

Prerequisite features

Determine MNP Lookup Number Feature

The MNP (Mobile Number Portability) Lookup Feature performs a MAP AnyTimeInterrogation MNP lookup based on the address selected by a previous execution of the Determine MNP Lookup Number Feature. The MNP ATI destination HLR is determined by the configuration associated with the feature. The party to look up is based on the MNPLookupNumber saved into session state by the Determine MNP Lookup Number Feature.

The MNP response is saved in the sentinel session state.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Increment SendFailures stat Report featureFailedToExecute Return

MNPLookupNumber

String

MSISDN

Address to perform the MNP lookup for

Increment SendFailures stat Report eatureFailedToExecute Return

Outputs

Name Type Format Description

MNPInfo

com.opencloud.slee.resources.cgin.map.MAPMNPInfoRes

MAP-MS-DataTypes.MNPInfoRes

The MNP lookup result

Error scenarios

Scenario Handling

Missing entry in MNPLookupFeatureConfigProfileTable

Increment SendFailures stat
Report featureFailedToExecute

Null sessionstate MNPLookupNumber

Increment SendFailures stat
Report featureFailedToExecute

Error parsing MNPLookupNumber

Increment SendFailures stat
Report featureFailedToExecute

Null MNPSRFSccpAddress configured in MNPLookupFeatureConfigProfileTable

Increment SendFailures stat
Report featureFailedToExecute

Null GSMSCFAddressString configured in MNPLookupFeatureConfigProfileTable

Increment SendFailures stat
Report featureFailedToExecute

Exception while trying to send ATIRequest

Increment SendFailures stat
Report featureFailedToExecute

OpenRefuse from MNP SRF

Close dialog Increment SS7ProviderErrors or SS7UserErrors

Abort from MNP SRF

Close dialog
Increment SS7Aborts

Timeout waiting for MNP SRF response

Close dialog
Increment SS7Timeouts

Feature responses

Response Reason

featureFailedToExecute

Missing sessionstate or configuration data, exception while sending ATIRequest or error response from MNP SRF

featureHasFinished

feature has finished

Configuration

The MNP Lookup configuration includes:

Parameters Type Description

OriginatingSccpAddress

SCCP address

Will be used as the TCAP Calling Party Address in dialogs initiated towards the HLR and MSC. May be null in which case the local SCCP address configured for the platform will be used. Example: type=c7,ri=gt,digits=34607012345,nature=national,national=true

InvokeTimeout

Long

AnyTimeInterrogation invoke timeout in milliseconds (for example, 5000). A 0 value results in CGIN RA defaults being used.

GSMSCFAddress

AddressString

Return address for responses (for example, address of Sentinel)

MNPSRFSccpAddress

SCCP address

Static address of an MNP SRF.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

MNPLookupFeatureConfigProfileTable

Feature configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning Interfaces

The feature is provisioned using the Sentinel web interface.

SRI for Basic Call Routing Feature

Description

Feature name

SRIForBasicCallRouting

Applicable contexts

SS7 service

SAS Support

No

Prerequisite features

Determine SRI Lookup Number Feature

The SRI For Basic Call Routing feature performs a MAP SendRoutingInformation lookup based on the address selected by a previous execution of the Determine SRI Lookup Number Feature. The SRI request contents and destination HLR are determined by the configuration associated with the feature.

The SRI response is saved in the SendRoutingInfoRes field defined in the com.opencloud.sentinel.feature.common.sribasiccall.SRIForBasicCallRoutingSessionState Sentinel session state interface.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Increment SendFailures stat Report featureFailedToExecute Report featureHasFinished Return

SRILookupNumber

String

MSISDN

Address for which to perform SRI lookup

Return

Outputs

Name Type Format Description

SendRoutingInfoRes

com.opencloud.slee.resources.cgin.map.MAPSendRoutingInfoRes_v3

MAP-CH-DataTypes.SendRoutingInfoRes-v3

The result of the SRI lookup

Error scenarios

Scenario Handling

Missing profile entry in SRIForBasicCallRoutingFeatureConfigProfileTable

Increment SendFailures stat
Report featureFailedToExecute
Report featureHasFinished

Exception creating MSISDN string using sessionstate SRILookupNumber

Report featureHasFinished

Null HLRAddress or GsmScfAddress in config profile

Increment SendFailures stat
Report featureFailedToExecute
Report featureHasFinished

Exception sending SRI request to HLR

Increment SendFailures stat
Report featureFailedToExecute
Report featureHasFinished

OpenRefuse from HLR

Close dialog
Increment SS7ProviderErrors or SS7UserErrors
if sriConfig.failOnError report featureFailedToExecute
Report featureHasFinished

Abort from HLR

Close dialog
Increment SS7Aborts
if sriConfig.failOnError report featureFailedToExecute
Report featureHasFinished

Timeout waiting for HLR response

Close dialog
Increment SS7Timeouts
if sriConfig.failOnError report featureFailedToExecute
Report featureHasFinished

Feature responses

Response Reason

featureHasFinished

feature has finished

featureFailedToExecute

unclassified

Session State interface

Uses the SRILookupNumber as the MSISDN for the query. If this is not set the feature continues without affecting the call.

The SendRoutingInfoRes result is stored in the SendRoutingInfoRes field defined in the com.opencloud.sentinel.feature.common.sribasiccall.SRIForBasicCallRoutingSessionState session state interface.

The IMSI from the SendRoutingInfoRes is stored in the IMSI field defined in the com.opencloud.sentinel.common.ImsiSessionState session state interface.

Configuration

The SRI For Basic Call Routing configuration includes:

Parameters Type Description

SccpOriginatingAddress

SCCP address

Will be used as the TCAP Calling Party Address in dialogs initiated towards the HLR and MSC. May be null in which case the local SCCP address configured for the platform will be used. Example: type=c7,ri=gt,digits=34607012345,nature=national,national=true

InvokeTimeout

Long

SendingRoutingInformation invoke timeout in milliseconds (for example, 5000). A 0 value results in CGIN RA defaults being used.

Map3Supported

Boolean

if ‘true’ will use locationInfoRetrievalContextv3-ac, if ‘false’ locationInfoRetrievalContext-v2-ac

HLRAddress

SCCP address

HLR address for the SRI

GSMSCFAddress

AddressString

Return address for responses (e.g. Sentinel address)

PrePagingSupported

Boolean

When true sets the Pre_pagingSupported flag in the SRI

FailOnError

Boolean

When true the feature will respond on error with a featureFailedToExecute to the Sentinel core, when false the feature will continue without reporting error to the core.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SRIForBasicCallRoutingFeatureConfigProfileTable

Feature configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The feature is provisioned using the web interface.

USSD Push Notification Feature

Description

Feature name

USSDNotification

Applicable contexts

  • SS7 service

SAS Support

No * Diameter Service * SIP Service

Prerequisite features

  • Optional: Any feature which sets NotificationMessage

  • Optional: Any feature which sets NotificationAddress

The USSD Push Notification feature is a pre-credit-check, post-credit-check, or end-session feature early in the feature list. It always allows the session to continue even in the event of a feature execution failure.

The notification information will be accessed from the NotificationMessage session state variable which was set by a prior feature. If no message has been set, the SendFailures usage stat is incremented and the feature ends.

The notification message will be sent to (in order of precedence):

  • Address in NotificationAddress session state variable (if set)

  • Address in Subscriber session state variable

If neither of these variables are set then the message will not be sent.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

Sentinel?SelectionKey

com.?opencloud.?sentinel.?common.?Sentinel?SelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Increment SendFailures Return

NotificationMessage

String

Arbitrary text

The text content of the outgoing USSD notification

Increment SendFailures Return

NotificationAddress

String

MSISDN

The destination address of the outgoing USSD notification

Fall back to Subscriber session state field

Subscriber

String

MSISDN

The destination address of the outgoing USSD notification if NotificationAddress is null

Increment SendFailures Return

Outputs

This feature does not write to session state.

Error scenarios

Scenario Handling

Missing configuration profile in USSDNotificationFeatureConfigProfileTable

Increment SendFailures

Null sessionstate NotificationMessage

Increment SendFailures

Null sessionstate NotificationAddress

Increment SendFailures

Could not create destination MSISDN from NotificationAddress

Increment SendFailures

Could not create SccpAddress from NotificationAddress

Increment SendFailures

USSD message encoding failed

Increment EncodingFailures

Failed to send unstructured SS notify request

Increment SendFailures

OpenRefuse from HLR

Increment HlrProviderErrors or HlrUserErrors

Abort from HLR Increment

HlrAborts

Timeout waiting for HLR response

Increment HlrTimeouts

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

The USSD Push Notification configuration includes:

Parameters Type Description

SccpOriginatingAddress

SCCP address

Will be used as the TCAP Calling Party Address in dialogs initiated towards the HLR and MSC. May be null in which case the local SCCP address configured for the platform will be used. Example: type=c7,?ri=gt,?digits=34607012345,?nature=national,?national=true

InvokeTimeout

Long

UnstructuredSS_Notify invoke timeout in milliseconds (for example, 5000). A 0 value results in CGIN RA defaults being used.

UssdDataEncodingScheme

Byte

USSD data encoding scheme. Currently must be 15 (coding scheme must be 0x0f (0000 1111) GSM 7 bit language unspecified)

WaitForConfirmation

Boolean

true/false, when true will wait for the response from the HLR, if false will proceed with feature execution immediately

Call flow

ussd push notification interaction diagram

The HLR SCCP Address will be based on the MSISDN of the subscriber (See MAP SPEC, Section 4, concerning the use of SCCP and TC/4.1.3.3 The Home Location Register (HLR) — refer to MAP SPEC footnote below).

hlrSccpAddress.address={SessionState.NotificationAddress or SessionState.Subscriber)
hlrSccpAddress.nature=International
hlrSccpAddress.numberingPlan=ISDN
hlrSccpAddress.routingIndicator=(GT for extra/inter-PLMN, GT or SPC for intra-PLMN) default 0 (GT)
hlrSccpAddress.GTI=0100 (Global title indicator = 0100 (Global title includes translation type, numbering plan, encoding scheme and nature of address indicator)
hlrSccpAddress.type=C7
hlrSccpAddress.ssnIndicator=1 (MAP SSN always included)
hrlSccpAddress.ssn=(configured per network) default 6
hrlSccpAddress.pc=(configured per network) default not set
hlrSccpAddress.tt=0 (not used)
The USSD String of the message sent will be taken from the notification session state variables.
The ProcessUnstructuredSS_Request will include the MSISDN of the subscriber taken from the IDP.

  • In WaitForConfirmation true mode, the feature will immediate return continue once the notify request is sent and will not wait for the response.

  • In WaitForConfirmation false mode, the feature will return when one of the following occurs:

    • the response is received

    • a MAP error is reported

    • the invoke times out (ProviderError(NO_RESPONSE) is received

    • the dialog is aborted.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

USSD?Notification?Feature?Config?Profile?Table

Feature configuration

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The feature is provisioned using the web interface.

MAP SPEC

Digital cellular telecommunications system (Phase 2+); Mobile Application Part (MAP) specification (3GPP TS 09.02 version 5.17.0 Release 1996)

ETSI/3GPP

2002-03

ETSI

CAMEL Features

Sentinel includes many features for CAMEL networks:

Accept Protocol Feature

This feature allows the dialog processing to proceed if the application context is acceptable.

Description

Feature name

AcceptProtocol

Applicable contexts

SS7 Service

SAS Support

No

Prerequisite features

None

Dialogs with unacceptable application contexts are refused with the reason code USER_ACN_NOT_SUPPORTED.

The acceptable application contexts are:

  • cap_v1_gsmSSF_to_gsmSCF-AC

  • cap-v2-gsmSSF-to-gsmSCF-AC

  • capssf_scfGenericAC (CAP3)

  • cap3_sms_AC

This feature also sets the SessionType parameter to call or sms.

The feature notifies the Sentinel core if the dialog is a voice (includes data, video fax) or sms dialog.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Runtime exception handled by feature runner

Outputs

Name Type Format Description

SessionType

com.opencloud.sentinel.common.SessionType

One of: call, sms

Session type determined from application context

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>:<network>:<session type>::)

Updated selection key including session type determined from application context

Protocol

com.opencloud.sentinel.common.SentinelProtocol

One of: cap_v1, cap_v2, cap_v3, cap_v4, etsi_inap_cs1, map_rel4, call_control

Session protocol determined from application context

Error scenarios

Scenario Handling

Trigger not instance of DialogOpenRequestEvent

Report featureCannotStart

Feature responses

Response Reason

refuseDialog

User ACN not supported

featureCannotStart

Trigger event is not a DialogOpenRequestEvent

markSessionType

mark the session type (one of: call, sms, diametermediation, sipcall, unset) in session state

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Call Barring Feature

The Call Barring feature is a network operator barring feature. That is, it is intended for barring/allowing calls to specific numbers at network and plan scope.

Description

Feature name

CallBarring

Applicable contexts

SS7 service

SAS Support

No

Prerequisite features

It is run pre credit check, early in the feature list (but always after the emergency number feature). If the barring algorithm returns a match, then the feature returns an instruction to the Sentinel core to release the call and close with no further intervention from Sentinel.

The default release cause value is CLASS1_CALL_REJECTED. This value may be overridden by configuration.

Note This feature is for network operator wide barring. It is not a per subscriber barring feature.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, '<platform>::::')

For selecting configuration data

Report featureCannotStart, featureHasFinished

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

InitialDP which triggered this session, from which the CalledPartyBCDNumber will be read

Report featureCannotStart, featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Barring will only be performed for mobile originating calls

Report featureCannotStart, featureHasFinished

Outputs

This feature does not write to session state.

Error scenarios

Scenario Handling

Trigger not instance of DialogOpenRequestEvent

Report featureCannotStart

Null sessionstate SentinelSelectionKey

Report featureCannotStart

InitialDP not CAP

Report featureCannotStart

Null sessionstate CallType

Report featureCannotStart

InitialDP does not contain a CalledPartyBCDNumber

Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

SessionState SentinelSelectionKey is not set, protocol is not CAP, session type has not been set, or InitialDP does not contain a CalledPartyBCDNumber

releaseCallAndCloseDialog

call is barred

featureHasFinished

feature has finished

Determining if a call is to be barred

The Call Barring feature analyses the InitialDP to determine whether to request barring of the call:

IF call is not a mobile originating call THEN
    do not barr call
    RETURN
ENDIF

IF idp.calledPartyBCDNumber does not match using longest prefix match in block list THEN
    do not barr call
    RETURN
ENDIF

IF idp.calledPartyBCDNumber does not match using longest prefix match in allow list THEN
        barr call
    RETURN
ENDIF

do not barr call

Triggers and application contexts

Application Contexts:

  • cap-v2-gsmSSF-to-gsmSCF-AC

  • capssf_scfGenericAC (CAP3).

The InitialDP will be triggered on DP2 (Collected_Info).

Typical call flow

  • MSC ---- OpenRequest -→ Sentinel

  • MSC ---- IDP(Cdpn=123) -→ Sentinel

  • MSC ←-- OpenAccept --- Sentinel

  • MSC ←-- Release(cause) --- Sentinel

Configuration

The CallBarring feature configuration profile includes the following attributes:

Parameters Type Description

ReleaseCause

Integer

Release cause to be set for barred calls

The feature also maintains two Sentinel address lists: a block list and an allow list containing the barring configuration. Numbers are matched using longest prefix.

  • The block list defines numbers to be barred.

  • The allow list defines numbers to be allowed and overrides the block list.

The feature applies the barring configuration to all subscribers with the matching Sentinel selection key.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

CallBarringFeatureConfigProfileTable

CallBarring feature configuration parameters

SentinelSelectionKey (for example, OpenCloud::::)

Block and Allow List configuration profile naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:CallBarring:BlockList or ${SELECTIONKEY}:CallBarring:AllowList

${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable Feature specific

Address List entry table

${SELECTIONKEY}:CallBarring:BlockList:${ADDRESS}, ${SELECTIONKEY}:CallBarring:AllowList:${ADDRESS}

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

Call Forwarding Detection Feature

Description

Feature script name

CallForwardingDetection

Applicable contexts

SS7 service

SAS Support

No

Prerequisite Features

ClassifyCallScenario

The CallForwardingDetection feature analyses an MT initialdp to determine if early call forwarding applies for this call. If call forwarding is pending, the call will be allowed to continue with no charging or monitoring of the call.

This feature prevents an unnecessary credit check with the OCS and unnecessary monitoring of the call when the outcome is already determined.

IF initialdp.gsm-forwardingPending is set AND initialdp.gsm-forwardingPending is true THEN
   instruct call to continue with no monitoring and no charging.
ELSE
   allow the call to proceed without any affect from this feature
ENDIF
If the SessionType of the call is not MobileTerminating then this feature must end without affecting the call.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

InitialDPArg

com.opencloud.slee.resources.cgin.callcontrol.CCInitialDPArg

InitialDP which triggered this session.

If CAP1, the call is not eligible for forwarding detection. If CAP2 or higher, it is eligible.

Report featureCannotStart, featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call — if MobileTerminating, the call is eligible for call forwarding detection

Assume eligibility for call forwarding detection

Outputs

This feature does not write to session state.

Feature responses

Response Reason

doNotMonitorSession

if call is a MT call and hasGsm_ForwardingPending is set

doNotChargeSession

if call is a MT call and hasGsm_ForwardingPending is set

featureHasFinished

feature has finished

Interaction with call forwarding supplementary service

The gsm-forwardingPending indicator will be present when the GMSC has determined one of the following applies:

  • unconditional call forwarding or conditional call forwarding not

  • call forwarding not reachable — MS switched off

  • call forwarding not reachable — no paging response.

For more information, see Noldus 4.3.2.1 Early Call Forwarding. (Refer to Noldus footnote below.)

OCS interface

No interaction with OCS from this feature except via MFC.

Triggers and application contexts

Application Contexts:

  • cap-v2-gsmSSF-to-gsmSCF-AC

  • capssf_scfGenericAC (CAP3)

The InitialDP will be triggered on DP12 (Terminating_ Attempt_Authorized).

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

NOLDUS

CAMEL INTELLIGENT NETWORKS FOR THE GSM, GPRS AND UMTS NETWORK

Rogier Noldus

2006

John Wiley & Sons, Ltd

Classify Call Scenario Feature

Description

Feature name

ClassifyCallScenario

Applicable contexts

SS7 service

SAS Support

No

Prerequisite Features

None

The Classify Call feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature classifies the call’s Session Type, Roaming Indicator, and Service Type, which are stored in session state variables for future features.

Session type

The call’s session type is classified as one of:

  • MobileOriginating

  • MobileTerminating

  • MobileForwarded.

A CallType enum is defined to represent the values, and the session type is stored in session state variable CallType.

The session type is determined based on the following pseudo code:

Function DetermineSessionType(initialDP)

    /* make an assumption on insufficient information that originating */
    IF initialDP.eventTypeBCSM not set
    THEN
        return MobileOriginating
    ENDIF

    /* Originating or terminating eventTypeBCSM? */
    IF initialDP.eventTypeBCSM is one of {origAttemptAuthorized, collectedInfo, analyzedInformation, routeSelectFailure,
                                          oCalledPartyBusy, oNoAnswer, oAnswer,  oMidCall,oDisconnect, oAbandon}
    THEN
        isOriginatingEventTypeBCSM = true
    ELSE
        isOriginatingEventTypeBCSM = false
    ENDIF

    IF NOT isOriginatingEventTypeBCSM
    THEN
        return MobileTerminating
    ENDIF

    IF isOriginatingEventTypeBCSM AND initialDP.redirectingPartyID is set
    THEN
        return MobileForwarded
    ENDIF

    IF isOriginatingEventTypeBCSM AND initialDP.redirectingPartyID not set
    THEN
        return MobileOriginating
    ENDIF

    return Unknown

Roaming indicator

The call’s roaming indicator is classified as one of:

  • Roaming

  • NotRoaming.

The roaming indicator is stored in session state variable RoamingIndicator as a Boolean.

The roaming indicator is determined based on the following pseudo code:

Function DetermineRoaming(initialDP)
    IF initialDP.LocationInformation.VLR-Number prefix in (operator VLR number prefix list) THEN
       return isNotRoaming
    ELSE
       return isRoaming
    ENDIF
Note

In the case of an MT call, the location information may be reported; but this is dependent on an HLR setting (MAP PSI during MT processing).

For MO calls, the LocationInformation relates to the calling party. For the MT case, it relates to the called party.

The feature maintains a profile address list of home VLR numbers. If the VLR number is in this list, the call is not roaming.

Service type

The call’s service type is classified as one of:

  • Voice

  • Video

  • Data

  • Fax

A ServiceType enum is defined to represent the values, and the service type is stored in session state variable ServiceType.

The service type is determined based on the following pseudo code:

Function DetermineServiceType(initialDP)

    IF initialDP.ext-basicServiceCode == ext-Teleservice THEN

       CASE initialDP.ext-basicServiceCode.ext-Teleservice
           Telephony(11):
           EmergencyCalls(12):
           VoiceGroupCall(91):
           VoiceBroadcast(92):
               return VOICE
           Alternate speech and fax group 3(61):
           Automatic fax group 3(62):
               return FAX
       ENDCASE

    ENDIF

    IF initialDP.ext-basicServiceCode is ext-BearerService THEN
        IF initialDP.ext-basicServiceCode.ext-BearerService == Asynchronous data bearer services (30) THEN
           return VIDEO
        ELSE IF initialDP.ext-basicServiceCode.ext-BearerService == synchronous data bearer services (20) THEN
           return DATA
        ENDIF
    ENDIF

    /* assume voice if no match */
    return VOICE

Session State inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP1InitialDPArg

InitialDP which triggered this session, which will be analysed to classify the session

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

The type of this session

RoamingIndicator

Boolean

true if roaming, false if non-roaming or indeterminate

Indicates whether this call is roaming or non-roaming

ServiceType

com.opencloud.sentinel.common.ServiceType

One of: Voice, Data, Fax, Video, Unknown

Indicates the service type of this session

Error scenarios

Scenario Handling

Null sessionstate InitialDPArg

Report featureCannotStart

Null sessionstate SentinelSelectionKey

Report featureCannotStart

InitialDPArg not CAP

Report featureCannotStart

Session type could not be determined

featureFailedToExecute

Roaming status could not be determined

featureFailedToExecute

Service type could not be determined

featureFailedToExecute

Feature responses

Response Reason

featureCannotStart InitialDP has not been set in session state, SessionState Sentinel

SelectionKey is not set or InitialDP is not CAP

featureFailedToExecute

unclassified error

featureHasFinished

feature has finished

Configuration

The ClassifyCall feature configuration consists of the BearerService and TeleService configuration profiles.

BearerService configuration

Parameter Type Description

BearerServiceCode

Integer

The bearer service value

BearerService

ServiceType

The ServiceType associated with the bearer service value

TeleService configuration

Parameter Type Description

TeleServiceCode

Integer

The tele service value

TeleService

ServiceType

The ServiceType associated with the tele service value

Each ServiceType attribute can be one of the following: Voice, Data, Fax, Video, Unknown.

For roaming determination, Classify Call uses an address list for matching VLR addresses. See Address Lists for how to configure data for the address list.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:ClassifyCallScenario:HomeVLR

${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable Feature specific

Address List entry table

${SELECTIONKEY}:ClassifyCallScenario:HomeVLR:${ADDRESS}

BearerServiceConfigProfileTable

BearerService configuration

SentinelSelectionKey + ':' + BearerServiceCode (for example, OpenCloud:::::32)

TeleServiceConfigProfileTable

TeleService configuration

SentinelSelectionKey + ':' + TeleServiceCode (for example, OpenCloud:::::45)

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

Closed User Group Feature

Description

Feature script name

ClosedUserGroup

Applicable contexts

SS7 service

SAS Support

No

Prerequisite features

The Closed User Group (CUG) feature indicates to the OCS any CUGs that apply to the current session, and optionally restricts a subscriber to sessions within a CUG. The subscriber can be a member of multiple groups, with the group sizes being a maximum of 1,000 entries. The feature has similar functionality to the CUG Closed User Group (CUG) Supplementary Services GSM TS 02.85.

CUG will also have the following features.

  • Supports MOC, MFC, MTC, Network-Initiated.

  • If feature is enabled for the subscriber, and there is no preferential CUG and no CUG specified, then reject the session.

  • The subscriber may provide a CUG index to select which CUG will override the preferential CUG for the session.

  • Set which AVPs and CDR fields contain the CUGs that the session matches. (AVPs presumed to be set by the mapper.)

Each CUG has the following attributes:

  • Rating group

  • Incoming Access (IA) — an arrangement which allows a member of a CUG to receive calls from outside the CUG

  • Outgoing Access (OA) — an arrangement which allows a member of a CUG to place calls outside the CUG.

Note

The ICB and OCB capabilities of the CUG Supplementary Service are not supported:

  • Incoming Calls Barred Within A CUG (ICB) — an access restriction that prevents a CUG member from receiving calls from other members of that group

  • Outgoing Calls Barred Within A CUG (OCB) — an access restriction that prevents a CUG member from placing calls to other members of that group.

Outgoing access

The CUG to use for a call will be determined as follows:

IF CUGToUse is not set AND subscriber's CUGPreferred is set THEN
   CUG for call is CUGPreferred
   RETURN
ENDIF

IF CUGToUse is set but invalid index for subscriber's CUGList THEN
   reject call
   RETURN
ENDIF

CUG for call is CUGList[CUGToUse]

The algorithm to check if the session is within a CUG:

IF numberToCheck exact or longest prefix matches in CUG table THEN
   add CUG name to sessionState.CUGMatchedList list
   add Rating group to sessionState CUGMatchedRatingGroupList list
ENDIF

The number to check include prefix matches:

Call type Number to check against CUG list

MOC

CalledPartyBCDNumber

MFC

CalledPartyNumber

MTC

CallingPartyNumber

NetworkInitiated(Callback)

Leg #4 Address

Emergency

N/A

MOSMS

DestinationSubscriberNumber

In all cases the normalised number will be used for the check.

The CUG feature will not include any logic to determine if the CUG entries are legal. This will be the requirement of the provisioning system.

Any errors encountered during the execution of this feature, such as configuration errors or missing subscriber data, will have no effect: no tariff will be set. The call will be allowed to continue with no effect to the call. (Dependent on error — the rule above specifies rejecting the call if invalid index.)

Session State inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

InitialDPArg which triggered this session if it is a call

Set ClosedUserGroupCall session state field to false (indicating that this is not a closed user group call)
Increment ClosedUserGroupSubscriberDataError
Report featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Determines how to perform CUG analysis

Report featureCannotStart, featureHasFinished

SessionType

com.opencloud.sentinel.common.SessionType

One of: call, sms

For mobile originating sessions, distinguish call or sms CUG analysis

Report featureCannotStart, featureHasFinished

CAP3InitialDPSMSArg

com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg

CAP-SMS-ops-args.InitialDPSMSArg

InitialDPSMSArg which triggered this session if it is an sms

Set ClosedUserGroupCallsession state field to false (indicating that this is not a closed user group call)
Increment ClosedUserGroupSubscriberDataError
Report featureHasFinished

ClosedUserGroupEnabled

Boolean

true or false

Whether the subscriber has closed user group support enabled

Equivalent behaviour if null or false
Increment ClosedUserGroupNotEnabled
Set ClosedUserGroupCall session state field to false
Report featureHasFinished

ClosedUserGroupList

String[]

Array of closed user group names

The closed user groups this subscriber belongs to

Increment ClosedUserGroupNotEnabled
Set ClosedUserGroupCall session state field to false
Report featureHasFinished

ClosedUserGroupPreferred

Integer

Any integer from 0 — ClosedUserGroupList.length

Indexes this subscriber’s preferred closed user group in their ClosedUserGroupList

Set ClosedUserGroupCall session state field to false
Report featureCannotStart
Increment ClosedUserGroupSubscriberDataError
Report releaseCallAndCloseDialog, featureHasFinished

ClosedUserGroupToUse

Integer

Null or any integer from 0 — ClosedUserGroupList.length

Index which overrides ClosedUserGroupPreferred if set

Set ClosedUserGroupSelectedGroupName session state field to ClosedUserGroupPreferred

Outputs

Name Type Format Description

ClosedUserGroupCall

Boolean

true or false

Indicates whether this session is a closed user group call

ClosedUserGroupSelectedGroupName

String

May be null if ClosedUserGroupCall is false or CUG analysis failed

Name of the selected closed user group

RatingGroup

Long

May be null if ClosedUserGroupCall is false or CUG analysis failed

ID of the selected rating group

Error scenarios

Scenario Handling

Null sessionstate SentinelSelectionKey

Report featureCannotStart

Null sessionstate CallType

Report featureCannotStart

Null sessionstate SessionType

Report featureCannotStart

Null sessionstate ClosedUserGroupPreferred

Report featureCannotStart
Increment ClosedUserGroupSubscriberDataError
Report releaseCallAndCloseDialog

SessionState: CUG preferred id is invalid

Set sessionstate ClosedUserGroupCall to false
Report featureCannotStart
Increment ClosedUserGroupSubscriberDataError
Report releaseCallAndCloseDialog

OtherPartyAddress could not be set successfully

Set sessionstate ClosedUserGroupCall to false
Increment ClosedUserGroupSubscriberDataError

No CUG Group was selected

Set sessionstate ClosedUserGroupCall to false
Increment NonClosedUserGroupCall Report releaseCallAndCloseDialog No CUG Profile was found for group

Feature responses

Response Reason

featureCannotStart

Invalid session state or configuration

releaseCallAndCloseDialog

CUG preferred ID is null, CUG preferred ID is invalid, no CUG Group was selected, call not allowed, or no CUG Profile was found for group

featureIssuedWarning

OtherPartyAddress has not been set or no CUG Group was selected

featureHasFinished

feature has finished

Configuration

Each ClosedUserGroup’s configuration includes:

a general configuration profile (1 entry):

Parameter Type Description

Name

String

Name of the the CUG

Description

String

Description of the CUG

RatingGroup

Long

Rating group to associate with the CUG

RestrictIncomingAccess

Boolean

Global per-subscriber override to restrict incoming calls from non-CUG members

RestrictOutgoingAccess

Boolean

Global per-subscriber override to restrict outgoing calls to non-CUG members

a list of numbers (configured as address lists; 0..N entries):

Parameter Values

Number

Normalized number

The CUG number list is provisioned in international format:

  • 6421678956

  • 6492324856

  • 64800123456 (0800 123456)

a per-subscriber configuration (held in session state and retrieved by, for example, the Subscriber Data Lookup Feature; 1 entry):

Parameter Type Values

CUGEnabled

Boolean

true/false

CUGPreferred

Integer

CUG Index (for example, 0)

CUGList

String[]

List of CUG names (for example, CUG1,CUG17,CUG_OPENCLOUD)

CUGIncomingAccessAllowed

Boolean

true/false

CUGOutgoingAccessAllowed

Boolean

true/false

OCS interface

In the case of Diameter Ro, a proprietary AVP will be set to indicate:

  • the specific CUG group tariff code(s) (SessionState.CUGTariffGroup)

  • the CUG name (SessionState.CUGName)

  • type of access (SessionState.CUGAccessType with values IntraCUG, IncomingAccess, OutgoingAccess)

The AVP mapping will be determined as part of the vendor-specific integration requirements for the OCS.

Triggers and application contexts

Application Contexts:

  • cap-v2-gsmSSF-to-gsmSCF-AC

  • capssf_scfGenericAC (CAP3)

The InitialDP will be triggered on DP2 (Collected_Info).

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

ClosedUserGroupCUGsProfileTable

CUG general configuration

${SELECTIONKEY}:${CUGName} (for example, OpenCloud:Opencloud::::CUG1Profile)

${PLATFORMOPERATOR}_Sentinel_AddressLisConfigurationTable

Address list configuration

${SELECTIONKEY}:ClosedUserGroup:${CUGName} (for example, OpenCloud:Opencloud::::ClosedUserGroup:CUG1Profile)

${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable

Feature specific Address List entry table

${SELECTIONKEY}:ClosedUserGroup:${CUGName}:${ADDRESS} (for example, OpenCloud:Opencloud::::ClosedUserGroup:CUG1Profile:34600000001)

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

Connect and Close Feature

Description

Feature name

ConnectAndClose

Applicable contexts

SS7 Service

SAS Support

No

Prerequisite Features

None

This is an initial trigger feature which calls connectAndClose() on the feature endpoint.

Session State inputs and outputs

This feature does not read from or write to session state.

Error scenarios

This feature has no error conditions.

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Continue and Close Feature

Description

Feature name

ContinueAndClose

Applicable contexts

SS7 Service

SAS Support

No

Prerequisite Features

None

This is an initial trigger feature which calls continueAndClose() on the feature endpoint.

Session State inputs and outputs

This feature does not read from or write to session state.

Error scenarios

This feature has no error conditions.

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Do Not Monitor Session Feature

Description

Feature name

DoNotMonitorSession

Applicable contexts

SS7 Service

SAS Support

No

Prerequisite Features

None

This is an initial trigger feature which instructs Sentinel core not to monitor the call. Sentinel will send a Continue and close the dialog.

Session State inputs and outputs

This feature does not read from or write to session state.

Error scenarios

This feature has no error conditions.

Feature responses

Response Reason

doNotMonitorSession

intended behaviour

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Emergency And Special Number Feature

Description

Feature name

EmergencyAndSpecialNumber

Applicable contexts

SS7 service

SAS Support

No

Prerequisite Features

None

The Emergency and Special Number Feature is used as a pre credit check feature early or first in the feature list, to allow the call to continue immediately with no further intervention from Sentinel.

The feature will continue the call with no further intervention in the following cases:

  • MOC: initialDP.calledPartyBCDNumber is an exact match with a number in the provisioned table

  • MTC/MFC: initialDP.calledPartyNumber is an exact match with a number in the provisioned table

  • Any: initialDP.ext-basicServiceCode == ext-Teleservice AND initialDP.ext-basicServiceCode.ext-Teleservice == EmergencyCalls(0x12).

Session State inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

InitialDP which triggered this session

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Call type will be overwritten as EmergencyCall if the call is to a special or emergency number, otherwise it will be left as is

Error scenarios

Scenario Handling

InitialDPArg is not CAP

Report featureCannotStart

Null sessionstate SentinelSelectionKey

Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

Protocol is not CAP or SessionState SentinelSelectionKey is not set

continueAndCloseDialog

is a call to a special or emergency number

featureHasFinished

feature has finished

Configuration

The feature maintains a table of emergency or special numbers (using AddressLists) which are compared to the Called Party Number.

Error handling

If there are any errors attempting to execute this feature, such as a configuration error, the feature will end handling and allow Sentinel to continue handling the call as if it was NOT an emergency call.

Call flow

MSC ---- IDP(Cdpn=111) --> Sentinel
MSC <---   Continue    --- Sentinel

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:EmergencyAndSpecialNumber:AddressList

${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable

Feature specific Address List entry table

${SELECTIONKEY}:EmergencyAndSpecialNumber:AddressList:${Address}

Provisioning interfaces

The feature is provisioned using the web interface.

Friends and Family Feature

Description

Feature name

FriendsAndFamily

Applicable contexts

  • SS7 service

SAS Support

No * Diameter Mediation Service

Prerequisite features

Subscriber Data Lookup Feature

The Friends and Family (FnF) feature sets a special OCS tariff code if a subscriber is making a call to a number in their FnF list. If the other party’s number is in the FnF list, Sentinel will send the configured FnF tariff code (=rating group) while performing charging to OCS. The subscriber for the call type will have been determined using the SS7 Subscriber Determination Feature. When the MSC triggers Sentinel, the FnF list is retrieved for the subscriber. The number to check in the FnF list for the subscriber is shown in the table below:

Call type Number to check against FnF list

MOC

CalledPartyBCDNumber

MTC

CallingPartyNumber

MFC

CalledPartyNumber

NetworkInitiated(Callback)

Leg #4 Address

Emergency

N/A

MOSMS

DestinationSubscriberNumber

In all cases the normalized number will be used for the check.

It is expected that a subscriber’s Friends and Family list will be limited to a small number (such as 5). No logic will be implemented in the Profile/Database or Feature to enforce this limit. Any limit required by the operator will be enforced by the system provisioning the feature.

Any errors encountered during the execution of this feature, such as configuration errors or missing subscriber data, will have no effect on the call. No tariff will be set. The call will be allowed to proceed with other features.

Session State inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Runtime exception handled by the feature runner

FriendsAndFamilyEnabled

Boolean

true or false

Indicates whether Friends and Family is enabled for this subscriber

Runtime exception handled by the feature runner

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

InitialDP which triggered this session if it is a call — may be null if sms

If SessionType is call, Report featureCannotStart, featureHasFinished

InitialDPSMSArg

com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg

CAP-SMS-ops-args.InitialDPSMSArg

InitialDPSMS which triggered this session if it is an sms — may be null if call

If SessionType is sms, Report featureCannotStart, featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Calltype used for determining which party number is the other party address

Report featureCannotStart, featureHasFinished

SessionType

com.opencloud.sentinel.common.SessionType

One of: call, sms

Decide whether to inspect InitialDPSMSArg or InitialDPArg session state field when determining other party address

Runtime exception handled by the feature runner

FriendsAndFamilyList

String[]

Array of addresses

List of friends and family numbers

Set IsFriendsAndFamilyCall session state field to false
Increment NonFriendsAndFamilyCall
Report featureHasFinished

Outputs

Name Type Format Description

IsFriendsAndFamilyCall

Boolean

true or false

Indicates whether this session is a friends and family call

RatingGroup

Long

May be null if IsFriendsAndFamilyCall is false or FNF analysis failed

ID of the selected rating group

Error scenarios

Scenario Handling

Sessionstate CallType is null

Report featureCannotStart

Other Party address could not be determined

Report featureIssuedWarning

Feature responses

Response Reason

featureCannotStart

Call type is not set in the session state

featureIssuedWarning

OtherPartyAddress has not been set

featureHasFinished

feature has finished

OCS interface

In the case of Diameter Ro, a proprietary AVP will be set to indicate the FnF tariff code to the OCS. This will be determined as part of the vendor-specific integration requirements for the OCS.

Configuration

Friends and Family feature general configuration parameters

Parameter Type Description

LookupMethod

LookupTypeEnum

The method to be used to lookup the zone; one of: [profile,dbQuery]

RatingGroup

Long

General Rating Group for FnF

Subscriber FriendsAndFamily data (determined by, for example, the SubscriberDataLookup feature)

Parameter Type Values

FriendsAndFamilyEnabled

Boolean

true when HomeZone feature is activated for this subscriber. See Friends and Family Feature.

FriendsAndFamilyList

String[]

list of numbers in normalized format (for example, 6421678956,6421345444,6421343333)

The Friends and Family list is provisioned in normalized format, such as:

  • 6421678956

  • 6492324856

  • 64800123456 (0800 123456)

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

FriendsAndFamilyFeatureConfigProfileTable

Selection of database implementation and rating group for the feature

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The feature is provisioned using the web interface.

Home Zone Feature

Description

Feature script name

HomeZone

Applicable contexts

SS7 service

SAS Support

No

Prerequisite features

The Home Zone feature determines if the subscriber is within a defined set of home zones on originating calls.

The subscriber zones table is used to determine the list of zones that the subscriber is registered in.

The location type criteria is determined from the initialdp.locationInformation.cellGlobalIdOrServiceAreaIdOrLAI and set to one of SAI, CGI, or LAI.

Then the zones table is used to determine if the location from the initialdp is in one of the registered zones for the subscriber.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

HomeZoneEnabled

Boolean

true or false

Whether the subscriber has home zone support enabled

Runtime exception handled by the feature runner

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

InitialDP which triggered this session if it is a call

Report featureCannotStart, featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Only mobile originating calls eligible for home zone

Report featureCannotStart, featureHasFinished

HomeZoneList

String[]

Array of zone names

The subscriber’s home zones

Set InHomeZone session state field to false
Report featureHasFinished

Outputs

Name Type Format Description

InHomeZone

Boolean

true or false

Indicates whether the subscriber is calling from their home zone

Error scenarios

Scenario Handling

Sessionstate

CallType is null Set Sessionstate InHomeZone to false
Report featureCannotStart

Sessionstate InitialDPArg is null

Set Sessionstate InHomeZone to false
Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

Call type is not set in the session state or InitialDP Arg is not set in the session state

featureHasFinished

feature has finished

Configuration

Home Zone has a single general configuration parameter:

Parameter Type Description

LookupMethod

LookupTypeEnum

The method to be used to lookup the zone; one of: [profile,dbQuery]

The storage of zone information is as follows:

Field Type Description

Name

String

Name of the zone referenced by subscriber specific zone configuration

LocationTypes

LocationTypeEnum[]

Each entry to be be one of: [SAI, CGI or LAI]

LocationDescriptions

String[]

Location descriptions

MCC

String[]

MCC may have values between 100 and 999

MNC

String[]

MNC may have values between 10 and 999

LAC

Integer[]

LAC may have values between 1 and 65533 (FFFD) and 65535 (FFFF) (excludes 0 and 65534 (FFFE) for which no valid LAI exists)

CIOrSAC

Integer[]

CI may have values between 0 and 65535 (FFFF); SAC may have values between 0 and 65535 (FFFF)

Example Zones Table

ZoneName LocationType MCC MNC LAC CIorSAC Location description

WgtnCBD

SAI

530

01

11

22

Vodafone NZ location

WgtnCBD

CGI

530

01

01

01

Vodafone NZ location

WgtnCBD

LAI

530

01

01

Vodafone NZ location

AkldCBD

LAI

530

02

02

Vodafone NZ location

Where LocationType=SAI or CGI then MCC, MNC, LAC, and CIorSAC are mandatory

Where LocationType=LAI then MCC, MNC, and LAC are mandatory. CIorSAC must not be set.

Subscriber Zones Table

Field Description

HomeZoneEnabled

true or false

HomeZoneList

List of home zones from the zones table for this subscriber

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

HomeZoneFeatureConfigProfileTable

Feature configuration. Currently for the selection of database implementation for the zones table

SentinelSelectionKey (for example, OpenCloud::::)

HomeZoneFeatureSqlProfileTable

SQL statement configuration

SentinelSelectionKey (for example, OpenCloud::::)

HomeZoneFeatureZonesProfileTable

Zone table if profiles selected

SentinelSelectionKey:ZoneName (for example, OpenCloud::::WgtnCBD)

Database schemas

Database schemas for TimesTen and Oracle are available in the Sentinel release package.

Provisioning interfaces

The feature is provisioned using the web interface.

Play Announcement Feature

The Play Announcement feature plays an announcement to the calling party during call establishment or after the called party disconnects. The announcement is played by the MSC/GMSC gsmSRF.

Description

Feature name

PlayAnnouncement

Applicable contexts

SS7 service

SAS Support

No

Prerequisite features

The id of the announcements to be played is set in the AnnouncementID session variable. If the AnnouncementID session variable is not set (null) or set to 0, no announcement is played and the feature returns without error or side effect to the dialog.

Another feature must be executed prior to the PlayAnnouncement feature to set the AnnouncementID.

All announcements which are played by the feature are appended to the PlayedAnnouncementIDs session variable. This list of announcements is used by the standard CDR mappers and may be used in custom CDR mappers.

The announcement can be played using one of the following modes:

  • Using ConnectToResource only, to connect to an SRF integrated with the controlling MSC.

  • Using EstablishTemporaryConnection and an assisting dialog to connect to a non-integrated SRF.

  • Using Connect to redirect the call to an IVR or announcement device. When using this mode the call ceases to be controlled via Sentinel.

If desired the announcement mode can be configured based on address lists matching the global title digits in the dialog’s CallingPartyAddress, the triggering MSC address, the subscriber address (as determined by Sentinel), or the subscriber’s IMSI. Alternatively the announcement can always be played using the same announcement mode.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

AnnouncementID

Integer

Any integer

ID of the announcement that is to be played

Increment MissingAnnouncementIDs
Report featureHasFinished

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

CanRelayDialog

boolean

true or false

True if the assisting dialog has not been accepted yet

Not nullable

ResponderSccpAddress

com.opencloud.slee.resources.cgin.SccpAddress

SccpAddress

The SCCP Address to use as the responding address in the Open Response instead of the address provided by the stack, or null to leave the address unchanged

Use the address provided by the stack

LatestEventReportBCSM

com.opencloud.slee.resources.cgin.callcontrol.CCEventReportBCSMArg

CC-DataTypes.EventReportBCSMArg

Once the first event report has been received abandon is no longer required

Abandon will be armed

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call for determining from configuration which party address to lookup

Report featureCannotStart, featureHasFinished

LatestOcsAnswer

org.jainslee.resources.diameter.ro.types.CreditControlAnswer

Credit-Control-Answer

Announcements can reference variables based on latest CCA see Configuration

No action

Outputs

Name Type Format Description

CanRelayDialog

boolean

true or false

True if the assisting dialog has not been accepted yet

Error scenarios

Scenario Handling

Null CorrelationProvider

Increment ConfigurationErrors
Report featureFailedToExecute

Sessionstate SentinelSelectionKey is null

Increment InputParameterErrors
Report featureFailedToExecute

ACI not provided to the announcement feature

Increment InputParameterErrors
Report featureFailedToExecute

No profile for selection key and AnnouncementID in AnnouncementProfileTable

Increment InputParameterErrors
Report featureFailedToExecute

No profile for selection key in AnnouncementConfigProfileTable

Increment InputParameterErrors
Report featureFailedToExecute

Null TariMillis in AnnouncementConfigProfile

Increment InputParameterErrors
Report featureFailedToExecute

Exception invoking RequestReportBCSM on dialog

Increment ErrorsArmingAbandon
Report featureFailedToExecute

Dialog object not provided to the announcement feature in the activity context interface

Increment InputParameterErrors
Report featureFailedToExecute

Invalid type configured for the announcement ID (Should be tone, message or messages)

Increment InputParameterErrors
Report featureFailedToExecute

TooManyInvokesException or ProtocolException whiling sending CTR or PlayAnnouncement

Increment ErrorsSendingCTRAndPA
Report featureFailedToExecute

Received SS7 Abort

Increment Ss7Aborts
If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input
Report featureFailedToExecute

Received SS7 Error

Increment Ss7Errors
If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input
Report featureFailedToExecute

Received Abandon or Disconnect

If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input
Report featureFailedToExecute

Tari expiry

If not useAssistingDialog, Increment TariExpiries If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input
Report featureFailedToExecute

Feature responses

Response Reason

featureFailedToExecute

ss7Error

featureHasFinished

feature has finished

Configuration

Announcement configuration

Announcements are referenced by id. The configuration of each announcement id is provisioned in the following table:

Parameter Type Description

Description

String

Description of the announcement

Id

Integer

Announcement ID

AnnouncementType

AnnouncementTypeEnum

The announcement type, one of [message, tone, messages]

Value

Integer[]

Value of the message/tone ID (or IDs if 'announcementType' is 'messages') to be played.

ToneDuration

Integer

Duration of a tone announcement in seconds. Valid values: not set, 0 - 65535. Note: 0 means infinite duration. (This is an Integer4 ASN.1 type).

NumberOfRepetitions

Integer

The number of times an announcement may be repeated. Valid values: 0 - 127. Note: 0 means the NumberOfRepetitions parameter is not included in the InbandInfo of the PlayAnnouncement operation.

VariableCcaPaths

String[]

An array of CCA xpath expressions

VariableTypes

String[]

An array of type names. Each entry has to be one of [integer, number, date, time, price]

AllowDisconnect

Boolean

Determines if automatic disconnect of the gsmSRF is allowed when the announcement is complete.

ResetTssf

Boolean

Indicates whether or not a ResetTimer operation will be sent before the announcement is played to reset the Tssf timer.

InvokeTimeout

Long

Invoke timeout in milliseconds. In conjunction with the Tssf Reset Margin it is used to set the invoke timeout of the PlayAnnouncement operation and to determine the value to reset the Tssf timer to via the ResetTimer operation before the announcement begins (if ResetTssf is true). 1000-3600000 milliseconds.

CtrConfig

String

Reference to resource configuration to use with ConnectToResource

IvrAddressCalledPartyNumber

CalledPartyNumber

The IVR address is only required if the announcement mode is CONNECT. It is specified in called party number string format, which includes comma-separated name value pairs with names one of: address, nature, numberingPlan, routingToInternalNetworkNumber. See CalledPartyNumber for more information.

Example announcement table configuration:

ID Description Type Value ToneDuration NumberOfRepetitions AllowDisconnect InvokeTimeout CtrConfig VariableCcaPaths VariableTypes

1

Play message "You have insufficient credit to make this call"

message

123

3

N

10000

srf1

2

Play tone

tone

23

250

N

1000

3

Play messages "You have insufficient credit to make this call", and "Call the topup line"

messages

123,124

N

10000

4

Play message with variable 1 assigned time granted

message

34

N

10000

[/MultipleServices
CreditControl
[ServiceId = 0]
/Granted-Service-Unit/CCTime]

[integer]

The Play Announcement feature may set variables based on fields from session state (latest CCA is supported). The Sentinel XPath Language Component is used to reference fields in the CCA. For example, /MultipleServicesCreditControl[ServiceId = 0]/GrantedServiceUnit/CCTime references the amount of time granted for service with id 0.

The CtrConfig is a reference to an entry in the Resource Config table with the ConnectToResource configuration.

Resource config

Parameter Type Description

Name

String

Name of this CtrConfig. It is used by the announcement configuration profile to reference this configuration.

ResourceAddressCalledPartyNumber

CalledPartyNumber

The resource address in called party number string format, which includes comma-separated name value pairs with names one of: address, nature, numberingPlan, routingToInternalNetworkNumber. See CalledPartyNumber for more information.

Example resource configuration profile:

Name

ResourceAddress

srf1

The ResourceAddress choice NONE is selected when the ResourceAddress is not set.

Announcement mode

The announcement mode determines how the announcement will be played:

Internally using ConnectToResource only, to connect to an SRF integrated with the controlling MSC.

Using EstablishTemporaryConnection and an assisting dialog to connect to a non-integrated SRF. There are two sub-modes of this mode:

Combined mode, where the assisting MSC address, SCF id, and correlation id are all combined into the assistingSSPIPRoutingAddress parameter of the EstablishTemporaryConnection operation argument.

Separate mode, where the assisting MSC address, SCF id, and correlation id all use separate fields in the EstablishTemporaryConnection operation argument.

Using Connect to redirect the call to an IVR or announcement device. When using this mode the call ceases to be controlled via Sentinel.

The announcement mode is determined first by address list interrogation (see table below), followed by the Sentinel Selection Key configuration if no matching address list configuration was found.

Address lists

The Play Announcement feature supports four different address lists for determining the announcement mode:

Address List Name Default Search Mode Description

OriginatingSccpAddressList

longest prefix match

Uses the the global title digits of the the incoming dialog’s CallingPartyAddress.

MscAddressList

longest prefix match

Uses the address string of the MSCAddress parameter of the incoming InitialDP or InitialDPSMS.

SubscriberAddressList

exact match

Uses the subscriber address for the session.

SubscriberImsiList

exact match

Uses the subscriber IMSI for the session.

The address lists actually searched by the Play Announcement feature are determined by the Sentinel Selection Key configuration. The default search mode for each list can be changed via the configuration for the corresponding address list. An address list will only be searched if the feature can determine a suitable address for the lookup. For example, if the incoming dialog has no global title digits in the CallingPartyAddress then the OriginatingSccpAddressList will not be searched, even if specified in the configuration.

Sentinel selection key configuration

Various other parameters related to playing the announcement are set in a configuration that may be scoped to the Sentinel selection key:

Parameter Type Description

AnnouncementLists

AnnouncementList[]

A list of Address List names specifying which address lists to search for the announcement mode. The address lists will be searched in the order given in this list.

Default Mode

AnnouncementMode

The announcement mode to use if address list lookup fails to find an announcement mode. One of [INTERNAL, ETC_COMBINED, ETC_SEPARATE, CONNECT]

Assisting SSP IP Routing Address Generic Number

GenericNumber

Address of the Assisting MSC. Only required if using an ETC announcement mode.

Combined Mode SCF ID

String

The SCF ID of Sentinel to use in ETC_COMBINED mode. Only required if using an ETC_COMBINED announcement mode.

Separate Mode SCF ID

Byte[]

The SCF ID of Sentinel to use in ETC_SEPARATE mode. Only required if using an ETC_SEPARATE announcement mode.

Use Correlation Delimiter

Boolean

Flag indicating if a delimiter digit (hex 'b') should be used between the assisting MSC address and the SCF ID when using the ETC_COMBINED mode. Only relevant if using this mode.

Tssf Reset Margin

Integer

The number of seconds added to the announcement duration used to reset the Tssf timer using the ResetTimer operation during announcement playing. This is just a safety margin.

Tari Millis

Long

The Tari timer value in milliseconds

Announcement playing signalling flows

If AllowDisconnect=false or is not set or has invalid value, the PlayAnnouncement.disconnectFromIPForbidden is set to true and the announcement component will send the DFC; otherwise it will not.

The call flow to be used (AllowDisconnect=true):

MSC <---- RT ----- Sentinel
MSC <---- CTR ---- Sentinel
MSC <---- PA ----- Sentinel
MSC <- DELIMITER - Sentinel
MSC ----- SRR ---> Sentinel
MSC - DELIMITER -> Sentinel

The call flow to be used (AllowDisconnect=false):

MSC <---- RT ----- Sentinel
MSC <---- CTR ---- Sentinel
MSC <---- PA ----- Sentinel
MSC <- DELIMITER - Sentinel
MSC ----- SRR ---> Sentinel
MSC <---- DFC ---- Sentinel
MSC <- DELIMITER - Sentinel

In the case of multiple announcements, all the play announcements in the list will be sent together to the gsmSRF. The FSM will handle all of the SRR expected from the gsmSRF before returning.

The call flow to be used (all AllowDisconnect=false):

MSC <---- CTR ---- Sentinel
MSC <---- PA ----- Sentinel
MSC <---- PA ----- Sentinel
MSC ----- SRR ---> Sentinel
MSC ----- SRR ---> Sentinel
MSC <---- DFC ---- Sentinel

Error handling

The Play Announcement feature may encounter a number of different errors, for example:

  • required configuration state may be missing

  • required configuration parameters may be invalid

  • operation errors sent by the initiating or assisting MSC may be encountered

In all error cases the feature returns the featureFailedToExecute result and exits. A feature script can test for this condition and react accordingly, for example the script could allow the call to continue regardless, or could release the call instead.

Examples of some error call flows:

SRR expected but not received:

MSC <---- CTR ---- Sentinel
MSC <---- PA(requestAnnouncementComplete=true) ---- Sentinel
Invoke timeout
MSC ----> PE(NO_LINKED_RESPONSE) ---> Sentinel

This is the standard case when requestAnnouncementComplete=false (that is, no SRR expected but we still get the provider error due to the protocol definition)

MSC <---- CTR ---- Sentinel
MSC <---- PA(requestAnnouncementComplete=n) ---- Sentinel
Invoke timeout
MSC ----> PE(NO_LINKED_RESPONSE) ---> Sentinel

Reject:

MSC <---- CTR ---- Sentinel
MSC <---- PA ---- Sentinel
MSC ----> PE(REMOTE_REJECT) ---> Sentinel

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

AnnouncementProfileTable

Announcement configuration profiles

SentinelSelectionKey:id (for example, OpenCloud::::15)

AnnouncementResourceConfigProfileTable

ConnectToResource resource configuration

SentinelSelectionKey:ctrConfigName (for example, OpenCloud::::srf1)

AnnouncementConfigProfileTable

Additional resource configuration

SentinelSelectionKey:configName (for example, OpenCloud::::config)

${PLATFORMOPERATOR}PlayAnnouncementAddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:PlayAnnouncement:${AddressListName}

${PLATFORMOPERATOR}PlayAnnouncementAddressListEntryTable

Feature specific Address List entry table

${SELECTIONKEY}:PlayAnnouncement:${AddressListName}:${ADDRESS}

Provisioning interfaces

The feature is provisioned using the web interface.

Prefix and Suffix Analysis Feature

Sentinel has a set of configurable prefix and suffix lists, scoped by Sentinel selection key, which are used for number analysis.

Description

Feature name

PrefixAndSuffixAnalysis

Applicable contexts

  • SS7 service

SAS Support

No * Diameter Mediation Service

Prerequisite features

Classify Call Scenario Feature

If a prefix or suffix is matched, the directive associated with the prefix is used.

The directives are: strip prefix/suffix or retain prefix/suffix, and set session parameter with configured value.

Where the directive is strip, the new called party number will be sent in a connect.

Note Subsequent features may make additional changes to the called party number, so the final address sent in the connect will be dependent on those features.
Parameter Description

Address

Prefix or suffix to match

Description

ListId

${SELECTIONKEY}:PrefixAndSuffixAnalysis::SpecialPrefixList
${SELECTIONKEY}:PrefixAndSuffixAnalysis:SpecialSuffixList

ParameterName

Session state field to set (for example, AnnouncementID). Field name is in Java identifier format, and follows the rules of Java identifiers (such as not being a Java keyword).

ParameterType

boolean, integer, long, string

ParameterValue

Value to write to session state. Must be formatted correctly for the value specified in the Parameter Type field

PrefixDirective

strip, retain

Example of prefix analysis configuration:

Prefix/suffix address Directive Session Parameter Parameter Type Parameter Value Description

1234

STRIP

CLI

String

SUPPRESS

555

STRIP

TARIFF

String

Cheap-International-Calling

*591

STRIP

PROFILE

Integer

1

Profile selection

*592

STRIP

PROFILE

Integer

2

Profile selection

*593

STRIP

PROFILE

Integer

3

Profile selection

*594

STRIP

PROFILE

Integer

4

Profile selection

.

STRIP

Strip ST (end of pulsing) digit

Prefix may contain the following characters: 0-9, *, #, a, b, c, and . (period) . The expected decoding of a network address is specific to the number.

CalledPartyBCDNumber (MO calls):

Decoded character

0

1

2

3

4

5

6

7

8

9

*

#

a

b

c

Encoded hexadecimal

0

1

2

3

4

5

6

7

8

9

A

B

C

D

E

CalledPartyNumber (MF/MT calls):

Decoded character

0

1

2

3

4

5

6

7

8

9

*

#

.

Encoded hexadecimal

0

1

2

3

4

5

6

7

8

9

A

B

C

D

E

F

Session State inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.

CAP1InitialDPArg

CAP-DataTypes.InitialDPArg InitialDP which triggered this session

Report featureCannotStart, featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call for determining which party address to analyse

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

DestinationHasChanged

boolean

true or false

True if the IDP CdPA number address has been modified

ServiceType

com.opencloud.sentinel.common.ServiceType

One of: Voice, Data, Fax, Video, Unknown

Indicates the service type of this session

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

Updated InitialDPArg if destination has changed

Other session state fields see Description see Description This feature can update other session state fields according to configuration data when a prefix or suffix match is found

Error scenarios

Scenario Handling

Sessionstate SentinelSelectionKey is null

Report featureCannotStart

Sessionstate InitialDPArg is null

Report featureCannotStart

Sessionstate InitialDPArg is not CAP

Report featureCannotStart

Attempt to set non-existent SessionState parameter

Report featureFailedToExecute

Feature responses

Response Reason

featureCannotStart

SessionState SentinelSelectionKey is not set, InitialDP Arg is not set in session state or InitialDP Arg is not an instance of CAP1InitialDPArg

featureFailedToExecute

Attempt to set non-existent SessionState parameter

featureHasFinished

feature has finished

Multiple subscriber profile selection

The Prefix and Suffix Analysis feature supports multiple subscriber profile selection. See Noldus​[1] pp.219 5.2.9 Multiple Subscriber Profile.

MSP uses suffixes with the following digit string for the called party number, for dynamic profile selection: <Directory Number>59n # SEND , where n identifies the profile.

Configuration

Prefix and Suffix Analysis uses Sentinel AddressLists for configuration data. See Address Lists for how to provide the configuration data.

Configuration profile naming

Configuration Profile Table Name

Description

Profile Naming

${PLATFORMOPERATOR}_PrefixAndSuffixAnalysisFeature_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:PrefixAndSuffixAnalysis:SpecialPrefiList or ${SELECTIONKEY}:PrefixAndSuffixAnalysis:SpecialSuffixList

${PLATFORMOPERATOR}_PrefixAndSuffixAnalysisFeature_AddressListEntryTable

Feature specific Address List entry table

${SELECTIONKEY}:PrefixAndSuffixAnalysis:SpecialPrefixList:${ADDRESS}

Provisioning interfaces

The feature is provisioned using the web interface.

NOLDUS

CAMEL

INTELLIGENT NETWORKS FOR THE GSM, GPRS AND UMTS NETWORK

Rogier Noldus

2006

John Wiley & Sons, Ltd

Relay Dialog During Dialog Analysis Feature

Description

Feature name

RelayDialogDuringDialogAnalysis

Applicable contexts

SS7 service

SAS Support

No

Typical feature execution points

DirectAccess_SessionStart, DirectAccess_SessionAccept

Prerequisite features

None

The Relay Dialog During Dialog Analysis feature requests Sentinel core to relay the received dialog to another network element.

Session state inputs and outputs

This feature does not read from or write to session state.

Feature responses

Response Reason

relayDialog

the dialog should be relayed

featureHasFinished

feature has finished

Call flow

MSC ---- OpenRequest --> Sentinel
MSC ----- InitialDP ---> Sentinel
                         Sentinel ---- OpenRequest --> New Network Element
                         Sentinel ----- InitialDP ---> New Network Element
MSC <----------------- OpenAccept -------------------- New Network Element

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Relay Dialog During Initial Trigger Analysis Feature

Description

Feature name

RelayDialogDuringInitialTriggerAnalysis

Applicable contexts

SS7 service

SAS Support

No

Typical feature execution points

Any of the initial trigger feature execution points such as DirectAccess_SessionPreCreditCheck

Prerequisite features

None

This feature requests Sentinel core to relay the received dialog to another network element.

Session state inputs and outputs

This feature does not read from or write to session state.

Error scenarios

This feature has no error conditions.

Feature responses

Response Reason

relayDialog

the dialog should be relayed

featureHasFinished

feature has finished

Call flow

The InitialDP may have been altered by features. For example, the calling and called party numbers in the InitialDP may have been normalised to an international format. The InitalDP relayed to the new network element will contain any such changes.

MSC ---- OpenRequest --> Sentinel
MSC ----- InitialDP ---> Sentinel
                         Sentinel ---- OpenRequest --> New Network Element
                         Sentinel ----- InitialDP' --> New Network Element
MSC <----------------- OpenAccept -------------------- New Network Element

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Release Call and Close Dialog Feature

Description

Feature name

ReleaseCallAndCloseDialog

Applicable contexts

SS7 service

SAS Support

No

Prerequisite Features

Optional: Any feature setting the UserReleaseCause session state field

The Release Call And Close Dialog feature is a very simple feature that instructs Sentinel to release the call or SMS and close the dialog with the MSC. The following release cause codes are used by default:

  • for calls:

    • when used during Initial Trigger handling: CLASS_1_CALL_REJECTED (21)

    • when used during End Session handling: CLASS_1_NORMAL_CALL_CLEARING (16)

  • for SMSes:

    • if the latest OCS reply (if any) indicates an unknown user, then: UNKNOWN_SUBSCRIBER (30)

    • otherwise: RESERVED (11)

If a different release cause code is needed, another feature can be run before the Release Call And Close Dialog feature to set the CCUserReleaseCause or CCUserReleaseCause session state variable. If this session state variable is set, the Release Call And Close Dialog feature uses the cause value it specifies instead of the default. If the value set is not within the valid range of cause codes, the default cause code as specified above will be used instead.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

CCUserReleaseCause

com.opencloud.slee.resources.in.datatypes.cc.Cause

CAP-DataTypes.Cause

Release Cause to use for call control session release

Report featureCannotStart, featureHasFinished

SMSUserReleaseCause

com.opencloud.slee.resources.in.datatypes.sms.RPCause

CAP-DataTypes.RPCause

Release Cause to use for SMS session release

Report featureCannotStart, featureHasFinished

LatestOcsAnswer

org.jainslee.resources.diameter.ro.types.CreditControlAnswer

Credit-Control-Answer

For determining release cause code if the UserReleaseCause is not set

Use default call release cause CLASS1_NORMAL_CALL_CLEARING

SessionType

One of: call, sms

Session type of this call for choosing how to determine cause code from LatestOcsAnswer

Runtime exception handled by the feature runner

Outputs

This feature does not modify session state.

Error scenarios

This feature has no error conditions.

Feature responses

Response Reason

releaseCallAndCloseDialog

intended behaviour

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Roaming Default Call Forwarding Feature

Description

Feature name

RoamingDefaultCallForwarding

Applicable contexts

SS7 service

SAS Support

No

Prerequisite features

Roaming Default Call Forwarding (RDCF) applies only to roaming MTC calls. It defines roaming-specific forwarding addresses for ‘Busy’, ‘No reply’ cases to prevent tromboning of forwarded calls to numbers in the subscriber’s HPLMN.

The ‘Busy’, ‘No Reply’ cases are triggered when the event report BCSM returns busy or no answer.

RDCF issues a ‘Connect’ to forward the call. The following parameters are set in the ‘Connect’:

Parameter Value Description

destinationRoutingAddress

SessionState.{CfBusy,CfNoReply}

Set based on the forwarding case from session state

redirectingPartyID

SessionState.Subscriber

Sets to the address of the served subscriber

originalCalledPartyID

 
IF initialdp.originalCalledPartyID not set THEN
    set to initialdp.calledPartyBCDNumber
ELSE
    do not set
ENDIF

redirectionInformation.redirectingReason

USER_BUSY / NO_REPLY / UNCONDITIONAL / MOBILE_UNREACHABLE

Set based on reason for the forward.

redirectionInformation.RedirectionCounter

Set to Maximum Value (configurable)

Setting the counter to the maximum value has the effect of suppressing call forwarding in the VMSC, and preventing tromboning.

redirectionInformation.redirecting

CALL_DIVERTED

oCSIApplicable

true

Needed to ensure that MF call is triggered.

In the case of a subscriber configuration error which causes the feature to be unable to forward the call, the feature will allow the Sentinel core to continue without affecting the call, but will report the error to the core.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Runtime exception handled by feature runner

LatestEventReportBCSM

com..opencloud..slee..resources..cgin..callcontrol..CCEventReportBCSMArg

CCEventReportBCSMArg

Argument of the latest event report BCSM received

Report featureCannotStart, featureHasFinished

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg

CAP-DataTypes.InitialDPArg

InitialDP which triggered this session

Runtime exception handled by feature runner

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call for determining which party address to lookup

Call is considered not eligible for call forwarding — report featureHasFinished

RoamingIndicator

Boolean

true or false

Indicates whether this session is roaming

Runtime exception handled by feature runner

CfBusy

String

MSISDN

Call forwarding destination address when subscriber line is busy

If CfNoReply also null, increment FeatureNotEnabledForSubscriber
If EventTypeBCSM is tCalledPartyBusy, increment NoForwardingNumber and do not forward call

CfNoReply

String

MSISDN

Call forwarding destination address when subscriber does not answer

If CfBusy also null, increment FeatureNotEnabledForSubscriber
If EventTypeBCSM is tNoAnswer, increment NoForwardingNumber and do not forward call

Subscriber

String

MSISDN

For recording RedirectingPartyNumber in the connect arg if call forwarding is triggered

Runtime exception handled by feature runner

Outputs

Name Type Format Description

CCConnectArg

com.opencloud.slee.resources.cgin.cap_v2.CAP2ConnectArg

CAP-DataTypes.ConnectArg

The connect arg Sentinel will use when forwarding the call. Not updated if RDCF fails or is disabled.

Error scenarios

Scenario Handling

MappingException while mapping destination routing address to connect arg

Report featureFailedToExecute

Feature responses

Response Reason

featureCannotStart

latestEventReportBCSM is not set or Initial DP Arg is missing the CdPA BCD number

featureFailedToExecute

Error while forwarding a roaming MT call

connectAndCloseDialog

successful attempt to forward the call

featureHasFinished

feature has finished

Interaction with call-forwarding supplementary service

See ETSI TS 100 543/GSM 03.82 Call Forwarding (CF) supplementary services.

RDCF will suppress the call forwarding supplementary service for the subscriber (if configured) in the busy and no answer cases. Unconditional and not reachable cases which do not cause tromboning are not affected by this feature.

Note Please see Call Forwarding Detection Feature for detection and handling of the early call forwarding case, where the idp is received and call forwarding is pending.

OCS interface

No interaction with OCS from this feature except via MFC.

Triggers and application contexts

Application Contexts:

  • cap-v2-gsmSSF-to-gsmSCF-AC

  • capssf_scfGenericAC (CAP3).

The InitialDP will be triggered on DP12 (Terminating_ Attempt_Authorized).

Configuration

RDCF feature-wide configuration parameters

Parameter Type Description

MaxRedirectionCounter

Integer

The maximum value for use in connect.redirectionInformation.RedirectionCounter

Subscriber RDCF Table

Parameter Type

CfBusy

CalledPartyNumber

CfNoReply

CalledPartyNumber

The the RDCF list is provisioned in international format, such as:

  • 6421678956

  • 6492324856

  • 64800123456 (0800 123456)

The subscriber forwarding numbers will be provisioned using a text format, such as that used for CalledPartyNumber; for example:

address=641234567,NATURE=INTERNATIONAL,numberingplan=isdn,routingToInternalNetworkNumber=allowed

The internal format used by Sentinel will be the binary encoding.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

RoamingDefaultCallForwardingFeatureConfigProfileTable

Configuration properties

SentinelSelectionKey (for example, OpenCloud::::)

Provisioning interfaces

The feature is provisioned using the web interface.

Roaming Reorigination Feature

The Reorigination feature is used as a way of handling triggers from roaming subscribers on networks that use CAPv1, or networks that use CAPv2 or CAPv3 but are otherwise determined to be unsupported for direct call control from the VPLMN.

Description

Feature name

Reorigination

Applicable contexts

SS7 service

SAS Support

No

Prerequisite Features

Classify Call Scenario Feature

The reorigination capability is needed when:

  • Roaming partners are triggering calls with CAMELv1.

  • Roaming partners are triggering calls with CAPv2, and cannot send the ERB(disconnect) in the same TCAP message as the ACR)(see CAMEL2 issue).

  • The calling party number is lost in the ISUP signalling when traversing an international carrier. In this case Sentinel must store the calling party number and set it in the connect. As setting the calling party number is not supported in CAMEL, this capability requires INAP CS1, CS2, or a proprietary variant. See Noldus​[2] section 3.6.3 Short Number Dialling with CLI Guarantee pp.82. Currently not supported in Sentinel.

In these cases, the call is reoriginated to the HPLMN using a pool of special routing numbers. The reoriginated call is re-triggered from the HPLMN MSC.

The Reorigination feature should run at one of the pre credit check feature execution points for both the original InitialDP and the reoriginated InitialDP. The Reorigination feature uses the reorigination-correlation-ra to choose the special routing number, and to store data from the original InitialDP that should be correlated with the reoriginated InitialDP.

Tip See Correlation Resource Adaptor to understand how the reorigination-correlation-ra works and how it can be configured
Note If the dialog should not be reoriginated, or represent a reoriginated dialog, then the Reorigination feature will silently end to allow subsequent features to process the InitialDP.

The two phases of roaming reorigination

  • Reoriginating a session. The Reorigination feature analyses the InitialDP stored in session state to decide if it should be reoriginated. If the dialog should be reoriginated, then it chooses a free special routing address and routes the call to this special routing address. The reoriginated call may then be re-triggered from the HPLMN MSC

  • Receiving a reoriginated trigger.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

InitialDP which triggered this session — CalledPartyBCDNumber may be used in identifying reoriginated calls and may be modified

Runtime exception to be handled by feature runner

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call

Call will not be reoriginated or identified as reoriginated

RoamingIndicator

Boolean

true or false

Indicates whether this is a roaming call

Reorigination will not be attempted

Outputs

Name Type Format Description

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

CalledPartyBCDNumber be restored or replaced if the call has or will be reoriginated

RoamingIndicator

Boolean

true or false

Will be set to true if this call is a reoriginated request, otherwise unchanged

CCConnectArg

com.opencloud.slee.resources.cgin.cap_v2.CAP2ConnectArg

CAP-DataTypes.ConnectArg

The connect arg Sentinel will use if the call is to be reoriginated — not modified otherwise

Error scenarios

Scenario Handling

Sessionstate SentinelSelectionKey is null

Report featureCannotStart

Invoked for a non CAP dialog

Report featureIssuedWarning

No available correlation entries

Report releaseCallAndCloseDialog

Could not find a mapper to build the ConnectArg

Report featureFailedToExecute

Error retrieving the correlated data to restore InitialDP

Report releaseCallAndCloseDialog

Feature responses

Response Reason

featureCannotStart SessionState

SentinelSelectionKey is not set

featureIssuedWarning

non CAP dialog

releaseCallAndCloseDialog

Error while restoring the original Called Party Address address, error while reoriginating: unsupported network, could not find a mapper to build the ConnectArg

connectAndCloseDialog

Attempt to trigger reorigination

featureHasFinished

feature has finished

Below are details of the two phases, followed by Call Flow, Configuration, Configuration Profile Naming, and Provisioning Interfaces.

Phase one: reoriginating a session

Reoriginating a session includes these steps:

Determining if a dialog should be reoriginated

The Reorigination feature analyses the InitialDP to determine if the dialog should be reoriginated. The Reorigination feature checks:

  1. if the dialog is for originating treatment. The first InitialDP will be triggered on DP2 (Collected Info). Terminating and forwarded dialogs are not reoriginated.

  2. if the application context is supported. Supported application contexts are:

    • cap_v1_gsmSSF_to_gsmSCF-AC

    • cap-v2-gsmSSF-to-gsmSCF-AC

    • capssf_scfGenericAC (CAP3).

  3. if the InitialDP VLR address is for a roaming party for which reorigination is supported. Roaming partners that do not support the ERB(Disconnect) + ACH guarantee are listed in a reorigination configuration table which includes the VLR addresses of the operator. The Reorigination service determines if the VLR address is present in the table, and if so triggers reorigination.

Processing a reoriginated session

If a session is to be reoriginated, the feature uses the Correlation RA to:

  • get an ID that is used to route the call to

  • associate some data with the correlation ID that can be used when the dialog is reoriginated.

The important steps are:

  1. Create the address we will use to select an id-pool.

  2. Create the data that we will associate with the correlation ID.

  3. Get a new correlation entry (passing the address and correlation data).

  4. Construct the outgoing connect arg.

Step one is achieved with a Mapper. The Reorigination feature looks for a mapper:

// a mapper that takes an {{InitialDP}} and generates a String.
final Mapper mapper = mapperLibrary.findMapper(selectionKey, initialDpArg.getClass(), String.class);

Sentinel includes a Mapper for this purpose — CAPInitialDPToCorrelationIdPoolAddress — that returns the MCC from location information in the InitialDP.

Note An alternative mapper that uses a different method for choosing an address to choose the id-pool can be written using the Sentinel SDK.

Step two is achieved with a Mapper. The Reorigination feature looks for a mapper:

// a mapper that takes an {{InitialDP}} and generates a {{byte\[\]}}.
final Mapper mapper = mapperLibrary.findMapper(selectionKey, cap1IdpArg.getClass(), byte[].class);

Sentinel includes a Mapper for this purpose, (CAPInitialDPArgToCorrelationData), that:

  • creates a new CAP1InitialDPArg object

  • copies the called party bcd number to the new cap 1 InitialDP

  • copies the bearer capability (if present) to the new cap 1 InitialDP

  • copies the redirecting party ID (if present) to the new cap 1 InitialDP

  • copies the redirection information (if present) to the new cap 1 InitialDP

  • copies the location information (if present) to the new cap 1 InitialDP

  • copies the extensions (if present) to the new cap 1 InitialDP

  • uses CGIN persist factory to turn this CAP1InitialDP → byte[].

Note An alternative mapper that uses a different method for building the correlated data to be associated with the correlation ID can be written using the Sentinel SDK. Step four uses a configuration profile selected from the ReoriginationConfigProfileTable to construct a new DRA, and a Mapper from the trigger class (for example, Cap2InitialDPArg) to a ConnectArg, to map it to an outgoing connect arg.

Phase two: receiving a reoriginated trigger

Receiving a reoriginated trigger includes these steps:

Determining if a dialog has been reoriginated

The reorigination feature analyses the InitialDP to determine whether the dialog is a reoriginated dialog; if:

  1. The reoriginated InitialDP will be triggered on DP3 (Analyzed Info).

  2. The application context is supported. Supported application contexts are:

    • cap-v2-gsmSSF-to-gsmSCF-AC

    • capssf_scfGenericAC (CAP3).

  3. The called party is a special routing number.

Note See Correlation Resource Adaptor to understand how the Correlation resource adaptor works and how it can be queried to see if the called party is a special routing number.

Processing a reoriginated trigger

If this session corresponds is a reoriginated trigger:

  • use the correlation ID (the called party number) to get the correlated data from the Correlation RA

  • restore fields from the original InitialDP (that is stored in the correlation data) into the reoriginated InitialDP.

This is achieved with a mapper. The reorigination feature looks for a mapper:

// a mapper that takes a {{byte\[\]}} and returns a {{CAP1InitialDPArg}}
final Mapper mapper = mapperLibrary.findMapper(selectionKey, byte[].class, CAP1InitialDPArg.class);

Sentinel core bundles a mapper for this purpose (CorrelationDataToCAPInitialDP) that:

  • uses CGIN persist factory to turn this byte[] into a CAP1InitialDPArg object

  • copies the cap 1 InitialDP called party bcd number to the reoriginated InitialDP

  • copies the cap 1 InitialDP bearer capability (if present) to the reoriginated InitialDP

  • copies the cap 1 InitialDP redirecting party ID (if present) to the reoriginated InitialDP

  • copies the cap 1 InitialDP redirection information (if present) to the reoriginated InitialDP

  • copies the cap 1 InitialDP location information (if present) to the reoriginated InitialDP

  • copies the cap 1 InitialDP extensions (if present) to the reoriginated InitialDP

  • sets the InitialDP session state field with the updated reoriginated InitialDP.

Note An alternative mapper that uses a different method for reconstructing the correlated data associated with the correlation ID can be written using the Sentinel SDK.
Tip

The mapper used to reconstruct the correlated data and update the reoriginated InitialDP should be thought of as the mirror to the mapper used in step two for processing the original InitialDP. If a custom method for choosing the data to associate with the correlation ID is built with the Sentinel SDK, then two new mappers are needed that:

  • take an InitialDP and generate a byte[]

  • take a byte[] and return a CAP1InitialDPArg.

Determining service type in reoriginated dialogs

The Classify Call Scenario Feature may not be able to correctly determine that a reoriginated dialog is roaming. To ensure that the roaming indicator is set correctly, the Reorigination service must set the service type to isRoaming.

Call flow

400

Configuration

Correlation RA configuration

Note See Correlation Resource Adaptor to understand how the correlation resource adaptor works and how it can be configured.

Feature configuration

A configuration profile table is used to configure the parameters of the new DRA sent out in the first connect (Phase 1).

Parameter Type Description

Nature

CalledPartyNumber.Nature

The address nature

NumberingPlan

CalledPartyNumber.NumberingPlan

The numbering plan of the address

RoutingToInternalNetworkNumber

CalledPartyNumber.RoutingToInternalNetworkNumber

either ALLOWED or NOT_ALLOWED

Address list configuration

A VLR address list table is maintained, for the service to identify roaming partners requiring reorigination. A VLR address entry is an extension of the standard Address list entry, the addition being a listing of the set of supported application contexts:

Parameter Type Description

OriginatingContextNames

String[]

Array of context names: cap_v1_gsmSSF_to_gsmSCF_AC, cap_v2_gsmSSF_to_gsmSCF_AC, capssf_scfGenericAC

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_Reorigination_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:Reorigination:VLRAddressList

${PLATFORMOPERATOR}_Reorigination_AddressListEntryProfileTable

Feature specific Address List entry table

${SELECTIONKEY}:Reorigination:VLRAddressList:${ADDRESS}

ReoriginationConfigProfileTable

new DRA parameters

${SELECTIONKEY} (for example, OpenCloud::::)

ReoriginationCorrelationIdPools

Sets of reorigination numbers

Arbitrary eg Pool-1, however must include at least one profile named DEFAULT

CorrelationConfigTable

reorigination-correlation-ra configuration

ReoriginationCorrelationConfigProfile — can be redefined in the reorigination-correlation-ra configuration properties

Provisioning interfaces

The feature is provisioned using the web interface.

SMS Normalization Feature

Description

Feature script name

SMSNormalization

Applicable contexts

SS7 service MO SMS

SAS Support

No

Prerequisite features

Prefix And Suffix Analysis — where required

Uses the Normalization Component component to normalize the:

  • idp.CallingPartyNumber (MOSMS)

  • idp.DestinationSubscriberNumber (MOSMS)

The idp in session state is updated. All features executed after this feature will access the normalized numbers when accessing the idp in session state.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

CAP3InitialDPSMSArg

com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg

CAP-DataTypes.InitialDPSMSArg

InitialDPSMS which triggered this session, to which address normalization will be applied

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

DestinationHasChanged

boolean

true or false

Set to true only if InitialDPSMS is modified as a result of address normalization

CAP3InitialDPSMSArg

com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg

CAP-DataTypes.InitialDPSMSArg

Updated only if InitialDPSMS is modified as a result of address normalization

Error scenarios

Scenario Handling

Sessionstate CAP3InitialDPSMSArg is

null Report featureCannotStart

Initial DP SMS Arg is missing the CallingPartyNumber address

Report featureCannotStart

Initial DP SMS Arg is missing the DestinationSubscriberNumber address

Report featureCannotStart

Exception during number normalization

Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

InitialDP SMS Arg is not set in the session state or Initial DP SMS Arg is missing the CallingPartyNumber address

featureHasFinished

feature has finished

Configuration

See Normalization Component.

Configuration profile naming

See Normalization Component.

Provisioning interfaces

See Normalization Component.

SS7 Determine Network Operator Feature

Description

Feature name

SS7DetermineNetworkOperator

Applicable contexts

SS7 service

SAS Support

No

Prerequisite features

None

The SS7 Determine Network Operator Feature sets the network operator element of the Sentinel selection key for use in the selection of:

  • feature execution scripts

  • mappers

  • address lists.

The feature will set the Network Operator element of the Sentinel selection key, based on the value returned by the DetermineNetworkOperator function below.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data and updating network operator field

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>:<network>:::)

Only updated if network operator is determined

OriginatingSccpAddress

com.opencloud.slee.resources.cgin.SccpAddress

SccpAddress

Set to triggering DialogOpenRequestEvent originating address

ResponderSccpAddress

com.opencloud.slee.resources.cgin.SccpAddress

SccpAddress

Set to an address configured in Determine Network Operator address list

Error scenarios

Scenario Handling

Trigger event not a DialogOpenRequestEvent

Report featureCannotStart

Sessionstate SentinelSelectionKey is null

Report featureCannotStart

Trigger is null

Report featureCannotStart

DestinationAddress in DialogOpenRequestEvent is null

Report featureCannotStart

Could not match DestinationAddress in SS7DetermineNetworkOperatorGlobalTitleAddress

Increment CouldNotDetermineNetworkOperator
Report featureFailedToExecute

Feature responses

Response Reason

featureCannotStart

Trigger event must be DialogOpenRequestEvent, SessionState SentinelSelectionKey is not set, unsupported trigger, destination SCCP address not present in DialogOpenRequestEvent or destination SCCP GT address does not match and no default available

featureHasFinished

feature has finished

Selection

Function DetermineNetworkOperator(destinationSccpAddress.GT)

    IF destinationSccpAddress.GT not available THEN
        return default network operator value
    ENDIF

    IF destinationSccpAddress.GT address found in network operator selection table THEN
        RETURN network operator value from the matched selection table record match
    ELSE
        RETURN default network operator value
    ENDIF

The use of the destinationSccpAddress GT information is dependent on the subscriber’s HPLMN network configuration. It is possible that some networks may not pass the GT information set in the subscriber’s o-CSI or t-CSI.

Here is an example of SCCP address routing which includes the GT information:

application context: CAP-v2-gsmSSF-to-gsmSCF-AC
CAP OpenService Type: request/indication bitmask=0x1
CapOpenArg:
{
    applicationContext: 0 4 0 0 1 0 50 1
    nextBlockOpCode: not present
    originatingAddress:
    {
        P=C7, NI=0, RI=PCSSN, GTI=0,
              PC=5900, SSN=146
    }
    destinationAddress:
    {
        P=C7, NI=0, RI=PCSSN, GTI=4,
              SSN=146, TT=0, NP=1 (isdn), ES=2 (even),
              NAI=4 (international num), DIG=420603059300
    }
    gprsOriginatingReference: not present
    gprsDestinationReference: not present
    user information length: not present

}

For subscribers who are configured for intra-PLMN only, it is possible that the CSI may contain a gsmSCP address containing only PC/SSN. In this case, the feature cannot operate, as no GT information will be available.

Configuration

Network Operator Destination Global Title SCCP Address List Selection Table:

Parameter Type Example Values

Address

GT Address

642100000012

NetworkOperator

String

MVNO1

Example table:

Address NetworkOperator

642100000001

OpenCloud

642100000011

OpenNet

642100000022

CloudNet

The default network operator is stored in the Sentinel configuration table.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_SS7DetermineNetworkOperator_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:SS7DetermineNetworkOperator:GlobalTitleAddress

${PLATFORMOPERATOR}_SS7DetermineNetworkOperator_AddressListEntryTable

Feature-specific Address List entry table

${SELECTIONKEY}:SS7DetermineNetworkOperator:GlobalTitleAddress:${ADDRESS}

SentinelConfigurationTable

Sentinel configuration table (contains DefaultNetworkOperator)

SentinelConfiguration

Provisioning interfaces

The feature is provisioned using the web interface.

SS7 Subscriber Determination Feature

Description

Feature name

SubscriberDetermination

Applicable contexts

SS7 Service

SAS Support

No

Prerequisite features

Classify Call Scenario Feature

The Subscriber Determination Feature is used to determine the subscriber address, based on parameters from the InitialDP and session state.

For the prefix and exact match of MSISDNs, the following matching will be performed:

Call Type Subscriber number

MOC (Voice, Video, Fax, Data)

initialDP.callingPartyNumber

MFC (Voice, Video, Fax, Data)

initialDP.redirectingPartyID

MTC (Voice, Video, Fax, Data)

initialDP.calledPartyNumber

MOSMS

initialDPSMS.callingPartyNumber

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

InitialDP which triggered this session

Fall back to CAP3InitialDPSMSArg

CAP3InitialDPSMArg

com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg

CAP-DataTypes.InitialDPSMSArg

InitialDPSMS which triggered this session, to which address normalization will be applied

Irrelevant if InitialDPArg set, otherwise report featureFailedToExecute, featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call

Report featureFailedToExecute, featureHasFinished

Subscriber

String

MSISDN

The subscriber for this session

Proceed with subscriber determination

Outputs

Name Type Format Description

Subscriber

String

MSISDN

The subscriber address identified for this session

Error scenarios

Scenario Handling

InitialDPArg and InitialDPSMSArg not present or do not contain subscriber address

Report featureFailedToExecute

Feature responses

Response Reason

featureFailedToExecute

InitialDPArg and InitialDPSMSArg not present or do not contain subscriber address

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

SS7 Unconditional Reject Session Feature

Description

Feature name

UnconditionalRejectSession

Applicable contexts

Diameter Mediation Service

SAS Support

No

Prerequisite features

None

Unconditionally refuses the dialog with refuse reason set to USER_NO_REASON_GIVEN.

Session state inputs and outputs

This feature does not read from or write to session state.

Error scenarios

This feature always succeeds.

Feature responses

Response Reason

refuseDialog

intended behaviour

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Set User Release Cause From Latest Event Report Feature

Description

Feature name

SetUserReleaseCauseFromLatestEventReport

Applicable contexts

SS7 service

SAS Support

No

Prerequisite features

None

The Set User Release Cause From Latest Event Report feature inspects the latest EventReportBCSM received by Sentinel and if possible sets the UserReleaseCause integer session state variable to a cause code value appropriate for that event report. This feature can then be followed by the Release Call and Close Dialog Feature to have that cause code included in the ReleaseCall operation sent to the MSC.

The UserReleaseCause session state variable is set depending on the eventTypeBCSM field of the latest EventReportBCSM argument:

  • for Route Select Failure:

    • if the EventReportBCSM contains event-specific information, then the release cause is obtained from the event-specific information;

    • otherwise a default of CLASS0_NO_ROUTE_TO_DESTINATION (3) is used.

  • for Called Party Busy:

    • if the EventReportBCSM contains event-specific information, then the release cause is obtained from the event-specific information;

    • otherwise a default of CLASS1_USER_BUSY (17) is used.

  • for No Answer:

    • a default of CLASS1_NO_ANSWER (19) is used.

  • for Disconnect

    • if the EventReportBCSM contains event-specific information, then the release cause is obtained from the event-specific information;

    • otherwise a default of CLASS1_NORMAL_CALL_CLEARING (16) is used.

For any other case, including the absence of an EventReportBCSM operation to inspect, the UserReleaseCause session state variable is left untouched.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

LatestEventReportBCSM

com.opencloud.slee.resources.cgin.callcontrol.CCEventReportBCSMArg

CC-DataTypes.EventReportBCSMArg

Latest event report

Do not set release cause
report featureHasFinished

Outputs

Name Type Format Description

UserReleaseCause

Integer

Any cause value, such as Cause.CauseValue.CLASS0_NO_ROUTE_TODESTINATION, Cause.CauseValue.CLASS1USER_BUSY, Cause.CauseValue.CLASS1_NO_ANSWER, Cause.CauseValue.CLASS1_NORMAL_CALL_CLEARING

The cause value extracted from the latest event report

Error scenarios

This feature always succeeds.

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Short Code Feature

The Short Code feature is a pre-credit check feature early in the feature list (but always after the emergency number feature), to perform number translation on a set of short codes configured for the network.

Description

Feature name

ShortCode

Applicable contexts

SS7 service

SAS Support

No

Prerequisite features

Classify Call Scenario Feature

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg \

CAP-DataTypes.InitialDPArg

InitialDP which triggered this session

Report featureCannotStart, featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

If short code matched and translation was successful

DestinationHasChanged

boolean

true or false

If short code matched and translation was successful

Error scenarios

Scenario

Handling

Sessionstate SentinelSelectionKey is null

Report featureCannotStart

Sessionstate InitialDPArg is null

Report featureCannotStart

InitialDP Arg is not CAP

Report featureCannotStart

Sessionstate CallType is null

Report featureCannotStart

InitialDP missing CalledPartyBCDNumber address

Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

SessionState SentinelSelectionKey is not set, InitialDP Arg is not set in session state, InitialDP Arg is not an instance of CAP1InitialDPArg, Session Type is not set in the session state or Initial DP Arg is missing the CdPA BCD number

featureHasFinished

feature has finished

Configuration

Short Code feature configuration:

Parameters Type Description

MinLength

Integer

Minimum short code length

MaxLength

Integer

Maximum short code length

Example configuration:

MinLength

MaxLength

3

3

Short Code address list configuration:

The ShortCode address list entry is an extension of the standard Address list entry, the addition being the 'translatedAddress' field which is used for number translation:

Parameter Type Description

…​

…​

…​

TranslatedAddress

String

the value of the short code translated address (in international format)

Example configuration:

Address

TranslatedAddress

100

6422987654

200

6422123456

The shortCode address is a digit string which can contain any digits valid for the network.

TranslatedAddress is a digit string in international format.

The short code list applies to all subscribers scoped to Sentinel selection key.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

ShortCodeFeatureConfigProfileTable

Short code feature configuration

SentinelSelectionKey (for example, OpenCloud::::)

${PLATFORMOPERATOR}_ShortCode_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:ShortCode:AddressList

${PLATFORMOPERATOR}_ShortCode_AddressListEntryTable

Feature specific Address List entry table

${SELECTIONKEY}:ShortCode:AddressList:${ADDRESS}

Provisioning interfaces

The feature is provisioned using the web interface.

Validate InitialDP Feature

Description

Feature name

ValidateInitialDP

Applicable contexts

SS7 service

SAS Support

No

Typical feature execution points

DirectAccess_SessionPreCreditCheck

Prerequisite features

Classify Call Scenario Feature

The Validate InitialDP feature performs validation checks to ensure that the InitialDP has sufficient parameters to be handled correctly by Sentinel.

If the InitialDP is not valid, then the Valdiate InitialDP feature returns either continueAndClose or releaseAndClose to the Sentinel core. The choices of response and release cause are configurable. In the absence of configuration data, the default behaviour is releaseCallAndClose(Call-Rejected).

The validation performed includes:

  • check that InitialDP is present in session state

  • check that InitialDP is CAP

  • check that CallingPartyNumber is present in the InitialDP

  • if session type is mobile originating, check for presence of CalledPartyBCDNumber

  • if session type is mobile terminating or mobile forwarded, check for presence of CalledPartyNumber.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data for ValidationFailedAction if InitialDP fails validation

Runtime exception handled by feature runner

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

InitialDPArg which triggered this session

Report featureCannotStart, featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call for determining which party numbers should be present in InitialDPArg

Report featureCannotStart, featureHasFinished

Outputs

This feature does not modify session state.

Error scenarios

Scenario Handling

Sessionstate InitialDPArg is null

Report featureCannotStart

InitialDPArg is not CAP

Report featureCannotStart

Sessionstate CallType is null

Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

InitialDP is not set in session state, InitialDP is not CAP or Session Type is not set in the session state

releaseCallAndCloseDialog

Configured to release on invalid InitialDP

continueAndCloseDialog

Configured to continue on invalid InitialDP

featureHasFinished

feature has finished

Configuration

The configuration allows two options on validation failure: releaseAndClose or continueAndClose. The release cause code may be configured.

Parameter Type Description

Action

String

one of: releaseAndClose or continueAndClose

ReleaseCause

Integer

cause code

Call flow

MSC ----- OpenRequest ----> Sentinel
MSC ------ InitialDP -----> Sentinel
MSC <----- OpenAccept ----- Sentinel
MSC <--- Release(cause) --- Sentinel

The release cause will be configurable (see cause values). The default will be a cause value of CLASS1_CALL_REJECTED.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

ValidateInitialDPFeatureConfigProfileTable

Configuration of behaviour on validation failure

SentinelSelectionKey (for example, OpenCloud:OpenCloud:call::)

Provisioning interfaces

The feature is provisioned using the web interface.

Validate Third Party Call Request Feature SS7

Description

Feature name

Validate3rdPartyCallRequest

Applicable contexts

SS7 service

SAS Support

No

Typical feature execution points

This feature should run early in ThirdPartyAccess_SessionAccept

Prerequisite Features

None

The Validate 3rd Party Call Request Feature checks the received HTTP request to see if it is well formed. The SS7 service accepts HTTP requests in the following format:

http://<host>:<port>/sentinel-ss7?cgpa=642200001&cdpa=642200002

This feature checks for the presence of the cgpa and cdpa request parameters.

Note The SS7 service only accepts the HTTP request for processing if the path contains sentinel-ss7

Session state inputs and outputs

This feature does not read from or write to session state.

Error scenarios

Scenario Handling

IOException while retrieving HttpRequest content

Increment CouldNotProcessHttpRequest

Report

refuseDialog

Feature responses

Response Reason

refuseDialog

the request to set up a 3rd party call should be refused

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Voice Call Normalization Feature

Description

Feature script name

Normalization

Applicable contexts

SS7 service voice call

SAS Support

No

Prerequisite features

Prefix and Suffix Analysis — where required

Uses the Normalization Component component to normalize the:

  • idp.CallingPartyNumber (MOC, MTC, MFC)

  • idp.CalledPartyBCDNumber (MOC)

  • idp.CalledPartyNumber (MTC, MFC)

The idp in session state is updated. All features executed after this feature will access the normalized numbers when accessing the idp in session state.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For configuring normalizer

Runtime exception handled by feature runner

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

InitialDPArg which triggered this session, to which address normalization will be applied

Report featureCannotStart, featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

InitialDPArg

com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

CAP-DataTypes.InitialDPArg

Updated only if InitialDPArg is modified as a result of address normalization

DestinationHasChanged

boolean

true or false

Set to true only if InitialDPSMS is modified as a result of address normalization

Error scenarios

Scenario Handling

Sessionstate InitialDPArg is null

Report featureCannotStart

InitialDPArg is not CAP

Report featureCannotStart

Sessionstate CallType is null

Report featureCannotStart

Initial DP Arg is missing the CalledPartyNumber address

Report featureCannotStart

Initial DP Arg is missing the CalledPartyBCDNumber address

Report featureCannotStart

Initial DP Arg is missing the CallingPartyNumber address

Report featureCannotStart

Error during number normalization

Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

InitialDP has not been set in session state, InitialDP is not CAP, Session type is not set in session state, error during number normalization or Initial DP Arg is missing a required CallingPartyNumber, CalledPartyNumber or CalledPartyBCDNumber address

featureHasFinished

feature has finished

Configuration

See Normalization Component.

Configuration profile naming

See Normalization Component.

Provisioning interfaces

See Normalization Component.

SIP Features

Sentinel includes many features for SIP networks, including:

  • SIP System Features — features that make up most of the default Sentinel behaviour, and can be used in feature execution pre and post scripts

  • SIP User Features — features that can be used in feature execution user scripts

These features provide the behaviour of a third party Registrar:

Registrar System Features

Sentinel includes system features for the Registrar which handle processing a Third Party REGISTER request. These features are run using system pre and post execution scripts, before and after the user features on the same execution point with the same triggering event.

Extract Encapsulated Request and Response

The ExtractEncapsulatedRegisterRequestAndResponse feature parses the body of the triggering third party REGISTER request and extracts the 1st party REGISTER and response. These messages are stored as Java objects in session state fields.

Note

This feature is a critical system feature. The Registrar cannot function without this feature executing successfully.

See Sentinel SIP Feature Execution Points for more about running critical features.

Details

Feature script name

ExtractEncapsulatedRegisterRequestAndResponse

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

RegistrarDetermineNetworkOperator or PlatformOperatorIsNetworkOperator

Feature execution points
Pre

SipRegistration_NetworkCheck

Session state inputs and outputs

Inputs

Name Format Description

SentinelSelectionKey com.opencloud.sentinel.common.SentinelSelectionKey

selection key
for example, <platform_operator>::::

For selecting a mapper that maps third party REGISTER request to session state fields

Outputs

Name Format Description

RouteHeaderMode com.opencloud.sentinel.state.RouteHeaderMode

One of: not_present (no mode parameter in the route header), mmtel (mmtel scenario), scc (scc scenario) or mmtel_scc (mixed, mmtel and scc scenario)

EncapsulatedRegisterRequest javax.sip.message.Request

A Request Java object

The 1st party REGISTER request

EncapsulatedRegisterResponse javax.sip.message.Response

A Response Java object

The 1st party REGISTER response

RejectRegisterRequest boolean

Set to true if the third party REGISTER request should be rejected.

Feature responses

Response Reason

featureHasFinished

Feature has finished.

featureFailedToExecute

Feature encountered a fatal error and was unable to continue.

Statistics

Statistic When incremented

MappingFailureExtractingRegisterRequestAndResponse

There was a failure whilst parsing the 1st party REGISTER and response from the body of the third party REGISTER

FailedToStart

The feature fails to start.

IssuedWarning

The feature encounters a non-fatal error and alerts the core.

FailedDuringExecution

The feature encounters any fatal error and alerts the core.

TimedOut

The feature fails to complete execution within the allowable time frame.

Extract Public and Private Identities

The ExtractPublicAndPrivateIdentities feature analyses the 1st party REGISTER request and response and stores public and private indentities in session state.

Note

This feature is a critical system feature. The Registrar cannot function without this feature executing successfully.

See Sentinel SIP Feature Execution Points for more about running critical features.

Details

Feature script name

ExtractPublicAndPrivateIdentities

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

ExtractEncapsulatedRegisterRequestAndResponse

Feature execution points
Pre

SipRegistration_SessionCheck

Session state inputs and outputs

Inputs

Name Format Description

SentinelSelectionKey com.opencloud.sentinel.common.SentinelSelectionKey

selection key
for example, <platform_operator>::::

For selecting a mapper that maps 1st party REGISTER and response to public and private ids in session state fields.

EncapsulatedRegisterRequest javax.sip.message.Request

The 1st party REGISTER request

EncapsulatedRegisterResponse javax.sip.message.Response

The 1st party REGISTER response

Outputs

Name Format Description

CallId String

The value of the Call-ID header

The call id of the 1st party REGISTER request

PrivateId String

The username parameter of the Authorization header

The private id of the subscriber, taken from the 1st party REGISTER request

PublicIds String[]

The value of a P-Associated-Uri with surrounding < and > removed

Public ids of the subscriber, taken from P-Associated-Uri headers in the 1st party REGISTER response

RegisteredContact String[]

Array of Strings, where each element is value of one Contact header

All the Contact headers, from the 1st party REGISTER response

RegisteredContactUris String[]

Array of Strings, where each element is URI part of the address in one Contact header

The URI`s of the address for each `Contact header in 1st party REGISTER response

PubGruu String

A SIP URI, as a String

The public GRUU (Globally Routable User Agent) from the first Contact header in the 1st party REGISTER response (if present)

TempGruu String

A SIP URI, as a String

The temporary GRUU (Globally Routable User Agent) from the first Contact header in the 1st party REGISTER response (if present)

RejectRegisterRequest boolean

Set to true if the third party REGISTER request should be rejected.

RegistrationDeviceId String

The ID that uniquely identifies the device associated with the activation session. The value is derived based on the Registrar Configuration Table property UsePrivateIdAsRegistrarDataPrimaryKey. If UsePrivateIdAsRegistrarDataPrimaryKey is true, then RegistrationDeviceId is set to the set to the value of the private ID. Otherwise, it is set to the value of the call ID.

Feature responses

Response Reason

featureHasFinished

Feature has finished.

featureFailedToExecute

Feature encountered a fatal error and was unable to continue.

Statistics

Statistic When incremented

MappingFailureExtractingSubscriberIds

There was a failure whilst extracting ids from the 1st party register request and response.

FailedToStart

The feature fails to start.

IssuedWarning

The feature encounters a non-fatal error and alerts the core.

FailedDuringExecution

The feature encounters any fatal error and alerts the core.

TimedOut

The feature fails to complete execution within the allowable time frame.

Registrar User Features

Sentinel features that provide most of the default Sentinel behaviour.

Accept REGISTER Request

The AcceptRegisterRequest feature creates and sends a 200 OK SIP response on the SIP leg for the triggering REGISTER request.

Details

Feature script name

AcceptRegisterRequest

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None

Feature responses

featureFailedToExecute()

If there is an error creating the 200 OK response, or if the calling SIP leg is not associated with a REGISTER request.

featureHasFinished()

Once the feature finishes

Determine Public Identities

Description

This feature checks and retrieves Public ID information for a registration.

Prerequisite features

Session state inputs and outputs

Inputs

SentinelSelectionKey

A selection key with the platform operator, network operator, session type and plan-id set (such as OpenCloud:OpenCloud:eSRVCCRegistration:register:)

PreviousRegistrationData

A list of registration records including all preexisting, active registrations associated with the subscriber and call ID.

PublicIds

A list of public IDs that have already been extracted from encapsulated first-party registration data.

Outputs

PublicIds

The list of public IDs for the registration.

Feature responses

rejectRegisterRequest()

If the list of public IDs for the registration is empty once the feature has completed its analysis.

featureHasFinished()

Once the feature has finished

Statistics

DeterminePublicIdentities statistics are tracked by the DeterminePublicIdentities feature and can be found under the following parameter set:
SLEE-Usage ▶ sentinel.registrar service ID ▶ sentinel.registrar SBB ID ▶ DeterminePublicIdentities.

Name Type Description 
Started

Counter

Incremented when the feature runs.

 
FailedToStart

Counter

Incremented when Sentinel Registrar encounters an error while attempting to start the feature.

 
IssuedWarning

Counter

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

 
FailedDuringExecution

Counter

Incremented when a fatal problem is encountered and the feature cannot execute correctly.

 
TimedOut

Counter

Incremented when the feature takes too long to complete and Sentinel Registrar aborts execution.

 
RetrievedIdsFromPAssociatedUris

Counter

Incremented when a mapper has already successfully retrieved the public identities from encapsulated data.

 
RetrievedIdsFromPreviousRegistration

Counter

Incremented when the feature is able to retrieve public identities from previous registration data.

 
FailedToRetrieveIds

Counter

Incremented when no public identities can be determined.

Behaviour

This feature is responsible for ensuring that the public identities for the served user are present in session state. It is also responsible for refusing a REGISTER request when public identities cannot be determined.

Under normal circumstances the public identities are pulled into session state by extracting them from the P-Associated-URI header on the encapsulated first-party registration message within the third-party REGISTER request. This is done by a mapper prior to this feature running.

Initially this feature will check if the mapper was successful in extracting the public identities. If it was successful the feature will increment a statistic and complete execution with no further changes. If the mapper was unsuccessful, the feature will do one of the following:

  1. If the REGISTER request is for de-registration and third-party registration data is currently stored in a Cassandra database, then the feature will attempt to retrieve public identities from the most recent active registration for the served user. If this is successful the feature will populate session state with the retrieved identities and complete execution. If it is unsuccessful the feature will reject the REGISTER request.

  2. If the REGISTER request is for registration or re-registration, or third-party registration data is currently stored in the HSS; then the feature will immediately reject the REGISTER request.

Determine Registration Action Type

This feature classifies a REGISTER request according its type (register, re-register, or de-register).

Classifying a REGISTER request

The DetermineRegistrationActionType feature examines the Contact headers of the first-party REGISTER request received in the body of the third-party REGISTER request.

A register is present if for any contact header:

  • the contact header expires parameter is present and is not zero

  • the contact header expires parameter is not present, but the request expires header is present and is not zero

A de-register is present if for any contact header:

  • the contact header expires parameter is present and zero

  • the contact header address is a wildcard and the request expires header is present and zero

  • the request expires header is present and zero and the contact header expires parameter is not present

The action that should be taken is based on the following table:

Table 1. Actions
register is present de-register is present have previous registration data action

false

true

-

de-register

true

true

-

re-register

-

false

true

re-register

-

false

false

register

Details

Feature script name

DetermineRegistrationActionType

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

Session state inputs and outputs

Inputs

SentinelSelectionKey

A selection key with the platform operator, network operator and session type set (such as OpenCloud:OpenCloud:eSRVCCRegistration::)

EncapsulatedRegisterRequest

The first-party REGISTER request that was in the body of the third-party REGISTER request received by the registrar.

PreviousRegistrationData

A list of registration records including all pre-existing, active registrations associated with the subscriber and call ID.

Outputs

SentinelSelectionKey

A selection key with the platform operator, network operator, session type and plan-id set (such as OpenCloud:OpenCloud:eSRVCCRegistration:de-register:)

RejectRegisterRequest

Set to true, if the first-party REGISTER request could not be analysed. For example, if the REGISTER request has a Contact with a wildcard address, while its Expires header is absent, or not equal to zero

Feature responses

featureHasfinished()

Once the feature has finished

Determine Registration Session Type

This feature classifies a REGISTER request according to how it should be handled.

Determining the Registration type

The DetermineRegistrationSessionType classifies the session as Regular3rdPartyRegistration.

Details

Feature script name

DetermineRegistrationSessionType

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

Session state inputs and outputs

Inputs

SentinelSelectionKey

A selection key with the platform operator and network operator set (such as OpenCloud:OpenCloud:::)

EncapsulatedRegisterRequest

The first-party REGISTER request that was in the body of the third-party REGISTER request received by the registrar

Outputs

SentinelSelectionKey

A selection key with the platform operator, network operator, and session type set (such as OpenCloud:OpenCloud:Regular3rdPartyRegistration::)

Feature responses

featureCannotStart()

If the first-party REGISTER request does not contain a Feature-Caps header

featureHasfinished()

Once the feature has finished

Statistics

Parameter …​ incremented if …​

Regular3rdPartyRegistration

The session is a regular third-party registration scenario

Determine Visited Network

This feature extracts a value from the p-visited-network-id header(s) that is to be included in registration data.

Tip

The p-visited-network-id header is defined in http://www.ietf.org/rfc/rfc3455.txt

The P-Visited-Network-ID header field is used to convey to the registrar or home proxy in the home network the identifier of a visited network.

The identifier is a text string or token that is known by both the registrar or the home proxy at the home network and the proxies in the visited network.

This feature uses the value of the first p-visited-network-id header. If the value is a string then the " characters are removed.

Details

Feature script name

DetermineVisitedNetwork

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

Session state inputs and outputs

Inputs

SentinelSelectionKey

A selection key with the platform operator and network operator set (such as OpenCloud:OpenCloud:::)

EncapsulatedRegisterRequest

The first-party REGISTER request that was in the body of the third-party REGISTER request received by the registrar

Outputs

VisitedNetwork

The value of the visited network id the registrar should store in registration data related to the current REGISTER request

Feature responses

featureHasfinished()

Once the feature has finished

Fetch Previous Registration Data

This feature retrieves any pre-existing active registrations associated with the incoming REGISTER request, and places it in a session state field where it can be accessed and used by other features. It will ignore expired registrations.

Details

Feature script name

FetchPreviousRegistrationData

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

Session state inputs and outputs

Inputs

NetworkOperator

The network operator, used for looking up registration data.

RegistrationDeviceId

The ID that uniquely identifies the device associated with the activation session.

PublicIds

The public IDs for the subscriber, used for looking up registration data.

Outputs

PreviousRegistrationData

A list of registration records including all pre-existing, active registrations associated with the subscriber and call ID.

Feature responses

featureHasfinished()

Once the feature has finished

Registrar Determine Network Operator

:toclevels:4 :toc-title: On this page…​

This feature determines which network operator a REGISTER request is related to.

Determining the network operator

This feature adopts three techniques to determine the network operator:

Special header in the third-party REGISTER request

If the REGISTER request contains a sentinel-network-operator header, then the network operator is the value of this header. For example, a REGISTER request, such as the one shown below, returns a network operator ‘HomeOneNet’.

REGISTER sip:registrar.home1.net:5060 SIP/2.0
...
From: <sip:scscf1.home1.net>;tag=m1xC8Q
To: <sip:user1_public1@home1.net>
...
sentinel-network-operator: HomeOneNet

If the header is present, but empty, then treat this as if there was not header present and try the next technique.

Look up the network operator in feature configuration data

This RegistrarStg:feature has configuration data that is a lookup table key → network operator. The feature uses a RegistrarStg:mapper IncomingSipRequest.class → String.class @ RegistrarMappingPoint.DetermineNetworkOperator.

The mapper included with the registrar returns the host from the To address as the lookup key. For example, a REGISTER request, such as the one shown below, results in a lookup key of ‘home1.net’.

REGISTER sip:registrar.home1.net:5060 SIP/2.0
...
From: <sip:scscf1.home1.net>;tag=CefmLQ
To: <sip:user1_public1@home1.net>
...

The feature uses this lookup key to find a network operator. If there is no network operator that corresponds to this key, then try the next technique.

Details

Feature script name

RegistrarDetermineNetworkOperator

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None

Session state inputs and outputs

Inputs

SentinelSelectionKey

A selection key with the platform operator set (such as OpenCloud::::)

Outputs

SentinelSelectionKey

A selection key with the platform operator and network operator set (such as OpenCloud:HomeOneNet:::)

Mappers

This feature uses a mapper that conforms to:

Mapping Mapper Execution Point

IncomingSipRequest.class → String.class

RegistrarMappingPoint.DetermineNetworkOperator

Feature responses

featureFailedToExecute()

FeatureError.Cause.invalidConfiguration — Could not determine Network Operator, and no default is configured.

featureHasFinished()

Once the feature has finished execution.

Statistics

Stats interface

DetermineNetworkOperatorStats

Parameter set to monitor

SLEE-Usage.Services.ServiceID\[RegistrarStg:name=sentinel.registrar,vendor=OpenCloud,version=1.0].SbbID\[RegistrarStg:name=sentinel.registrar,vendor=OpenCloud,version=1.0].(default)
Parameter …​ incremented if …​

CouldNotDetermineNetworkOperator

If the network operator cannot be inferred by analysis of the REGISTER request and there is no platform-level default network operator configured.

Error scenarios

Error Scenario for error

This feature signals an error to the registrar core, and increments a statistic

If it could not determine network operator, and there is no platform-level default network operator configured

Configuration

  • A profile table called SentinelRegistrarNetworkOperatorProfileTable.

    Each profile in the table:

    Parameter Type

    LookupKey

    java.lang.String

    NetworkOperator

    java.lang.String

    For example:

[Rhino@localhost (#3)] listprofileattributes SentinelRegistrarNetworkOperatorProfileTable home1.net
LookupKey=home1.net
NetworkOperator=HomeOneNet

  • The default network operator, which is in the Sentinel configuration table.

Provisioning interfaces

The feature is provisioned using the web interface.

Registrar Platform Operator Is Network Operator

The feature updates the Sentinel selection key so that the network operator is the same as the configured platform operator.

Details

Feature script name

RegistrarPlatformOperatorIsNetworkOperator

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None

Session state inputs and outputs

Interface

SentinelRegistrarSessionState

Inputs

SentinelSelectionKey

A selection key with the platform operator set (such as OpenCloud::::).

Outputs

SentinelSelectionKey

A selection key with the network operator set to the value of the platform operator (such as OpenCloud:OpenCloud:::).

Feature responses

This feature always succeeds and responds to the registrar core with featureHasFinished().

Reject REGISTER Request

The RejectRegisterRequest feature issues a SIP error response on the triggering REGISTER leg.

Choosing the SIP error response code

The RejectRegisterRequest uses the RejectRegisterResponseCode session state field if it is set. Otherwise the error response code is derived from the RouteHeaderMode session state field in the following way:

RouteHeaderMode SIP Error response code

mmtel

SipResponse.SC_OK

scc or mmtel_scc

SipResponse.SC_REQUEST_TERMINATED

not_present

SipResponse.SC_REQUEST_TERMINATED

Details

Feature script name

RejectRegisterRequest

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None

Session state inputs and outputs

Inputs

Name Format Description

RouteHeaderMode com.opencloud.sentinel.state.RouteHeaderMode

One of: not_present (no mode parameter in the route header), mmtel (mmtel scenario), scc (scc scenario) or mmtel_scc (mixed, mmtel and scc scenario)

RejectRegisterResponseCode Integer

An Integer Java object

The SIP error response code to use when rejecting the third party REGISTER request

Feature responses

This feature always responds featureHasFinished().

Remove Registration

This feature removes all third party registration-related state associated with the Registration from the persistent storage mechanism. It is similar to the Store Subscriber Data feature in the sense that it uses the same storage mechanisms.

This feature is intended for use upon De-Registration.

Details

Feature script name

RemoveRegistration

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

Session state inputs and outputs

Inputs

SentinelSelectionKey

A selection key with the platform operator, network operator, session type, and plan-id set. The plan-id must be set to de-register (such as OpenCloud:OpenCloud:ESRVCCRegistration:de-register:)

RegistrationDeviceId

The ID that uniquely identifies the device associated with the activation session.

PrivateId

The private-id of the UE

Feature responses

featureFailedToExecute()

If the request made by the registrar core to remove registration information is rejected by the data store sub-system

featureHasFinished()

Once the feature finishes

Schedule Reject REGISTER Request

The ScheduleRejectRegisterRequest feature sets the RejectRegisterRequest session state field to true. This session state field can be tested in feature execution scripts to decide what features should run (for example RejectRegisterRequest).

Details

Feature script name

ScheduleRejectRegisterRequest

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None

Feature responses

featureHasFinished()

Once the feature finishes

Store Subscriber Data

The feature stores third party registration data from session state fields into the configured Data Storage. This feature is intended for use upon Initial Registration and Re-Registration. It is an extensible feature that supports multiple storage models. The default storage model is:

The property SubscriberDataFacadeType in the Registrar Configuration Table indicates the Data Storage to be used.

Details

Feature script name

StoreSubscriberData

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

Session state inputs and outputs

Inputs

SentinelSelectionKey

A selection key with the platform operator, network operator, session type, and plan-id set. The plan-id must be set to register or re-register (such as OpenCloud:OpenCloud:ESRVCCRegistration:register:)

RegistrationDeviceId

The ID that uniquely identifies the device associated with the activation session

CallId

The call-id associated with the activation session

PrivateId

The private-id of the UE

PublicIds

The list of public IDs provided in the 3rd party registrar message

Contacts

The contacts provided in the 3rd party registrar message. If there are two or more contacts the feature will add the parameter oc-ue-contact to the contact that is related to the device.

TemporaryGruu

The temporary Gruu provided in the 3rd party registrar message

Gruu

The Gruu provided in the 3rd party registrar message

CMSISDN

The CMSISDN fetched from HSS

MSRN

The MSRN fetched from HLR

VisitedNetwork

The visited network fetched from the sip message

STNSR

The Session Transfer Number for SRVCC

CurrentATUSTI

The ATU-STI configured for the SCC AS

AtcfMgmtUri

The ATCF Management URI from Feature-Caps header in the initial first-party REGISTER request

AtcfPathUri

The ATCF Path URI from Feature-Caps header in the initial first-party REGISTER request

Extensions

The Extensions map is a general purpose storage location for key/value pairs. It’s currently used by Registrar to store PATH headers received in a third party REGISTER.

Feature responses

featureFailedToExecute()

If the request made by the registrar core to store registration information is rejected by the data store sub-system

featureHasFinished()

Once the feature finishes

Write Registrar Audit CDR

The WriteRegistrarAuditCdr feature writes an audit Call Detail Record (CDR) that summarises the action taken on the triggered REGISTER request. The behaviour of the WriteRegistrarAuditCdr feature can be influenced by the platform level registrar configuration (Registrar Configuration Table). In particular:

Field Name Description

WriteAuditCdr

This property is true if audit CDRs should be written. The default value is false.

AuditCdrPrivateIdFilter

A private-id for which an audit CDR should be written. This setting has the highest priority and over-rides 'WriteAuditCdr'. Values of null or "" are ignored. If the private-id that the registrar has extracted from the 1st party REGISTER request and response is equal to the value of AuditCdrPrivateIdFilter then an audit CDR is written.

CdrStreamName

The cdr stream where audit CDRs are written

If there is a failure of any kind the WriteRegistrarAuditCdr feature will attempt to write the CDR as a warning trace message and increment relevant statistics.

Details

Feature script name

WriteRegistrarAuditCDR

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None

Feature responses

featureFailedToExecute()

If the CDR resource adaptor is not operational, there was a failure creating a Call Detail Record, or there was a failure to write the Call Detail Record.

featureHasFinished()

Once the feature finishes

Statistics

Statistic When incremented

MappingFailureCreatingCdr

There was a failure whilst creating the CDR

FailedToWriteCdr

Either the CDR resource adaptor was not operational, or there was a failure whilst writing the CDR.

FailedDuringExecution

The feature encounters any fatal error and alerts the core.

SIP System Features

Sentinel includes many system features for SIP networks which handles default system behaviour. These features are run using system pre and post execution scripts, before and after the user features on the same execution point with the same triggering event.

Determine Session Replication

This feature reads configuration and sets up triggers in the Sentinel SIP service, that will cause session replication to begin at certain points in a call.

Details

Feature Script Name

DetermineSessionReplication

Applicable Contexts

SIP service

Call-Type

All

Session Plan

All

Execution Point

SipAccess_SessionStart and SubscriptionStart (in system pre-scripts)

Network Operator Config

Yes

Subscriber Config

None

POJO or SBB

POJO

Feature FSMs

None

Feature Parameters

None

SAS Support

No

Prerequisite features

None

Feature Statistics

DetermineSessionReplication statistics are tracked by the sentinel.sip SBB and can be found under the following parameter set:
SLEE-Usage → sentinel.sip service ID → sentinel.sip SBB ID → feature.DetermineSessionReplication

Name Type Description 
Started

Counter

Incremented when the feature is triggered.

 
FailedToStart

Counter

Incremented when the feature fails to start.

 
FailedDuringExecution

Counter

Incremented when the feature fails while executing.

 
IssuedWarning

Counter

Incremented when the feature issues a warning.

 
TimedOut

Counter

Incremented when the feature times out during execution.

 
SessionReplicationDisabledForSession

Counter

Incremented when the feature determines that replication will never be enabled for the current session.

 
ArmedReplicationTriggerOnSubscriptionUASLegs

Counter

Incremented when the feature sets up a replication trigger for subscription user-agent-server legs.

 
ArmedReplicationTriggerOnSubscriptionUACLegs

Counter

Incremented when the feature sets up a replication trigger for subscription user-agent-client legs.

 
ArmedReplicationTriggerOnInviteUASLegs

Counter

Incremented when the feature sets up a replication trigger for invite user-agent-server legs.

 
ArmedReplicationTriggerOnInviteUACLegs

Counter

Incremented when the feature sets up a replication trigger for invite user-agent-client legs.

 
ImmediateSessionReplicationEnableTriggered

Counter

Incremented when the feature immediately enables session replication for a session.

Configuration

This feature reads configuration from the SipSessionReplicationConfigProfileTable profile table. Profiles in this table are named based on the Sentinel selection key that they should be applied to.

The profile specification for this table is sentinel-sip-session-replication-profile. Each profile in this table has four fields that are used to indicate the point in a call that session replication should begin. Each of the four fields corresponds to a different type of leg. The fields use Enums to define the points in the call that session replication can begin. There are two different Enum types, one for legs initiated by SIP REFER or SUBSCRIBE requests, and one for legs initiated by INVITE requests.

The four fields on the profiles are:

Field Name Enum Type Purpose 
InviteUASLegReplicationTrigger
 
InviteReplicationTrigger

Determines the point in the signalling on a INVITE user-agent-server leg at which replication will be enabled.

 
InviteUACLegReplicationTrigger
 
InviteReplicationTrigger

Determines the point in the signalling on a INVITE user-agent-client leg at which replication will be enabled.

 
SubscriptionUASLegReplicationTrigger
 
SubscriptionReplicationTrigger

Determines the point in the signalling on a SUBSCRIBE or REFER user-agent-server leg at which replication will be enabled.

 
SubscriptionUASLegReplicationTrigger
 
SubscriptionReplicationTrigger

Determines the point in the signalling on a SUBSCRIBE or REFER user-agent-client leg at which replication will be enabled.

The possible values for each of the two different Enum types are outlined below.

InviteReplicationTrigger Enum

Enum Value Description 
DISABLED

Replication is prevented for this leg. All upstream and downstream legs in the same session are also excluded from replication.

 
NOOP

No replication decision will be made by this leg, see partner trigger (UAC/UAS) for subsequent replication behaviour.

 
INITIAL_REQUEST

Replication will begin as soon an initial INVITE request is seen on a leg of this type.

 
PROVISIONAL_RESPONSE

Replication will begin as a 18x response for the initial INVITE request is seen on a leg of this type.

 
RINGING_RESPONSE

Replication will begin when a 180 response for the initial INVITE request is seen on a leg of this type.

 
SUCCESS_RESPONSE

Replication will begin when a 2xx response for the initial INVITE request is seen on a leg of this type.

 
ACK

Replication will begin when an ACK for a 2xx response for the initial INVITE request is seen on a leg of this type.

SubscriptionReplicationTrigger Enum

Enum Value Description 
DISABLED

Replication is prevented for this leg. All upstream and downstream legs in the same session are also excluded from replication.

 
NOOP

No replication decision will be made by this leg, see partner trigger (UAC/UAS) for subsequent replication behaviour.

 
INITIAL_REQUEST

Replication will begin as soon an initial SUBSCRIBE or REFER request is seen on a leg of this type.

 
SUCCESS_RESPONSE

Replication will begin when a 2xx response for the initial SUBSCRIBE or REFER request is seen on a leg of this type.

Behaviour

This feature reads configuration data from the SipSessionReplicationConfigProfileTable profile table, and uses it to set up triggers in the SIP service that will initiate session replication. When reading from the profile table, the feature will select the profile that best matches the current Sentinel selection key.

The feature sets the triggers by setting special session state fields that are checked by the Sentinel SIP service when it hits key points in a call flow. If the service decides it has reached or passed the point in the call the the trigger corresponds to, it will instruct the Sentinel SIP Leg Manager to begin session tracking on all current and future legs (See External Session Tracking for details of how legs are tracked).

If all legs in a session are configured NOOP Rhino will initiate persistence automatically after the session reaches maxPersistDeferredTransactionAge.

If the feature is unable to find any suitable profile for the current session, it will not set any triggers. This effectively disables session replication for the session.

Warning If either UAC or UAS legs are set to DISABLED, a later execution point cannot then enable replication. IE. it is an error to set InviteUACLegReplicationTrigger to DISABLED and InviteUASLegReplicationTrigger to ACK

Special Handling for Initial Request Triggers

There is special handling in the feature for user-agent-server legs that have an INITIAL_REQUEST trigger. If InviteUASLegReplicationTrigger config is set to INITIAL_REQUEST and the feature was triggered on an INVITE request, or SubscriptionUASLegReplicationTrigger config is set to INITIAL_REQUEST and the feature was triggered on an SUBSCRIBER or REFER request, then the feature itself will immediately instruct the Leg Manager to begin session tracking, bypassing the need to wait for the service to do it.

Session Ownership Facility Availability

Before it attempts to read any configuration the feature will check whether the Rhino Session Ownership Facility is available on the node. If the feature determines that the session ownership facility is not available, it will skip loading config, and disable session replication for the session.

External Session Tracking

This feature creates and maintains records in the Rhino Session Ownership Facility for all SIP legs that have been flagged for tracking.

Details

Feature Script Name

ExternalSessionTracking

Applicable Contexts

SIP service

Call-Type

All

Session Plan

All

Execution Point

Most SipAccess, SipMidSession, Subscription, and EndSession system post-scripts

Network Operator Config

None

Subscriber Config

None

POJO or SBB

POJO

Feature FSMs

None

Feature Parameters

None

SAS Support

No

Prerequisite features

None

Feature Statistics

ExternalSessionTracking statistics are tracked by the sentinel.sip SBB and can be found under the following parameter set:
SLEE-Usage → sentinel.sip service ID → sentinel.sip SBB ID → feature.ExternalSessionTracking

Name Type Description 
Started

Counter

Incremented when the feature is triggered.

 
FailedToStart

Counter

Incremented when the feature fails to start.

 
FailedDuringExecution

Counter

Incremented when the feature fails while executing.

 
IssuedWarning

Counter

Incremented when the feature issues a warning.

 
TimedOut

Counter

Incremented when the feature times out during execution.

 
RequestedStore

Counter

Incremented when the feature attempts to store a record in the session ownership facility.

 
StoreSuccess

Counter

Incremented when the Session Ownership Facility successfully stores a full record.

 
StorePartialFailure

Counter

Incremented when the Session Ownership Facility fails to store some parts of a record.

 
StoreFailure

Counter

Incremented when the Session Ownership Facility fails to store any parts of a record.

 
RequestedDelete

Counter

Incremented when the feature attempts to remove a record from the session ownership facility.

 
DeleteSuccess

Counter

Incremented when the Session Ownership Facility successfully deletes a full record.

 
DeletePartialFailure

Counter

Incremented when the Session Ownership Facility fails to delete some parts of a record.

 
DeleteFailure

Counter

Incremented when the Session Ownership Facility fails to delete any part a record.

 
StartedSessionOwnershipActivity

Counter

Incremented when the feature starts a new session ownership activity.

 
EndedSessionOwnershipActivity

Counter

Incremented when the feature ends its session ownership activity.

 
FoundNewDialogIdThatRequiresTracking

Counter

Incremented when the feature detects that a new leg needs to be tracked, or that an existing tracked leg’s dialog ID has changed.

 
FoundDialogIdRequiringUpdate

Counter

Incremented when the feature detects that a leg has new information that needs to be tracked on its session ownership record.

 
FoundDialogIdDueForRefresh

Counter

Incremented when the feature detects that a leg’s session ownership record is approaching its TTL expiration, and needs to be refreshed.

 
ChangedOwnershipOfLeg

Counter

Incremented when the feature changes the owner of a session (SIP Dialog) from one node to a different node.

 
ChangedOwnershipOfCharging

Counter

Incremented when the feature changes the owner of a Charging Instance (Ro Dialog) from one node to a different node.

 
SuccessfulQueryTime

Sample

Samples the time taken for a success response to be received from the session ownership facility for any given request.

 
PartiallyFailedQueryTime

Sample

Samples the time taken for a partial failure response to be received from the session ownership facility for any given request.

 
FailedQueryTime

Sample

Samples the time taken for a failure response to be received from the session ownership facility for any given request.

Behaviour

This feature monitors all legs in a session, regularly checking if any of the legs require a session ownership record, and if so, what information should be stored in that record. The feature maintains its own list of which legs currently have records in the session ownership facility, and when those records were last updated.

The exact behaviour of the feature differs based on how it is invoked:

  • If the feature is invoked at the SipEndSession feature execution point, it will execute End Session Clean-Up behaviour.

  • If it is invoked at any other feature execution point, it will execute Leg Tracking behaviour, followed by Charging Instance Tracking behaviour.

  • If the feature is invoked with a SessionOwnershipWriteResultEvent via the Session Ownership Event Handler, it will execute Result Processing behaviour.

Session Ownership Records for protocol dialogs

Session ownership records are used to track information about specific sessions across multiple Rhino nodes. Their main purpose it to indicate which node is currently responsible for processing a session, but they can also be used for other information that Sentinel features might need to keep track of across nodes. They are stored the in Rhino Session Ownership Facility.

Sentinel SIP has the capability to maintain zero or one session ownership records for a SIP leg, and zero or one session ownership records for an Ro Dialog. Session ownership records are not maintained for all legs at all times, instead individual legs can be flagged for tracking in the session ownership facility. When that flag is seen by this feature, it will create a session ownership record for the leg. The flag can be set by the Sentinel SIP service when session replication is triggered, or by user features that need a leg to be tracked for their own purposes.

If the Sentinel Session has an Ro dialog, and at least one SIP leg is tracked, then the Ro session is tracked.

All protocol dialog session ownership records created, or updated by this feature are linked to the Sentinel Session’s Convergence Name Session Ownership Record. This ensures that after a fail-over, any simultaneous signalling will resolve to a single node.

Fields on a SIP Dialog Session Ownership Record

Certain fields on the Sentinel SIP Leg API are used to populate associated fields on a session ownership record. The following table outlines the relationship between data stored using the Leg API, and data stored on a session ownership record.

Session Ownership Record Field Corresponding Leg API Getter Corresponding Leg API Setter Notes

PrimaryKey

 
getDialogID().toTrackingKey()
 
N/A

The primary key cannot be modified and is always based on the SIP Dialog ID associated with the leg.

OwnerURI

 
getOwner()
 
setOwner()

While the owner can be modified by other features, it should generally be left to this feature to set it.

AdditionalKeys

 
getAdditionalTrackingKeys()
 
setAdditionalTrackingKeys()

-

Attributes

 
getAdditionalTrackedAttributes()
 
setAdditionalTrackedAttributes()

-

The dialog ID of a leg is used as the primary key for the session ownership record. This means that if the dialog ID changes (e.g. when the dialog is confirmed by the remote party) a new record is created and the old one is deleted.

There are a few other SIP Leg API calls that relate to Session Ownership Records: - setTrackingEnabled() and isTrackingEnabled() are used set and read the flag that determines whether a session ownership record will be created for a leg. - setWaitForTrackingResultEnabled() and `isWaitForTrackingResultEnabled() are used to set and read a flag that affects how this feature manages asynchronous queries to the session ownership facility (see below). - getLastTrackingDataChangeTime() provides the timestamp of the last time that a call to any of: setTrackingEnabled(), setOwner(), setAdditionalTrackingKeys(), or setAdditionalTrackedAttributes() on the Leg API actually resulted in a meaningful change in the leg’s tracked state.

Fields on a Ro Dialog Session Ownership Record

Certain fields on the Sentinel SIP ChargingInstance API are used to populate associated fields on a session ownership record. The following table outlines the relationship between data stored using the ChargingInstance API, and data stored on a session ownership record.

Session Ownership Record Field Corresponding ChargingInstance API Getter Corresponding CharingInstance API Setter Notes

PrimaryKey

 
getTrackingKey()
 
N/A

The primary key cannot be modified and always includes the Ro session identifer.

OwnerURI

 
getOwner()
 
setOwner()

While the owner can be modified by other features, it should generally be left to this feature to set it.

Leg Tracking

When the feature is invoked to do standard tracking behaviour, it will get the set of current legs from the leg manager and iterate over it. For each leg in the set, the feature will go through the following steps:

  1. Check if the leg is flagged for tracking.

    • If it is not it will skip the remaining steps and move on to the next leg.

    • If it is flagged for tracking, the feature will move on to the next step.

  2. Check if there is already a session ownership record stored under the leg’s Dialog ID.

    • If not, the feature will create a new record and write it into the session ownership facility. The remaining steps will then be skipped and the feature will move on to the next leg.

    • If so, it will move on to the next step.

  3. Check if the owner node in the record matches the node currently executing the feature.

    • If not, a fail-over has occurred and the feature will take ownership of the leg (using Leg.setOwner()), and write an updated record into the session ownership facility (indicating that the owning node is the currently executing node). Then skip the remaining steps and move on to the next leg.

  4. Check when the tracked data on the leg was last modified against the last time that the session ownership record was updated.

    • If the leg’s tracked data has been modified since the last time the session ownership record was updated, then the feature will create and write an updated record into the session ownership facility. It will then skip the remaining step and move on to the next leg.

  5. Check whether the record’s TTL could expire before the feature is next invoked.

    • If so, then the existing record will be rewritten into the session ownership facility with a refreshed TTL.

    • Otherwise the feature will move on to the next leg.

After processing all of the legs, the feature will look for any records it has stored under Dialog IDs that no longer correspond to any leg that has tracking enabled. If it finds any such records, it will delete them from the facility.

All store and delete requests sent to the session ownership facility are executed asynchronously. The value of isWaitForTrackingResultEnabled() on the Leg API will affect the feature’s behaviour while it waits for the result for requests relating to that leg’s session ownership record. If any leg that has an outstanding store request to session ownership facility returns true for that API call, the feature will enter a featureWaiting state while it has nothing to do. This will prevent the session plan advancing to the next feature while the session ownership request is in progress. This is useful if further down the session plan, there is a feature that requires the session ownership record to be in place. If all legs with outstanding requests return false, then the feature will enter the featureHasFinished state while it waits, and session processing will continue in the mean time. The feature will not normally enter the featureWaiting state for delete requests.

This means that the feature can block further SIP signalling progress until a write has either succeeded, failed or timed out on a per-leg basis. There are several application specific use-cases where the database state (behind the session ownership facility) must be visible before further SIP signalling proceeds.

Charging Instance Tracking

When the feature is invoked to do standard tracking behaviour, it first checks if any SIP legs are tracked and if so it checks if a Charging instance exists and is not in the Final state. This essentially means that if Diameter Ro charging is in-use, and Session Replication is enabled, then the Ro session is tracked.

The feature goes through the following steps to determine if the Charging Instance (Ro Session) should be tracked:

  1. Check if there is already a session ownership record stored under the Ro Dialog’s tracking key (this is a value that includes the Ro session identifier)

    • If not, the feature will create a new record and write it into the session ownership facility, and further steps are skipped

  2. Check if the owning node in the record matches the node currently executing the feature.

    • If not, a fail-over has occurred, and the feature writes an updated record indicating that the owning node is the currently executing node. Further steps are skipped.

  3. Check when the tracked data on the Charging Instance was last modified against the last time that the session ownership record was updated. If an update is needed the feature updates the record in the session ownership facility and skips the remaining steps.

  4. Check whether the record’s TTL could expire before the feature is next invoked. If so the existing record is rewritten into the session ownership facility with a refreshed TTL.

All store and delete requests sent to the session ownership facility are executed asynchronously. The feature does not enter a waiting state for a Charging Instance’s session tracking write response (success, failure or timeout).

Result Processing

When a result is received from the session ownership facility, the feature simply records statistics and logs messages based on whether the result is successful, partially successful, or unsuccessful. After processing the result, the feature will decide to enter a featureWaiting or featureHasFinished state based on the same criteria used in Leg Tracking behaviour.

End Session Clean-Up

When the feature is triggered at session end, it create delete requests for all remaining session ownership records associated with the session. While under normal circumstances, the feature would not enter the featureWaiting state for delete requests, during end session behaviour the feature will keep going into the featureWaiting state until ALL outstanding requests are answered. This prevents to session from ending until all records have been handled.

AVP CDR Feature

SipAvpCdr is a system feature that is responsible for building a Call Detail Record that reflects the actions taken whilst processing a session.

SipAvpCdr runs once when a session is ending and creates a CDR based on information gathered from session state, and then writes it out using the cdr-ra.

Tip

By default, Sentinel runs SipAvpCdr as the very last feature in the post SIP end session feature execution script. For example:

featurescript PostEndSession {
    run DetermineCauseCode
    run DiameterServiceInfo
    run SipAvpCdr
}

Details

Feature script name

SipAvpCdr

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None, but information from various features is used if available

Session state inputs and outputs

Inputs

If any of these fields are unset the feature will skip writing them to the CDR file.

Name Type Description Where set

CalledPartyAddress

String

The address of the called party

CallPartiesAddressDetermination feature

CallId

String

The unique ID of the call

DiameterServiceInfo feature

CallingPartyAddress

String

The address of the calling party

CallPartiesAddressDetermination feature

CallType

Enumerated

The type of the call. One of MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, or EmergencyCall

DetermineCallType feature, SipThirdPartyHttpTrigger feature

ChargingResult

int

The result code of the Diameter session

Sentinel SIP service

DiameterServiceContextId

String

The Diameter context ID of the relevant service

AcceptSip feature, SipThirdPartyHttpTrigger feature

EndSessionCause

Integer

The end session cause code

LegManager

EventId

String

  • For SUBSCRIBE and NOTIFY events, the main value and id parameter of the Event header.

  • For REFER events, the string refer and the sequence number.

DiameterServiceInfo feature

ImsInformation

org.jainslee.resources.diameter .ro.types.vcb0.ImsInformation

The IMS-Information Diameter AVP

DiameterServiceInfo feature

LatestOcsAnswer

org.jainslee.resources.diameter .ro.types.vcb0.CreditControlAnswer

The latest OCS response message

Sentinel SIP service

PlayedAnnouncementIDs

int[]

IDs of the played announcements

SipPlayAnnouncement feature, SipMidCallPlayAnnouncement feature

OcsSessionIds

String[]

An array of all the OCS session IDs for the call

Various features

OcsSessionTerminationCause

Integer

The OCS session termination cause

Sentinel SIP service

SentinelSelectionKey

com.opencloud.sentinel .common.SentinelSelectionKey

The selection key (for example, <platform>::::) for selecting configuration data

Various features

SessionEnded

long

The date and time when the session ended

SessionEstablished

long

The date and time when the session was established

SessionInitiated

long

The date and time when the session was initiated

Sentinel SIP service

SipServiceType

Enumerated

The type of service Sentinel is processing. One of Message, Subscription, SipCall, or Unknown.

AcceptSip feature

Subscriber

String

The subscriber associated with the session

SipSubscriberDetermination feature

Statistics

Name Description

CDRWritten

Number of times a CDR was successfully written

CDRnotWritten

Number of times a CDR was not successfuly written

Functionality

This features uses the information from the session state fields mentioned above and constructs a protobuf message out of it for output. See AVP CDR Format for the format of these messages.

Also see Charging Information for general information about the contents of CDRs and CCRs.

Note This feature only supports writing binary CDRs. If the cdr-ra is configured to write text CDRs the feature will fail to execute.

Feature responses

Response Reason

featureHasFinished

feature has finished

B2BUA ECUR Features

The B2BUA ECUR charging features define event charging with unit reservation behaviour for Sentinel SIP as a B2BUA.

Details

Feature script name

B2BUAEcurpre-feature, B2BUAEcurpost-feature

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite features

B2BUA

Feature execution points
Pre

SipAccess_ChargingReauth SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_OCSFailurePostCC SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReachedPostCC SipMidSession_OCSFailurePostCC SipMidSession_ChargingReauth SubscriptionSubscriberCheck SubscriptionSipRequest SubscriptionSipResponse CreditFinalised SipTransaction_Response SipTransaction_SubscriberCheck

Post

SipAccess_ChargingReauth SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_OCSFailurePostCC SipAccess_PartyResponse SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReachedPostCC SipMidSession_OCSFailurePostCC SipMidSession_ChargingReauth SubscriptionSubscriberCheck SubscriptionSipRequest SubscriptionSipResponse SipLegEnd SipTransaction_Response SipTransaction_SubscriberCheck

Pre- and post-features

The B2BUA ECUR pre- and post-features cover event charging using a reserve/confirm model. The features are responsible for:

  • creating the reservation charging instance (B2BUAChargingFeatureUtil.DEFAULT_ECUR_CHARGING_INSTANCE) and default session counter on an initial SUBSCRIBE, MESSAGE, OPTIONS, or PUBLISH request

  • performing the initial credit check

  • detection of message delivery or nondelivery conditions and credit finalisation.

The general use case is that a message will be B2BUA’d through Sentinel. The ECUR pre-feature will request a credit check, then allow delivery of the message. When a response to the B2BUA’d message is received, the credit reservation will be confirmed (or refunded).

Note

  • During any credit check, Sentinel automatically ensures all incoming messages are queued in the SLEE until the CCA (or a timeout) is received; in other words, no further network events will be delivered to Sentinel and processed until the credit check is complete.

  • Currently, Sentinel for SIP only supports one charging instance per Sentinel session, though this instance may have multiple session counters.
Tip

Session state inputs and outputs

Inputs

Name Format Description Behaviour if null/invalid

SentinelSelectionKey
com.opencloud.sentinel.common.SentinelSelectionKey

Selection key
(for example, <platform_operator>::::)

For selecting mappers

Increment InputParameterErrors Common cleanup actions

CurrentSipFeatureExecutionPoint
com.opencloud.sentinel.feature.spi.SipFeatureScriptExecutionPoint

Enum value

Used to classify the triggering event

N/A

B2BUAChargingCounterAddress
com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress

Key/value pairs identifying the session charged service

Determines which counter the feature will update with charging data (the ECUR features only treat one counter as the session charging counter at a time). Also see Outputs.

No-op unless initial request

LatestOcsAnswer
org.jainslee.resources.diameter.ro.types.vcb0.CreditControlAnswer

Last received CCA

Passed through to a charging mapper to generate the session counter values

Exception thrown, if the feature is expecting a response from the OCS. Otherwise ignored.

RequestUnitsServiceSpecific
java.lang.Long

Non-negative long

The number of pending requested units, or the number of reported used units, depending on state.

N/A

Outputs

Name Format Description

B2BUAChargingCounterAddress
com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress

Key/value pairs identifying the session charged service

Mapped from initial incoming chargeable event request in SIP-initiated sessions to determine the default session counter against which the units will be charged.

Charging API interactions

The charging API interactions fall under the following categories:

  • charging instructions issued on the B2BUAChargingFeatureUtil.DEFAULT_ECUR_CHARGING_INSTANCE itself

  • updates made to all counters on the charging instance, mainly limited to updates from CCAs and credit finalisation

  • complete implementation of event based charging on the default counter.

Interaction with the default charging instance

Interaction with the default charging instance includes bxref#:initialisation[initialisation], bxref#initial-and-update-credit-checks[checks for initialisation and updates], and bxref#:finalisation[finalisation].

Initialisation

When the pre-feature is first triggered on an incoming event request, it creates the default ECUR charging instance, under the name B2BUAChargingFeatureUtil.B2BUA_ECUR_CHARGING_INSTANCE. It then maps the initial request to a session counter address written to the session state field B2BUAChargingCounterAddress. This is the default session counter on which all ECUR based charging is performed.

Initial and update credit checks

On any trigger other than an incoming chargeable event request, both features check whether the B2BUAChargingFeatureUtil.DEFAULT_ECUR_CHARGING_INSTANCE has been initialised. The first step is to check the instance exists in the ChargingManager, then that the instance has a session counter with the address specified in session state B2BUAChargingCounterAddress. If either check fails, the feature ends immediately on the assumption that ECUR is not enabled.

The pre-feature will issue a credit reservation for an incoming chargeable event request. The called party leg is suspended until the OCS authorises the call.

Finalisation

Any feature can issue credit finalisation, however if the post-feature detects zero remaining legs or it receives an AbortSessionRequest, it issues credit finalisation itself.

Interaction with all session counters

When a CCA is received, all counters on the ChargingInstance will be processed according to the algorithm outlined in Counter Update Algorithm Pseudo Code.

If a credit finalisation is raised, the post-feature will clear the pending requested units on all session counters.

When charging using a non-default counter, another feature will need to set reported used and pending requested units on the counters as needed.

Interaction with the default session counter

The default ECUR session counter is fully managed by the ECUR pre- and post-features. Generally speaking, user features need not interact directly with this counter.

Setting pending requested units on the default counter

When the pre-feature is triggered on a chargable event, the pending requested units will be set to the value of RequestUnitsServiceSpecific in session state.

Setting reported used units on the default counter

When the pre-feature is triggered on the response to a chargable event, the reported used units will be set to the value of RequestUnitsServiceSpecific in session state.

Mappers

This feature uses two mappers:

  • The first converts the initial SIP request to SessionCounterAddress.
    The default implementation is SipRequestToSessionCounterAddress:

    // a mapper that takes a {{SipRequest}} and generates a {{SessionCounterAddress}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
        getSessionState().getSentinelSelectionKey(),
        SipRequest.class,
        SessionCounterAddress.class,
        mappingPoint);

  • The second mapper converts a CCA into a list of session counters.
    The default implementation is CCAtoSessionCounterList:

    // a mapper that takes a {{CreditControlAnswer}} and generates a {{List<SessionCounter>}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
        getSessionState().getSentinelSelectionKey(),
        CreditControlAnswer.class,
        List.class
        mappingPoint);

Feature responses

Response Reason

featureHasFinished

feature has finished

B2BUA Feature

The B2BUA feature provides back-to-back user agent functionality to Sentinel.

Details

Feature script name

B2BUA

Applicable contexts

SIP service

Call-Type

All

Feature execution points

SipAccess_SessionAccept SipAccess_PartyRequest SipAccess_PartyResponse SipMidSession_PartyRequest SipMidSession_PartyResponse SubscriptionAccept SubscriptionSipRequest SubscriptionSipResponse SipTransaction_Accept SipTransaction_Request SipTransaction_Response

SAS Support

Yes

Prerequisite features

None

Network Operator Config

Yes

Subscriber Config

None

POJO or SBB

POJO

Feature FSMs

None

Feature Parameters

None

RA Entity Links

None

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

N/A

Network Operator Data

B2BUA feature configuration is stored on a profile table called SipB2BUAConfigProfileTable.

Data is scoped according to a Sentinel selection key.

Attribute Name Type Default Description 
PreserveCallIdOverB2BUA

boolean

false

If true, the outgoing dialog will use the same SIP Call-ID as the incoming dialog.

 
SendEarlyInitialInviteACK

boolean

false

If true, on receiving a 2xx Response to an Initial INVITE request, an ACK will be sent on the dialog, and the incoming ACK will not be sent on the linked leg.

Statistics

B2BUA feature statistics are tracked by the sentinel.sip SBB and can be found under the following parameter set:
SLEE-Usage → sentinel.sip service ID → sentinel.sip SBB ID → feature.B2BUA

Statistic Type Description 
Started

Counter

Incremented when the feature is invoked.

 
FailedToStart

Counter

Incremented when Sentinel encounters an error while attempting to start the feature.

 
IssuedWarning

Counter

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

 
FailedDuringExecution

Counter

Incremented when a fatal problem is encountered and the feature cannot execute correctly.

 
TimedOut

Counter

Incremented when the feature takes too long to complete and Sentinel aborts execution.

 
FailedToCreateOutgoingLeg

Counter

Incremented when an error occurs while attempting to create a new SIP leg.

 
FailedToCreateOutgoingMessage

Counter

Incremented when an error occurs while attempting to create a new SIP message.

 
FailedToForwardMessage

Counter

Incremented when the feature fails to forward a message for any reason.

 
FailedToLinkLegs

Counter

Incremented when the feature fails to link the triggering leg to a newly created B2BUA leg.

 
FailedToSendNewErrorResponse

Counter

Incremented when an error occurs while the feature is attempting to directly respond to an inbound request with an error response.

 
LegAlreadyLinkedOnInitialRequest

Counter

Incremented when the feature detects that the leg an inbound initial request was received on already has a linked leg.

 
SessionEndingOnInitialRequest

Counter

Incremented when the feature detects that the session is already ending while processing an initial request.

 
LegsNotLinkedOnNonInitialMessage

Counter

Incremented when the feature detects that the leg a non-initial request or response was received on is not linked to another leg.

 
ForwardedResponse

Counter

Incremented when a SIP response is successfully forwarded across the B2BUA.

 
ForwardedRequest

Counter

Incremented when a SIP request is successfully forwarded across the B2BUA.

 
SentErrorResponse

Counter

Incremented when the feature directly answers an incoming request with an error response.

 
SentEarlyAck

Counter

Incremented when the feature generates an immediate ACK to an incoming INVITE-2XX response.

 
SuppressedAckAfterEarlyAck

Counter

Incremented when the feature does not forward an inbound ACK due to it having already sent one on the linked leg.

Behaviour

Basic Behaviour

The B2BUA feature divides the communication channel into two legs and mediates all SIP signaling between both ends of the session.

On receipt of an initial SIP request (i.e. a request without a To tag), the feature creates an outgoing leg, links it to the triggering leg, and forwards an equivalent request on the new leg. The forwarded request will have a new call ID unless the feature has been specifically configured to preserve the call ID across the B2BUA. If the initial request is received on a leg that is already linked to another leg, the feature will not create a new leg or attempt to forward the message on the existing leg. If another feature ends the session before the B2BUA feature processes the initial request, a new leg will not be created and the request will not be forwarded.

For all other incoming SIP messages the feature adds an equivalent outgoing SIP message to the linked leg’s message queue. If there in no leg linked to the triggering leg, the feature will not attempt to forward the message.

Note

This feature is a critical system feature, many features rely on the functionality and success of this feature, including the B2BUA SCUR, B2BUA ECUR, B2BUA IEC, and SDP Comparison features.

See Sentinel SIP Feature Execution Points for more about running critical features.

Early ACKs

If configured to do so, on an incoming success response to an initial INVITE, the feature will send an early ACK on the triggering leg, and will subsequently not forward the ACK received on the linked leg. An early ACK will not be sent if SDP negotiation has not been completed (offer & answer).

Error Responses

There are a number of cases where the feature will generate and send an error response for an inbound request instead of forwarding the request:

  • When the feature forwards a request on a linked leg, it will decrement the value of the Max-Forwards header on the outbound request. If the value reaches 0, the feature will generate and send a 483 (Too Many Hops) response.

  • If the feature receives a request and is unable to forward it on the linked leg due a to a SIP transaction already being in progress on that leg, it will send a 491 (Request Pending) response.

  • If an internal error occurs that prevents the request from being forwarded, the feature will send a 500 (Server Internal Error) response.

B2BUA IEC Features

The B2BUA IEC charging features define immediate event charging for Sentinel SIP as a B2BUA.

Description

Feature script name

B2BUAIECPreFeature, B2BUAIECPostFeature

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite features

B2BUA

Feature execution points
Pre

SipAccess_ChargingReauth SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_OCSFailurePostCC SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReachedPostCC SipMidSession_OCSFailurePostCC SipMidSession_ChargingReauth SubscriptionSubscriberCheck SubscriptionSipRequest SubscriptionSipResponse CreditFinalised SipTransaction_Response SipTransaction_SubscriberCheck

Post

SipAccess_ChargingReauth SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_OCSFailurePostCC SipAccess_PartyResponse SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReachedPostCC SipMidSession_OCSFailurePostCC SipMidSession_ChargingReauth SubscriptionSubscriberCheck SubscriptionSipRequest SubscriptionSipResponse SipLegEnd SipTransaction_Response SipTransaction_SubscriberCheck

The B2BUA IEC pre and post features cover event charging using a charge/refund model. The features are responsible for:

  • creating the reservation charging instance (B2BUAChargingFeatureUtil.DEFAULT_IEC_CHARGING_INSTANCE) and default session counter on an initial SUBSCRIBE, MESSAGE, OPTIONS, or PUBLISH request

  • instructing the charging manager to send a direct debit to the OCS

  • detection of message nondelivery conditions and refunding as necessary

The general use case is that a chargeable message — a SUBSCRIBE, MESSAGE, OPTIONS, or PUBLISH — will be B2BUA’d through Sentinel. The IEC post feature will trigger a direct debit, then allow delivery of the message. If a response to the B2BUA’d message is received which indicates non-delivery, the amount debited will be refunded.

For a high level overview of Sentinel charging see Sentinel SIP Charging Architecture

Note

During any credit check, Sentinel automatically ensures all incoming messages are queued in the SLEE until the CCA (or a timeout) is received; in other words, no further network events will be delivered to Sentinel or processed until the credit check is complete.

Currently, Sentinel for SIP only supports one charging instance per Sentinel session, though this instance may have multiple session counters.
Tip All of Sentinel for SIP’s charging features make use of Sentinel’s comprehensive charging API — see Using the SIP Charging Manager

Session state inputs and outputs

Inputs

Name Format Description Behaviour if null/invalid

SentinelSelectionKey
com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform_operator>:::: )

For selecting mappers

Increment InputParameterErrors Common cleanup actions

CurrentSipFeatureExecutionPoint
com.opencloud.sentinel.feature.spi.SipFeatureScriptExecutionPoint

Enum value

Used to classify the triggering event

N/A

B2BUAChargingCounterAddress
com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress

key/value pairs identifying the session charged service

Determines which counter the feature will update with charging data (the IEC features only treat one counter as the session charging counter at a time). Also see Outputs.

No-op unless initial request

LatestOcsAnswer
org.jainslee.resources.diameter.ro.types.vcb0.CreditControlAnswer

Last received CCA

Passed through to a charging mapper to generate the session counter values

Exception thrown, if the feature is expecting a response from the OCS. Otherwise ignored.

RequestUnitsServiceSpecific
java.lang.Long

Non-negative long

The number of pending requested units

N/A

Outputs

Name Format Description

B2BUAChargingCounterAddress
com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress

key/value pairs identifying the session charged service

Mapped from initial incoming chargeable event request in SIP initiated sessions to determine the default session counter against which the units will be charged.

Charging API interactions

The charging API interactions fall under the following categories:

  • charging instructions issued on the B2BUAChargingFeatureUtil.DEFAULT_IEC_CHARGING_INSTANCE itself

  • updates made to all counters on the charging instance, mainly limited to updates from CCAs.

  • complete implementation of event based charging on the default counter.

Interaction with the default charging instance

Initialisation

When the pre-feature is first triggered on an incoming event request, it creates the default IEC charging instance, under the name B2BUAChargingFeatureUtil.B2BUA_IEC_CHARGING_INSTANCE. It then maps the initial event request to a session counter address written to the session state field B2BUAChargingCounterAddress. This is the default session counter on which all IEC based charging is performed.

Initial debit

On any trigger other than an incoming chargeable event request, both features check whether the B2BUAChargingFeatureUtil.DEFAULT_IEC_CHARGING_INSTANCE has been initialised. The first step is to check the instance exists in the ChargingManager, then that the instance has a session counter with the address specified in session state B2BUAChargingCounterAddress. If either check fails, the feature ends immediately on the assumption that IEC is not enabled.

The pre feature will instruct the charging instance to send a direct debit message to the OCS.

The post feature will set the pending requested units and suspend the called party leg until the OCS authorises the call.

Refund

If the feature is triggered on a non-success response to a chargeable event, the pre feature will instruct the charging instance to refund the amount that was initially debited.

Interaction with all session counters

When a CCA is received, all counters on the ChargingInstance will be processed according to the algorithm outlined in Counter Update Algorithm Pseudo Code. The pre feature will clear the pending requested units on all session counters.

When charging using a non-default counter, another feature will need to set reported used and pending requested units on the counters as needed.

Interaction with the default session counter

The default IEC session counter is fully managed by the IEC pre and post features. Generally speaking, user features need not interact directly with this counter.

Setting pending requested units on the default counter

When the post feature is triggered on a chargable event, the pending requested units will be set to the value of RequestUnitsServiceSpecific in session state, unless they have already been set to a non-zero value. If the pending requested units value is non-zero, it will not be overwritten.

Mappers

This feature uses two mappers:

  • The first converts the initial SIP request to a SessionCounterAddress.
    The default implementation is SipRequestToSessionCounterAddress:

    // a mapper that takes a {{SipRequest}} and generates a {{SessionCounterAddress}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
        getSessionState().getSentinelSelectionKey(),
        SipRequest.class,
        SessionCounterAddress.class,
        mappingPoint);

  • The second mapper converts a CCA into a list of session counters.
    The default implementation is CCAtoSessionCounterList:

    // a mapper that takes a {{CreditControlAnswer}} and generates a {{List<SessionCounter>}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
        getSessionState().getSentinelSelectionKey(),
        CreditControlAnswer.class,
        List.class
        mappingPoint);

Feature responses

Response Reason

featureHasFinished

feature has finished

B2BUA SCUR Features

The SIP B2BUA SCUR Pre and Post features define default session charging behaviour for Sentinel SIP as a B2BUA.

Overview

At a high level, the supported behaviour covers time-based session charging:

  • creating the reservation charging instance (B2BUAChargingFeatureUtil.DEFAULT_SCUR_CHARGING_INSTANCE) and default session counter on an initial request

  • initial credit check

  • recurring credit re-authorisation and used unit reporting at regular intervals

  • responding to ReAuthRequests from an OCS or the Sentinel Diameter Mediation layer

  • detection of session end conditions and credit finalisation.

The SCUR features can also be used in conjunction with other reservation charging features such as SDP Comparison and MMTel Adhoc Conference. The SCUR features automatically handle accounting by updating session counters and the charging timer. The charging timer is armed redundantly if the session is replicated.

User features wishing to enhance Sentinel’s SCUR behaviour might be concerned with:

  • requesting a credit reservation (for example, on a material SDP change)

  • inspecting and reacting to specific CCA result codes

  • temporarily suspending the sending of outgoing SIP messages scheduled on one or more legs during a credit check (already done for called party leg on initial credit check)

  • creating purpose-specific session counters (see the section on Charging API interactions)

  • temporarily suspending charging, for example during an announcement,

Note

During any credit check, Sentinel automatically ensures all incoming messages are queued in the SLEE until the CCA (or a timeout) is received; that is, no further network events will be delivered to Sentinel and processed until the credit check is complete.

Currently, Sentinel SIP only supports one charging instance per Sentinel session, though this instance may have multiple session counters.

All Sentinel SIP’s charging features make use of the Sentinel SIP Charging Architecture.

Details

Feature script name

B2BUAScurPreFeature and B2BUAScurPostFeature

Applicable contexts

SIP service (INVITE dialog)

SAS Support

Yes

Requisite features

B2BUA

Feature execution points
Pre

SipAccess_SubscriberCheck SipAccess_PartyRequest [SipAccess/SipMidSession]_CreditAllocatedPostCC [SipAccess/SipMidSession]_CreditLimitReachedPostCC [SipAccess/SipMidSession]_OcsFailurePostCC [SipAccess/SipMidSession]_ControlNotRequiredPostCC CreditFinalised SipAccess_ServiceTimer SipMidSession_ChargingReauth SipAccess_ChargingReauth

Post

[SipAccess/SipMidSession/SipThirdPartyAccess]_SubscriberCheck [SipAccess/SipMidSession]_PartyRequest [SipAccess/SipMidSession]_PartyResponse [SipAccess/SipMidSession]_CreditAllocatedPostCC [SipAccess/SipMidSession]_CreditLimitReachedPostCC [SipAccess/SipMidSession]_OcsFailurePostCC [SipAccess/SipMidSession]_ControlNotRequiredPostCC CreditFinalised SipAccess_ServiceTimer SipMidSession_ChargingReauth [SipAccess/SipMidSession]_ChargingReauth [SipAccess/SipMidSession]_ChargingAbort SubscriptionSipRequest SubscriptionSipResponse SipTransaction_Request SipTransaction_Response

Timer usage

Execution-point targeted timer will trigger the feature at the SipAccess_ServiceTimer execution point on expiry.

Session state inputs and outputs

Inputs

Name Format Description Behaviour if null/invalid

SentinelSelectionKey com.opencloud.sentinel.common.SentinelSelectionKey

selection key
for example, <platform_operator>::::

For selecting mappers

Increment InputParameterErrors Common cleanup actions

CurrentSipFeatureExecutionPoint com.opencloud.sentinel.feature.spi.SipFeatureScriptExecutionPoint

Enum value

Used to classify the triggering event; for example, the initial invite ACK may occur on SipAccess_PartyRequest.

N/A

B2BUAChargingCounterAddress com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress

key/value pairs identifying the session charged service

Determines which counter the feature will update with timing data (the SCUR features only treat one counter as the session charging counter at a time — concurrent time counters would need to be managed in part by other features, while tariff changes would require updating this field with the address of a new counter). Also see Outputs.

No-op unless initial request

LatestOcsAnswer org.jainslee.resources.diameter.ro.types.vcb0.CreditControlAnswer

Last received CCA

When the feature is triggered on an RAR or QUOTA_EXHAUSTION the feature checks if the Final-Units-Indication AVP was present in the last CCA before proceeding with pending credit reservation. If present it instead calls legManager.endSession().

Proceed with reservation

CallEstablished java.lang.Boolean

Alternative to an incoming initial invite ACK

Indicates when to set the session start time and the initial charging timer in third party setup calls.

Assumed false

RequestUnitsSeconds java.lang.Long

Non-negative long

Number of seconds the post feature will request on the default session counter on any credit reservation if not already set.

N/A - defaults to 60

Outputs

Name Format Description

B2BUAChargingCounterAddress com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress

key/value pairs identifying the session charged service

Mapped from initial incoming request in SIP-initiated sessions to determine the default session counter against which time will be charged.

Charging API interactions

The charging API interactions fall under the following categories:

  • charging instructions issued on the B2BUAChargingFeatureUtil.DEFAULT_SCUR_CHARGING_INSTANCE itself

  • updates made to all counters (which may or may not be time-based) on the charging instance, mainly limited to updates from CCAs and credit finalisation

  • complete implementation of time-based charging on the default counter.

Interaction with the default charging instance

Initialisation

When the pre feature is first triggered on an initial incoming request, it creates the default SCUR charging instance, under the name B2BUAChargingFeatureUtil.B2BUA_SCUR_CHARGING_INSTANCE. It then maps the initial request to a session counter address written to the session state field B2BUAChargingCounterAddress. This is the default session counter on which all time-based charging is performed.

In a scenario with no initial incoming request, it is necessary for some user feature, such as the SIP Third Party Charging Feature, to initialize the charging instance and default session counter.

Initial and update credit checks

On any trigger other than an initial incoming request, both features check whether the B2BUAChargingFeatureUtil.DEFAULT_SCUR_CHARGING_INSTANCE has been initialised. The first step is to check the instance exists in the ChargingManager, and then that the instance has a session counter with the address specified in session state B2BUAChargingCounterAddress. If either check fails, the feature ends immediately on the assumption that SCUR is not enabled.

The pre feature will issue a credit reservation:

  • On an initial SIP request

  • On expiry of the charging timer (QUOTA_EXHAUSTED)

  • Or receipt of an RAR

If the Final-Units-Indicator AVP was present in the previous CCA then a credit reservation will not occur, legManager.endSession() is called and a CCR-T is sent.

If a reservation was requested on the charging instance and there are no previous SIP requests on the calling party linked leg (in other words, the called party), the post feature treats it as an initial credit check. Therefore, the called party leg is suspended until the OCS authorises the call.

Finalisation

Any feature can issue credit finalisation; however if the post feature detects zero remaining legs or it receives an AbortSessionRequest, it issues credit finalisation itself.

Interaction with all session counters

When a CCA is received, all counters on the ChargingInstance will be processed according to the algorithm outlined in Counter Update Algorithm Pseudo Code.

If a credit finalisation is raised, the post feature will clear the pending requested units on all session counters.

When charging using a non-default counter, another feature will need to set reported used and pending requested units on the counters as needed.

Interaction with the default session counter

The default SCUR session counter is fully managed by the SCUR pre and post features. Generally speaking, user features need not interact directly with this counter.

Setting end time on the default counter

When the post feature detects credit finalisation is raised, it sets the default counter’s end time to the current system time.

Setting reported units on the default counter

If either charging instruction is raised, the reported used units will be set on the default counter and the SCUR charging timer will be cancelled.

Setting start time on the default counter

On an incoming initial invite ACK, the pre feature records the current time as the start time on the default counter. In a third-party scenario the initial invite ACK is outgoing, so the start time is recorded when the CallEstablished session state field is true and the charging timer ID is null.

Setting pending requested units on the default counter

If a reservation instruction was issued by the user or pre features, and pending requested is 0, it will be set to the value of RequestUnitsSeconds in session state.

Setting reported used units on the default counter

If a finalisation or reservation instruction is issued, the post feature sets reported used units on the default counter. It uses the utility method in B2BUAChargingFeatureUtil.setReportedUsedMillis, which simply deducts the cumulative committed units from the current chargeable time.

Calculating chargeable time from the default counter

Chargeable time is the time since the default counter’s session start time minus any uncharged time (in which the charging instance was suspended).

LegManager outputs

Instruction Parameter Description

suspend

N/A

Suspend the outgoing request leg on an initial credit check if it is not already suspended

resume

N/A

Resume the leg suspended by the post feature on an initial CCA

endSession

SipResponse.SC_PAYMENT_REQUIRED

Called when final units have been consumed

Mappers

This feature uses two mappers:

  • The first converts the initial SIP request to SessionCounterAddress. The default implementation is SipRequestToSessionCounterAddress

    // a mapper that takes a {{SipRequest}} and generates a {{SessionCounterAddress}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
        getSessionState().getSentinelSelectionKey(),
        SipRequest.class,
        SessionCounterAddress.class,
        mappingPoint);

  • The second mapper converts a CCA into a list of session counters. The default implementation is CCAtoSessionCounterList:

    // a mapper that takes a {{CreditControlAnswer}} and generates a {{List<SessionCounter>}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
        getSessionState().getSentinelSelectionKey(),
        CreditControlAnswer.class,
        List.class
        mappingPoint);

Feature responses

Response Reason

featureHasFinished

feature has finished

Determine Cause Code Feature

The Determine Cause Code feature is responsible for determining an appropriate value for the Cause-Code AVP in the IMS-Information AVP used in Diameter charging. It does this by monitoring an ongoing dialog looking for any event that could bring the dialog to an end. It selects an appropriate code based on what kind of dialog ending event it finds.

Details

Feature script name

DetermineCauseCode

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

N/A

Feature execution points

All

Timer usage

N/A

Source Code

This feature’s source code is available in the Sentinel SDK in the sentinel-sip-service-information-modules module pack. It can be viewed by using the create-module command in the SDK with that module pack. This command will prompt you for information needed to create the new modules, once completed the original source for the feature can be found in the new modules.

The module-pack includes the following modules relevant to this feature:

Module Name Description

sentinel-sip-service-information-modules

Group module for all service information features, including the modules listed below.

sentinel-sip-service-information-session-state-library

Contains the session state interface for the feature.

sentinel-sip-determine-cause-code-feature

Contains the feature itself.

Session state inputs and outputs

Inputs

Name Type Purpose

CurrentSipFeatureExecutionPoint

Enum

Used to classify a dialog’s type and status.

EndSessionCause

Integer

Used to detect end-of-dialog triggered by an explicit call to the session ender.

Outputs

Name Type Description

DiameterCauseCode

Integer

The value to be used in the Cause-Code AVP

Feature responses

Response Reason

featureHasFinished

feature has finished

Statistics

This feature does not provide any usage statistics.

Behaviour

The DetermineCauseCode feature detects and classifies conditions that would bring about the end of a dialog. The feature runs at the end of every execution point to allow it detect any end of dialog cause. When it executes, the feature will start by determining the type of dialog based on what SIP Request method was used to initiate the dialog. From there, the feature will look for all possible conditions that could bring the dialog to an end. Finally, if the dialog is determined to be ending, a cause code value will be selected based on what condition triggered it and that value will be set in the DiameterCauseCode session state field.

This table summarises the possible cause code values, details of how they are determined follow on below.

Code Meaning

-3xx

Dialog was terminated with a SIP 3xx response. The actual value of the code will match the response status.

-2xx

Dialog was terminated with a SIP 2xx response. The actual value of the code will match the response status.

-2

Subscription dialog ended normally.

-1

Transaction dialog ended normally.

0

Invite session ended normally.

2

Invite session setup failed.

3

There was an internal error in Sentinel and no other code can be determined.

4xx

Dialog was terminated with a SIP 4xx response. The actual value of the code will match the response status.

5xx

Dialog was terminated with a SIP 5xx response. The actual value of the code will match the response status.

6xx

Dialog was terminated with a SIP 6xx response. The actual value of the code will match the response status.

Dialog Classification

The feature classifies the dialog into one of three categories: subscriptions, transactions, and invite sessions. It does this classification by examining the initial execution point that the feature was triggered on, which corresponds to the method of the SIP request the initiated the SIP dialog, as follows:

Execution Point Type Initial Request Method

SipAccess_SessionAccept

Invite Session

INVITE

SipThirdPartyAccess_SessionAccept

Invite Session

INVITE (Triggered by an HTTP GET)

SubscriptionAccept

Subscription

SUBSCRIBE or REFER

SipTransaction_Accept

Transaction

MESSAGE, PUBLISH, OR OPTIONS

Note that the feature does not support REGISTER dialogs.

End of Dialog Detection

The procedures for detecting an ending dialog depends on the dialog type. The detailed procedures for each dialog type are laid out below. Note that a cause code value of 3 will occur any time an internal error prevents the feature from determining a more accurate code.

Transaction Dialogs

When evaluating a transaction dialog, the feature will proceed through the following checks until one results in a cause code value being found and stored in the DiameterCauseCode session state field. If none of the checks produce a cause code then the dialog is considered to be still in progress and session state will not be modified.

  1. Check if the session ender was explicitly invoked to terminate the dialog. If this is the case, then the cause code will match the SIP response status code that was provided to the session ender.

  2. Check if the calling leg has already been released by the leg manager. If this has happened, one of two things can happen:

    1. If a cause code had previously been determined in an earlier run of the feature, that code will be preserved.

    2. If no cause code has been determined, then -1 (Successful transaction) will be used.

  3. Check for a pending final response queued to be sent on the calling leg, if one is found a code will be selected as follows:

    1. If the response status is 200 OK then a code of -1 (Successful transaction) will be used.

    2. For any other final response, the response status will be used.

Subscription Dialogs

When evaluating a subscription dialog, the feature will proceed through the following checks until one results in a cause code value being found and stored in the DiameterCauseCode session state field. If none of the checks produce a cause code then the dialog is considered to be still in progress and session state will not be modified.

  1. Check if the session ender was explicitly invoked to terminate the dialog. If this is the case, then the cause code will match the SIP response status code that was provided to the session ender.

  2. Check if the calling leg has already been released by the leg manager. If this has happened, one of two things can happen:

    1. If a cause code had previously been determined in an earlier run of the feature, that code will be preserved.

    2. If no cause code has been determined, then -2 (End of subscribe dialog) will be used.

  3. Check if the most recently received SUBSCRIBE request has a Expires header with the value 0. If this is the case, then -2 (End of subscribe dialog) will be used.

  4. Check for a final response the most recent SUBSCRIBE request (regardless of whether it has been sent or is queued) that has a status that is greater than or equal to 300. If one is found then the response status will be used as the cause code.

Invite Sessions

For invite sessions, the feature does an additional classification to determine what state the session is in: setup, mid-session, or ending. This classification is made based on the current execution point, and on whether an ACK for the initial INVITE/200 transaction has been sent or received by Sentinel.

For sessions in the setup phase, the feature will proceed through the following checks until one results in a cause code value being found and stored in the DiameterCauseCode session state field. If none of the checks produce a cause code then the dialog is considered to be still in progress and session state will not be modified.

  1. Check if the session ender was explicitly invoked to terminate the dialog. If this is the case, then the cause code will match the SIP response status code that was provided to the session ender.

  2. Check if the calling leg has already been released by the leg manager. If this has happened, one of two things can happen:

    1. If a cause code had previously been determined in an earlier run of the feature, that code will be preserved.

    2. If no cause code has been determined, then 2 (Unsuccessful session setup) will be used.

  3. Check if a SIP BYE request has been sent or received, or is queued to be sent on the calling party leg. If this is the case, then 2 (Unsuccessful session setup) will be used.

  4. Check for a final response to the initial INVITE request (regardless of whether it has been sent or is queued) that has a status that is greater than or equal to 300. If one is found then the response status will be used as the cause code.

For sessions in the mid-session phase, the DiameterCauseCode session state field will be immediately set to 0 (Normal end of session) as this is guaranteed from this point.

For session in the ending phase will check if a cause code has been determined in an earlier run of the feature. If one has been, nothing will change. If there is no cause code, then 0 (Normal end of session) will be set in the DiameterCauseCode session state field.

Determine Charging Feature

This feature reads charging settings from profile configuration and the incoming request, and sets session state accordingly.

Details

Feature name

DetermineCharging

Applicable contexts

SIP service

SAS Support

N/A

Prerequisite features

None

Session State inputs and outputs

Inputs

Name Type Purpose

SentinelSelectionKey

SentinelSelectionKey

Used to select a configuration profile to load.

CallType

CallType

Used to identify Service-Identifier and Rating-Group AVP values for session.

Outputs

Name Type Purpose

DisableCharging

boolean

Flag indicating whether charging has been disabled for the session.

InterimCdrsEnabled

boolean

Flag controlling whether interim CDRs will be created for the session.

SessionCdrsEnabled

boolean

Flag controlling whether a session CDR will be created at the end of the session.

ContinueCallOnOCSFailure

boolean

Flag controlling whether the session is permitted to continue if there is an OCS failure.

MonitorCallOnly

boolean

Flag controlling whether online charging will be skipped.

ServiceIdentifier

Long

The value of the Service-Identifier AVP to use according to call type and config value.

RatingGroup

Long

The value of the Rating-Group AVP to use according to call type and if configured, otherwise will be null.

RequestUnitsSeconds

Long

The value of the Requested-Service-Unit AVP in Credit Control Requests if configured, otherwise will be null.

DiameterServiceSpecificInfoConfigListConfig

List<DiameterServiceSpecificInfoConfig>

A list of the DiameterServiceSpecificInfoConfig objects or null if not configured.

OCSId

String

The ID of the Diameter OCS server to use.

Configuration

This feature uses profile configuration to determine how each session state field should be set. Configuration is kept in two profile tables: DetermineChargingConfigProfileTable and DiameterServiceSpecificInfoProfileTable

The profile table called DetermineChargingConfigProfileTable is made up of profiles with the following fields. Each profile is scoped by the Sentinel Selection Key.

Name Type Description

DisableCharging

boolean

If true, online charging will be disabled for sessions using this profile.

InterimCdrsEnabled

boolean

If true, interim CDRs will be created while sessions using this profile are in progress.

SessionCdrsEnabled

boolean

If true, session CDRs will be created at the end of sessions using this profile.

ContinueCallOnOCSFailure

boolean

If true, sessions using this profile will be allowed to continue in the event of OCS failure.

ServiceIdForMOC

Long

If set, overrides the default value of the Service-Identifier for AVP ('1') for Mobile Originating calls in Credit Control Requests and CDRs.

ServiceIdForMTC

Long

If set, overrides the default value of the Service-Identifier for AVP ('2') for Mobile Terminating calls in Credit Control Requests and CDRs.

ServiceIdForMFC

Long

If set, overrides the default value of the Service-Identifier for AVP ('3') for Mobile Forwarded calls in Credit Control Requests and CDRs.

ServiceIdForNIC

Long

If set, overrides the default value of the Service-Identifier for AVP ('4') for Network Initiated calls in Credit Control Requests and CDRs.

RatingGroupForMOC

Long

If set, the value of the Rating-Group AVP for Mobile Originating calls in Credit Control Requests and CDRs.

RatingGroupForMTC

Long

If set, the value of the Rating-Group AVP for Mobile Terminating calls in Credit Control Requests and CDRs.

RatingGroupForMFC

Long

If set, the value of the Rating-Group AVP for Mobile Forwarded calls in Credit Control Requests and CDRs.

RatingGroupForNIC

Long

If set, the value of the Rating-Group AVP for Network Initiated calls in Credit Control Requests and CDRs.

RoRequestUnitsSeconds

Long

If set, overrides the default value of the Requested-Service-Unit AVP ('60') in Credit Control Requests.

The profile table called DiameterServiceSpecificInfoProfileTable is made up with the following fields. Each profile is not scoped by the Sentinel Selection Key and therefore will apply to all sessions.

Name Type Description

ServiceSpecificTypeValue

Long

A positive number that identifies the type of data being provided.

ServiceSpecificDataSessionStateFieldName

String

A string containing either a name of the session state field, or a pipe (|) separated list of names of multiple session state fields to map into the Service-Specific-Info AVP value. When multiple fields are specified, the first non-empty field value will be used.

Feature Statistics

DetermineCharging statistics are tracked by the sentinel.sip SBB and can be found under the following parameter set:
SLEE-Usage → sentinel.sip service ID → sentinel.sip SBB ID → feature.DetermineCharging

Name Type Description

Started

Counter

Incremented when the feature is triggered.

FailedToStart

Counter

Incremented when the feature fails to start.

FailedDuringExecution

Counter

Incremented when the feature fails while executing.

IssuedWarning

Counter

Incremented when the feature issues a warning.

TimedOut

Counter

Incremented when the feature times out during execution.

ChargingDisabled

Counter

Incremented when the feature disables charging.

ChargingFunctionAddressSet

Counter

Incremented when the feature retrieves the ECF address from the P-Charging-Function-Addresses header.

ChargingFunctionAddressesHeaderIsInvalid

Counter

Incremented when the feature fails to parse the P-Charging-Function-Addresses header.

Behaviour

This feature determines charging configuration for the session.

It does this from two main sources:

  1. Most configuration is loaded from profile tables.

  2. The OCS server to use is determined from the incoming SIP request.

SIP Request OCS Selection

The feature will attempt to identify the OCS to use from the P-Charging-Function-Addresses header. If the header has an ECF address, it will be used to set the OCSId session state output field.

The OCSId field is used as described here: OCS Destination Configuration.

Profile Data

When triggered this feature will attempt to retrieve a profile from the DetermineChargingConfigProfileTable using the current Sentinel Selection Key. If a profile is found:

  • DisableCharging, InterimCdrsEnabled, SessionCdrsEnabled, ContinueCallOnOCSFailure and RoRequestUnitsSeconds values are mapped directly from their profile fields to their equivalent session output fields.

  • Using the CallType identified by the Determine Call Type Feature, the ServiceIdentifier and RatingGroup session output field values will be set using the corresponding configuration value if set.

If the feature fails to find a DetermineChargingConfigProfileTable profile, their session output fields will not be populated.

The feature will attempt to retrieve profiles from the DiameterServiceSpecificInfoProfileTable. For each profile found, a DiameterServiceSpecificInfoConfig object will be created using the configured ServiceSpecificTypeValue and ServiceSpecificDataSessionStateFieldName values. All DiameterServiceSpecificInfoConfig objects are collected into a list and put into the DiameterServiceSpecificInfoConfigList session output field.

The effect of each field is outlined below.

Charging Enabled/Disabled

The DisableCharging field controls whether online charging should be enabled for the session. When it is set to true the following behaviour is executed:

  • All reservation charging instances in the Charging Manager will be finalised.

  • The MonitorCallOnly session output field will be set to true.

When the MonitorCallOnly session state field is true, feature execution scripts will skip over online charging features.

Interim CDRs

The InterimCdrsEnabled field controls whether interim CDRs will be written for a session. This is done by checking the value of the field in feature executions scripts, and only executing the Interim CDR Feature if it is true.

Session CDRs

The SessionCdrsEnabled field controls whether a session CDR will be written when a session ends. This is done by checking the value of the field in feature executions scripts, and only executing the appropriate AVP CDR feature if it is true.

In Sentinel Express deployments this affects execution of the AVP CDR Feature. In Sentinel VoLTE deployments this affects execution of the VoLTE SIP AVP CDR Feature.

Continue Call On OCS Failure

The ContinueCallOnOCSFailure field determines system behaviour when there is a problem communicating with the OCS. When it is set to true the call will be allowed to continue in the event of an OCS failure, however:

  • No further online charging will occur for the session, even if communication with the OCS is re-established.

  • Rf and CDRs will continue to track the session.

  • OCS failure for a conference call will still result in the session ending (except for mid-session failures).

Service-Identifier AVP and Rating-Group AVPs

If set, the ServiceIdentifier and RatingGroup fields will be used for populating Credit Control Requests and CDRs. If not set, Sentinel will apply the default Service-Identifier value according to session’s callType and will not populate the Rating-Group AVP in Credit Control Requests and CDRs.

Ro Request Units Seconds

The RoRequestUnitsSeconds field contains the value passed in the Requested-Service-Unit AVP (60) in Credit Control Requests. If the OCS returns a value for the Granted-Service-Units AVP (in a Credit Control Answer) greater than '60', this field can be used to ensure that subsequent Credit Control Requests for the call are not sent unexpectedly early.

DiameterServiceSpecificInfoConfigList

The DiameterServiceSpecificInfoConfigList is used by the mapper responsible for generating Diameter Credit Control Requests to populate Service-Specific-Info AVPs in the requests.

For each DiameterServiceSpecificInfoConfig object in the list, the mapper will retrieve a session state field referenced in the ServiceSpecificDataSessionStateFieldNames. If a value is found in that field, a Service-Specific-Info AVP with the type value specified in the ServiceSpecificTypeValue field, and the found value will be added to the request.

If multiple fields are specified in the ServiceSpecificDataSessionStateFieldNames, the first non-empty field value will be used.

Diameter Per Leg Info Feature

This feature constructs IMS-Information AVPs that record leg-specific information about the call, for use in CDRs and Diameter Ro Credit-Control-Requests.

The feature name is DiameterPerLegInfo, as it is based on 3GPP TS 32.299 v12.11.0 (vcb0).

Description

Feature script name

DiameterPerLegInfo

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

DetermineCauseCode, DetermineCallType, StoreHeaderInfo, RecordTimestamps

Feature execution points

All

Session state inputs and outputs

Inputs

Name Type Purpose

PerLegInitialRequestTimeMillis

Map<String, Long>

Holds the time when the initial INVITE request was seen on each leg. Used for the SIP-Request-Timestamp AVP in the Time-Stamps AVP. Set by the RecordTimestamps feature.

PerLegFinalResponseTimeMillis

long

Holds the time when the initial INVITE final response arrived on each leg. Used for the SIP-Response-Timestamp AVP in the Time-Stamps AVP. Set by the RecordTimestamps feature.

ChargingIdentifier

String

Used for the 3GPP-Charging-Id or Access-Network-Charging-Identifier-Value AVPs. Set by the StoreHeaderInfo feature.

Outputs

Name Type Description

ImsInformation

org.jainslee.resources.diameter.ro.types.vcb0.ImsInformation

The IMS-Information AVP that will be written to a CDR, or sent in a Credit-Control-Request. This AVP is defined in 3GPP TS 32.299 v12.11.0 §7.2.77.

PerLegEventType

Map<String, org.jainslee.resources.diameter.ro.types.vcb0.EventType>

The table of leg names mapped to their corresponding Event-Type AVP data

PerLegEarlyMediaDescription

Map<String, org.jainslee.resources.diameter.ro.types.vcb0.EarlyMediaDescription>

The table of leg names mapped to their corresponding Early-Media-Description AVP data

PerLegSdpMediaComponents

Map<String, org.jainslee.resources.diameter.ro.types.vcb0.SdpMediaComponent>

The table of leg names mapped to their corresponding SDP-Media-Component AVP data

PerLegTimeStamps

Map<String, org.jainslee.resources.diameter.ro.types.vcb0.TimeStamps>

The table of leg names mapped to their corresponding Time-Stamps AVP data

PerLegCallingPartyAddress

MultiMap<String, String>

The table of leg names mapped to their corresponding Calling-Party-Address AVP data, of which there may be several per leg

PerLegCalledPartyAddress

MultiMap<String, String>

The table of leg names mapped to their corresponding Called-Party-Address AVP data, of which there may be several per leg

PerLegRequestedPartyAddress

Map<String, String>

The table of leg names mapped to their corresponding Requested-Party-Address AVP data

PerLegInitialCallingPartyRequestURIString

Map<String, String>

The table of leg names mapped to IntialCallingPartyRequestURI - used for the Requested-Party-Address AVP. Obtained from the incoming Request-URI.

Behaviour

The DiameterPerLegInfo feature populates the Diameter Ro IMS-Information AVPs with information about the call which is specific to each leg. Information about the call as a whole is populated by the Diameter Service Info feature. The information is gathered on a per-leg basis where it is specific to a given SIP leg. Such values are recorded into session state maps keyed by leg name. The feature needs to be run in two separate modes at different phases of each execution point. The inbound mode should be invoked in the SIP system pre scripts to process the incoming trigger leg, while the outbound mode should be invoked in the post scripts to monitor outgoing messages on all SIP legs. The feature stores the IMS-Information AVPs in session state, and updates it at various feature execution points when other features have run. The resulting AVPs are used by the AVP CDR Feature feature when writing a CDR. The AVPs are also sent in Credit-Control-Requests to the OCS.

Diameter Service Info Feature

This feature constructs IMS-Information AVPs that record information about the call, for use in CDRs and Diameter Ro Credit-Control-Requests.

The feature name is DiameterServiceInfo, as it is based on 3GPP TS 32.299 v12.11.0 (vcb0).

Description

Feature script name

DiameterServiceInfo

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

DetermineCauseCode, DetermineCallType, StoreHeaderInfo, RecordTimestamps

Feature execution points

All

Session state inputs and outputs

Inputs

Name Type Purpose

OriginatingInterOperatorIdentifier

String

Used for the Originating-IOI AVP in the Inter-Operator-Identifier AVP. Set by the StoreHeaderInfo feature.

TerminatingInterOperatorIdentifier

String

Used for the Terminating-IOI AVP in the Inter-Operator-Identifier AVP. Set by the StoreHeaderInfo feature.

IMEI

String

Used as the User-Equipment-Info-Value AVP in the User-Equipment-Info Grouped AVP. Set by the StoreHeaderInfo feature.

UserSessionId

String

The session’s Call-ID, used for the User-Session-Id AVP. Set by the StoreHeaderInfo feature.

IMSChargingId

String

The icid-value parameter of the SIP "P-Charging-Vector" header, used as the IMS-Charging-Identifier AVP. Set by the StoreHeaderInfo feature.

CallType

Enum

Used to set the Subscriber-Role AVP. Set by the DetermineCallType feature.

AccessNetworkInfo

String

Used for the Access-Network-Information AVP. Set by the StoreHeaderInfo feature.

DiscoveredAccessNetworkInformation

String

Used for the Access-Network-Information AVP if the AccessNetworkInfo isn’t set. Set by application level features.

DiameterCauseCode

int

Used for the Cause-Code AVP, indicating how the session ended. Set by the DetermineCauseCode feature.

ChargingIdentifier

String

Used for the 3GPP-Charging-Id or Access-Network-Charging-Identifier-Value AVPs. Set by the StoreHeaderInfo feature.

Outputs

Name Type Description

ImsInformation

org.jainslee.resources. diameter.ro.types.vcb0.ImsInformation

The IMS-Information AVP that will be written to a CDR, or sent in a Credit-Control-Request. This AVP is defined in 3GPP TS 32.299 v12.11.0 §7.2.77.

CallId

String

The SIP Call-ID of the current session.

EventId

String

The subscribed event ID, if present.

SsiSrcMccmnc

String

Contains a concatenation of the mcc and mnc obtained from PvniMccMnc or failing that, from PaniMccsMncs

This value may be used as the value of a Service-Specific-Info AVP.

SsiSrcImpiUserPart

String

Contains the user part of the IMPI which is the IMSI when the IMPI is derived from the IMSI.

This value may be used as the value of a Service-Specific-Info AVP.

SsiSrcCellId

String

Contains the cellID(s) derived as a semicolon separated list of the network ID values defined in the first available headers of Cellular-Network-Info, P-Cellular-Network-Info or P-Access-Network-Info for Mobile Originating calls or the OC-Term-P-Access-Network-Info header for Mobile Terminating calls, and failing that from the most recent unexpired registration record’s PAccessNetworkInfo.

This value may be used as the value of a Service-Specific-Info AVP.

SsiSrcCalledPartyNumber

String

Contains the called party number derived from the digits in the user part of the URI in the calledPartyAddress session state field, with a + prepended if normalization is set to international and the number of digits is >= MinNormalizableLength, or if the calledPartyAddress was a tel: uri where the digits had a leading +.

This value may be used as the value of a Service-Specific-Info AVP.

SsiSrcCallingPartyNumber

String

Contains the calling party number derived from the digits in the user part of the URI in the callingPartyAddress session state field, with a + prepended if normalization is set to international and the number of digits is >= MinNormalizableLength, or if the callingPartyAddress was a tel: uri where the digits had a leading +.

This value may be used as the value of a Service-Specific-Info AVP.

Behaviour

The DiameterServiceInfo feature populates the Diameter Ro IMS-Information AVPs with information about the call as a whole. Information specific to individual legs is stored by the Diameter Per Leg Info feature. The feature stores the IMS-Information AVPs in session state, and updates it at various feature execution points when other features have run. The resulting AVPs are used by the AVP CDR Feature feature when writing a CDR. The AVPs are also sent in Credit-Control-Requests to the OCS.

The SsiSrc (Service-Specific-Info source) prefixed session state fields are set where possible, as described.

Extract Network Info Feature

This feature parses P-Visited-Network-Identifier (PVNI) and P-Access-Network-Info (PANI) headers to extract the Mobile Country Code (MCC) and Mobile Network Code (MNC) values for the subscriber into session state fields.

This feature parses PVNI and PANI headers in the initial SIP request or Registration Records to extract MCC and MNC values to store in session state. The following features rely on the MCC and MNC data stored by this feature for use in Credit Control Requests (CCR), Call Detail Records (CDR) and Accounting Requests (ACR):

Description

Feature Script Name

ExtractNetworkInfo

Call-Type

Orig or Term

Prerequisite features

N/A

Session Plan

all

Execution points

For Sentinel Express: Post_SipAccess_SubscriberCheck, Post_SubscriptionSubscriberCheck, Post_SipTransaction_SubscriberCheck, Post_SipThirdPartyAccess_SubscriberCheck. For Sentinel VoLTE: Post_SipAccess_SessionCheck, Post_SubscriptionSessionCheck, Post_SipTransaction_SessionCheck.

Network Operator Config

Yes

Subscriber Config

No

POJO or SBB

POJO

Feature FSMs

None

Feature Parameters

None

SAS Support

Yes

RA Entity Links

None

Prerequisite features

Session State Inputs and Outputs

Inputs

Name Type Purpose

PvniMccMnc

com.opencloud.sentinel.common.MccMnc

If set, the feature will not attempt to do PVNI header analysis. See Outputs below.

PaniMccsMncs

List<com.opencloud.sentinel.common.MccMnc>

If set, the feature will not attempt to do PANI header analysis again. See Outputs below.

IsoCountryCode

String

If set, the feature will not update the IsoCountryCode. See Outputs below.

RegistrationRecords

RegistrationRecord

PANI and PVNI headers from registration records are used if the initial SIP request did not contain the corresponding header with MCC and MNC data. The MCC and MNC are parsed from the header and stored in the PvniMccMnc session state field. The RegistrationRecord field is normally set by IMSIDLookup in VoLTE.

Outputs

Name Type Description

PvniMccMnc

com.opencloud.sentinel.common.MccMnc

The MCC and MNC data that was retrieved from a PVNI header found either on the request itself or in registration records.

PaniMccsMncs

List<com.opencloud.sentinel.common.MccMnc>

A list of MCC and MNC data retrieved from the PANI headers found either on the request itself or in registration records.

IsoCountryCode

String

The ISO Country Code found from the PANI headers found either on the request itself or in registration records.

Behaviour

MCC and MNC

The ExtractNetworkInfo feature parses P-Access-Network-Info (PANI) and P-Visited-Network-Identifier (PVNI) headers found in the SIP trigger or Registration Records to determine the Mobile Country Code (MCC) and Mobile Network Code (MNC) for the subscriber. The following OpenCloud extension AVPs are used to communicate MCC and MNC information in CDRs and CCRs:

  • OC-ACCESS-NETWORK-MCC-MNC

  • OC-VISITED-NETWORK-MCC-MNC

  • OC-IMSI-NETWORK-MCC-MNC

Priority is given to any headers present in the SIP trigger, if they are able to be parsed. In Mobile Terminating cases OC-Term-P-Access-Network and OC-Term-P-Visited-Network headers added by SCC during reorigination are used if present. For any given header type, if it is missing or invalid in the SIP trigger, the feature will then check registration records. When an MNC cannot be determined, but the MCC was able to be extracted, a value of "000" will be used in place of the missing MNC.

For information on Sentinel AVP definitions, please refer to Sentinel AVPs in the Sentinel Administration guide.

ISO Country Code

The ExtractNetworkInfo feature parses P-Access-Network-Info (PANI) and P-Visited-Network-Identifier (PVNI) headers found in the SIP trigger or Registration Records to determine the ISO Country Code for the subscriber and populates the IsoCountryCode session state field. The section below explains precedence:

Originating

  • Look for a country parameter in the trigger’s P-Access-Network-Info headers

  • Look for an MCC in the trigger’s P-Access-Network-Info headers and find the ISOCountryCode for that MCC in the corresponding MobileCountryCodeInformation profile

  • Look for an MCC in the Cellular-Network-Info headers and find the ISOCountryCode for that MCC in the corresponding MobileCountryCodeInformation profile

  • Look for an MCC in the P-Cellular-Network-Info headers and find the ISOCountryCode for that MCC in the corresponding MobileCountryCodeInformation profile

  • Look for a country parameter in the registration data P-Access-Network-Info headers

  • Look for an MCC in the registration P-Access-Network-Info headers and find the ISOCountryCode for the corresponding MobileCountryCodeInformation profile

Terminating

  • Look for a country parameter in the registration data P-Access-Network-Info headers

If a country parameter is not found in stored P-Access-Network-Info headers:

  • Look at available MCC information from the registration P-Visited-Network-Info header to determine if the subscriber is roaming

  • Look at available MCC information from the registration P-Access-Network-Info headers to determine if the subscriber is roaming and determine the subscribers Access-Network type (WLAN, EUTRAN, or NR)

Store the ISOCountryCode associated with the first available MCC found in the subscriber’s P-Access-Network-Info headers

Statistics

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

Name Type Description 
Started

Counter

Incremented when the feature is triggered.

 
FailedToStart

Counter

Incremented when the feature fails to start.

 
FailedDuringExecution

Counter

Incremented when the feature fails while executing.

 
IssuedWarning

Counter

Incremented when the feature issues a warning.

 
TimedOut

Counter

Incremented when the feature times out during execution.

 
AccessNetworkMccMncFoundInTrigger

Counter

Incremented when access network MCCs and MNCs are found in the triggering message.

 
AccessNetworkMccMncFoundInRegistrationData

Counter

Incremented when access network MCCs and MNCs are found in registration data.

 
CellularNetworkMccMncFoundInTrigger

Counter

Incremented when access network MCCs and MNCs are determined from a Cellular-Network header on the triggering message.

 
UnableToDetermineAccessNetworkMccMnc

Counter

Incremented when access network MCCs and MNCs cannot be determined.

 
VisitedNetworkMccMncFoundInRegistrationData

Counter

Incremented when the visited network MCC and MNC are found in registration data.

 
VisitedNetworkMccMncFoundInTrigger

Counter

Incremented when the visited network MCC and MNC are found in trigger.

 
UnableToDetermineVisitedNetworkMccMnc

Counter

Incremented when the visited network MCC and MNC cannot be determined.

 
IsoCountryCodeFoundFromHeader

Counter

Incremented when an ISO country code is extracted directly from an access network info header.

 
IsoCountryCodeFoundFromMccMnc

Counter

Incremented when an ISO country code is determined from an MCC and MNC value.

 
IsoCountryCodeFoundFromHomeNetworkConfig

Counter

Incremented when an ISO country code is determined from home network configuration in Sentinel.

 
UnableToDetermineAccessNetworkIsoCountryCode

Counter

Incremented when an ISO country code cannot be determined.

Configuration

When parsing MNC’s from digit strings (such as an IMSI), the MobileCountryCodeInformation profile table is used to determine whether the MNC is two or three digits. The table maps an MCC to a list of that country’s MNC’s which are then compared against the digit string to determine length. At present, other fields are for administrative use only.

Parameter Type Description

MCC

String

The three digit Mobile Country Code each profile represents.

MNCs

String[]

An ordered list of the two or three digit Mobile Network Codes for this MCC.

Country

String

The name of the country the MCC belongs to (for documentation purposes only.)

CountryDialCode

String

A digit string representing the actual dial code for this country.

ISOCountryCode

String[]

An ordered list of two-character strings representing the ISOCountryCode - each entry corresponds to an MNC. Use "UNKNOWN" for missing values.

Brands

String[]

An ordered list of brand names corresponding to each MNC. Use "UNKNOWN" for missing values.

Operators

String[]

An ordered list of operator names corresponding to each MNC. Use "UKNOWN" for missing values.

The ExtractNetworkInfo feature also relies on configuration from the SipSentinelConfigurationTable. The data is scoped by selection key.

Parameter

Type

Description

ISOCode

String

A two-character string representing the ISOCountryCode for the home network

It also relies on the PLMN ID Analyser Component and its configuration to determine if an MCC is a home MCC.

An example MobileCountryCodeInformation profile:

            MCC: "530"
            Country: "New Zealand"
            ISOCountryCode: "nz"
            CountryDialCode: "64"
            MNCs: !array
                type: java.lang.String
                values:
                   - "00"
                   - "01"
            ...
            Brands: !array
                type: java.lang.String
                values:
                   - "Telecom"
                   - "Vodafone"
            ...
            Operators: !array
                type: java.lang.String
                values:
                   - "Telecom New Zealand"
                   - "Vodafone New Zealand"
            ...

The value at at a given index of each of the following array attributes corresponds to the value at the same index of any other:

  • MNC (01)

  • Brands (Vodafone)

  • Operators (Vodafone New Zealand)

Configuration Profile Naming

Table Name Description Profile Naming

MobileCountryCodeInformation

The Mobile Network Codes associated with a given Mobile Country Code.

SentinelSelectionKey with three digit Mobile Country Code suffix (for example, metaswitch::::722.)

The ExtractNetworkInfo feature also relies on configuration from the SipSentinelConfigurationTable. The data is scoped by selection key.

Table Name Description Profile Naming

SipSentinelConfigurationTable

SentinelSelectionKey (for example, metaswitch::::.)

Provisioning Interfaces

The feature is provisioned using the web interface.

Interim CDR Feature

SipInterimCdr is a system feature that is responsible for writing interim Call Detail Records and/or Diameter Accounting Requests (ACRs) throughout the session.

SipInterimCdr runs at various key points throughout a session and if any of its write conditions are met it writes either or both of:

  1. an interim AVP CDR using the cdr-ra

  2. an ACR using the rf-control-ra

Interim AVP CDRs and Diameter Accounting Records (ACRs) have substantially similar content and the same triggering logic hence both are supported by this feature.

The feature maintains a timer for the interim CDR period. This timer may be adjusted according to the Rf accounting interval provided by the CDF. The interim CDR timer is armed redundantly if session replication is enabled.

Tip

By default, Sentinel runs SipInterimCdr as the very last feature in the post phase of almost every Sip or Charging related feature execution script and EndSession. For example:

featurescript OnPostSubscriberCheck {
    if not session.MonitorCallOnly { run B2BUAScurPostFeature }
    run SDPMonitor mode "post"
    run DetermineCauseCode
    run DiameterServiceInfo
    run SipInterimCdr
}

Details

Feature script name

SipInterimCdr

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None, but information from various features is used if available

Session state inputs and outputs

Control flags indicating that an interim CDR should be written

Name Type Description Where set

WriteCdrOnSDPChange

boolean

Indicates that a meaningful SDP change occurred on a monitored leg

SDP Comparison feature

LegForCdrs

String

Name of the leg for which CDRs and/or ACRs should be written

Defaults to callingParty, can be set by another feature during call setup.

Inputs

If any of these fields are unset the feature will skip writing the current CDR and/or ACR.

Name Type Description Where set

CallId

String

The unique ID of the call

DiameterServiceInfo feature

CallType

Enumerated

The type of the call. One of MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, or EmergencyCall

DetermineCallType feature, SipThirdPartyHttpTrigger feature

ChargingResult

int

The result code of the Diameter session

Sentinel SIP service

DiameterServiceContextId

String

The Diameter context ID of the relevant service

AcceptSip feature, SipThirdPartyHttpTrigger feature

EndSessionCause

Integer

The end session cause code

LegManager

EventId

String

  • For SUBSCRIBE and NOTIFY events, the main value and id parameter of the Event header.

  • For REFER events, the string refer and the sequence number.

DiameterServiceInfo feature

ImsInformation

org.jainslee.resources.diameter .ro.types.vcb0.ImsInformation

The IMS-Information Diameter AVP

DiameterServiceInfo feature

LatestOcsAnswer

org.jainslee.resources.diameter .ro.types.vcb0.CreditControlAnswer

The latest OCS response message

Sentinel SIP service

PlayedAnnouncementIDs

int[]

IDs of the played announcements

SipPlayAnnouncement feature, SipMidCallPlayAnnouncement feature

OcsSessionIds

String[]

An array of all the OCS session IDs for the call

Various features

OcsSessionTerminationCause

Integer

The OCS session termination cause

Sentinel SIP service

SentinelSelectionKey

com.opencloud.sentinel .common.SentinelSelectionKey

The selection key (for example, <platform>::::) for selecting configuration data

Various features

SipServiceType

Enumerated

The type of service Sentinel is processing. One of Message, Subscription, SipCall, or Unknown.

AcceptSip feature

Subscriber

String

The subscriber associated with the session

SipSubscriberDetermination feature

Statistics

Name Description

CDRWritten

Number of times a CDR or ACR was successfully written

CDRWriteError

Number of times a CDR or ACR was not successfully written

EventCDRWritten

Number of times an Event CDR or ACR was successfully written

StartCDRWritten

Number of times a Start CDR or ACR was successfully written

InterimCDRWritten

Number of times a Interim CDR or ACR was successfully written

StopCDRWritten

Number of times a Stop CDR or ACR was successfully written

TriggeredOnSDPChange

Number of times the feature was triggered due to SDP change

TriggeredOnInterimCdrTimer

Number of times the 'InterimCdrTimer' fired

NoLegForCdr

Number of times the feature ran with no leg for CDRs configured

RfControlActivityLost

Number of times rfControlActivity was lost from session state so a CDR or ACR was not successfully written

Functionality

This feature can be configured to:

  • write CDRs to the local filesystem (through the cdr-ra), and/or

  • write ACRs using the Diameter Rf protocol (through the rf-control-ra)

This feature uses the information from the session state fields mentioned above and constructs a CDR and/or ACR for output. See AVP CDR Format for the format of the CDRs.

Although the feature runs in many execution points, it inspects various session state fields to decide whether or not to write an interim CDR and/or ACR.

An interim CDR and/or ACR will be written under any of the following conditions:

  • On the initial SIP request on the 'LegForCdrs'

  • On the SipInterimCdr feature timer, if no CDR has been recently written

  • On session end

  • When a feature (e.g. SDP Monitor) sets WriteCdrOnSDPChange to true

When the feature is about to write an INTERIM or STOP ACR for a Sentinel Session, if checks if the current Rhino node has an Rf Control Activity for the Diameter Rf session. If it does not, a new Rf Control Activity is started using the same Rf session identifier. This fails over the Rf session.

Also see Charging Information for general information about the contents of CDRs, ACRs and CCRs.

Note This feature only supports writing binary CDRs. If the cdr-ra is configured to write text CDRs the feature will fail to execute.

Configuration

These parameters configure the feature:

Parameter Type Description

WriteCdrOnSDPChange

boolean

When a meaningful SDP change occurs on a monitored leg, write a CDR

InterimTimerPeriod

long

The maximum duration in seconds between timer driven interim CDRs. Setting this to zero will disable timer based interim CDRs.

UseCdrRa

boolean

Whether interim CDRs should be written to disk using the cdr-ra

UseRfControlRa

boolean

Whether ACRs should be written using the rf-control-ra

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SipInterimCdrProfileTable

SipInterimCdr feature configuration parameters

SentinelSelectionKey (for example, OpenCloud::::)

Feature responses

Response Reason

featureHasFinished

feature has finished

featureFailedToExecute

Cause.invalidSessionState, "rfControlActivity no longer in session state"

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

Max Call Duration Feature

Warning This feature is deprecated as of version 2.8.0.3 of Sentinel SIP. Its functionality is now handled by the Session Refresh Feature.

The Max Call Duration Feature monitors the call duration and terminates the call if the maximum call time has been exceeded.

On an incoming initial ACK or when the callEstablished session state field is true, a timer is set. The timer length is controlled by the MaxTimerInterval and MaxCallDuration parameters in the feature’s configuration. MaxCallDuration can be overridden with a session state value to enable unlimited call duration or a session specific max call duration. A feature should override the MaxCallDuration in the initial call setup phase not during mid-call. On the expiry of the timer, the feature checks the call time against the maximum call duration. If the maximum call time has been exceeded, LegManager.endSession is instructed. If not, then the timer is reset to the minimum of MaxTimerInterval and the remaining MaxCallDuration.

Details

Feature script name

MaxCallDuration

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

N/A

Feature execution points
Pre

SipAccess_SipRequest SipEndSession

Post

SipAccess_SipResponse

Timer usage

Feature-targeted timer triggers feature directly on expiry. Does not need to be registered against SipAccess_ServiceTimer execution point.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key
for example, <platform>::::

For selecting configuration data

Increment InputParameterErrors,
common cleanup actions

CallEstablished

Boolean

true or false

true if the session has been established

Initially set to false.

MaxCallDuration

Long

null or a value greater than or equal to 0

null value feature will use configuration data. 0 value feature will be disabled for unlimited call length. Greater than 0 will set the Maximum call duration (ms)

Initially set to null a value less than 0 will be ignored.

Feature responses

Response Reason

featureHasFinished

feature has finished

Call Duration configuration

Parameter Type Description

MaxTimerInterval

long

Interval of periodic timer (ms)

MaxCallDuration

long

Maximum call duration (ms)

Statistics

Name Description

CallLimitReached

Counter incremented when the call has been ended due to reaching the maximum call duration.

Record Timestamps Feature

The Record Timestamps feature records the times at which Sentinel received a call’s initial request, 180 Ringing (if received), and its associated final response.

Details

Name in feature scripts

RecordTimestamps

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

N/A

Feature execution points

SipAccess_SessionStart, SipAccess_PartyResponse, SipThirdPartyAccess_SessionStart

Timer usage

N/A

Source Code

This feature’s source code is available in the Sentinel SDK in the sentinel-sip-service-information-modules module pack. It can be viewed by using the create-module command in the SDK with that module pack. This command will prompt you for information needed to create the new modules, once completed the original source for the feature can be found in the new modules.

The module-pack includes the following modules relevant to this feature:

Module Name Description

sentinel-sip-service-information-modules

Group module for all service information features, including the modules listed below.

sentinel-sip-service-information-session-state-library

Contains the session state interface for the feature.

sentinel-sip-record-timestamps-feature

Contains the feature itself.

Session state inputs and outputs

Inputs

None

Outputs

Name Type Format Description

PerLegInitialRequestTimeMillis

Map<String,Long>

A table mapping each leg to the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

Time that the initial request was received on each leg

PerLegFinalResponseTimeMillis

Map<String,Long>

A table mapping each leg to the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

Time that the final response to the initial request was received on each leg

InitialRingingResponseTimestamp

Long

Timestamp measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

Time the first 180 Ringing is received for the session (not per leg). If a 180 Ringing is not received the value is not updated.

Feature responses

Response Reason

featureHasFinished

feature has finished

Statistics

Name Description

RequestTimestampSet

Counter incremented when the timestamp for the initial request is set.

ResponseTimestampSet

Counter incremented when the timestamp for the final response is set.

Behaviour

The feature needs to be run in two separate modes at different phases of each execution point. The inbound mode should be invoked in the SIP system pre scripts to process the incoming trigger leg. In inbound mode, it verifies that it was triggered by an initial request, or the final response to such a request. If neither of these conditions is met, the feature will finish execution without modifying any state. In outbound mode, it checks outgoing messages on all SIP legs.

If it detects an initial request, the feature will record the current system time into the PerLegInitialRequestTimeMillis session state field against the corresponding leg name, increment the associated statistic, and then finish execution.

If it detects a 180 Ringing, the feature will record the current system time into the InitialRingingResponseTimestamp session state field.

If it detects a final response, the feature will record the current system time into the FinalResponseTimeMillis session state field and increment the associated statistic.

Remove Headers From Outgoing Messages Feature

The RemoveHeadersFromOutgoingMessages feature performs removal of headers from outgoing messages based on configuration.

Behavior

The RemoveHeadersFromOutgoingMessages works as follows:

  • For any SIP message present on a leg’s SipMessageQueue any header matching an entry in the HeadersToRemoveFromOutgoingMessages configuration will be removed.

  • For any SIP message present on a leg’s SipMessageQueue any Supported header value matching an entry in the SupportedHeaderValuesToToRemoveFromOutgoingMessages configuration will be removed.

Note

In order to capture all outgoing SIP messages this feature should be the last feature to run in all Post System Feature execution points.

If configured this feature will modify the content of any outgoing message with a matching header or Supported header value at the time of execution. Changing the features position within feature scripts may have side affects for subsequent features.

See Sentinel SIP Feature Execution Points for more information.

Details

Feature script name

RemoveHeadersFromOutgoingMessages

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

none

Feature execution points
Pre

none

Post

SipAccess_SubscriberCheck SipAccess_PartyRequest SipAccess_PartyResponse SipAccess_ServiceTimer SipAccess_ChargingReauth SipAccess_ChargingAbort SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReached SipAccess_CreditControlNotRequiredPostCC SipAccess_OCSFailurePostCC SipMidSession_PartyRequest SipMidSession_PartyResponse SipMidSession_ChargingReauth SipMidSession_ChargingAbort SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReached SipMidSession_CreditControlNotRequiredPostCC SipMidSession_OCSFailurePostCC SubscriptionSubscriberCheck SubscriptionSipRequest SubscriptionSipResponse SipTransaction_SubscriberCheck SipTransaction_Request SipTransaction_Response SipLegEnd SipEndSession

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key

for example: <platform>::::

For selecting configuration data

Feature responses

Response Reason

featureHasFinished

Feature has finished.

RemoveHeadersFromOutgoingMessages configuration

The configuration for the RemoveHeadersFromOutgoingMessages feature is provisioned in the following table:

Parameter Type Description

HeadersToRemoveFromOutgoingMesssages

String[]

Each entry of the array represents a header e.g Session-Expires that if present will be removed from outbound messages

SupportedHeaderValuesToRemoveFromOutgoingMesssages

String[]

Each entry of the array represents a value e.g timer or preconditions that if present will be removed from the Supported header of outbound messages
Note HeadersToRemoveFromOutgoingMessages can not be configured with the following values Cseq, Via, Rseq, RAck, From and To.

Statistics

Statistic When incremented

RemovedHeaderFromOutboundMessage

A header matching a configured HeadersToRemoveFromOutgongMessages value was removed.

FailedToRemoveHeaderFromOutboundMessage

A header matching a configured HeadersToRemoveFromOutgongMessages value could not be removed.

RemovedSupportedHeaderValueFromOutboundMessage

A Supported header matching a configured SupportedHeaderValuesToRemoveFromOutgongMessages value was removed.

FailedToModifySupportedHeaderOfOutboundMessage

A failure occurred removing a Supported header matching a configured SupportedHeaderValuesToRemoveFromOutgongMessages value.

Started

The feature is invoked.

FailedToStart

The feature fails to start.

IssuedWarning

The feature encounters a non-fatal error and alerts the core.

FailedDuringExecution

The feature encounters any fatal error and alerts that core.

TimedOut

The feature fails to complete execution within the allowable time frame.

Provisioning interfaces

The feature is provisioned using the web interface.

SDP Comparison Feature

The SDP Comparison feature updates charging information with the OCS when the media streams of a session have changed.

Details

Feature script name

SDPComparison

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

SDP Monitor
B2BUAScurPostFeature

Feature execution points
Pre

SipAccess_OCSFailurePostCC SipMidSession_OCSFailurePostCC

Post

SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_PartyResponse SipAccess_PartyRequest SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReachedPostCC SipMidSession_PartyRequest SipMidSession_PartyResponse

Behaviour

This feature tracks changes in SDPs used to negotiate media streams, and triggers credit re-authorization if material changes have occurred. Materialness is determined by classifying the codec specified in the SDP into 'equivalence classes' (see Configuration).

If the difference between the previous and newly negotiated SDP is material from a rating condition perspective, then the feature will perform a client-initiated credit re-authorization towards the Online Charging System (OCS). The OCS will be notified that the reason is due to rating conditions changing. While the re-authorization is in progress, the outgoing message is suspended. On successful response from the OCS, the outbound message processing is resumed.

If the difference between the previous and newly negotiated SDP is immaterial, then no credit re-authorization will be performed. On session refresh, where the new SDP matches the previously negotiated SDP, no credit re-authorization will be performed.

If a codec is not mapped to an equivalence class, it will trigger a re-authorization when compared to any codec which does belong to a class. Two codecs, neither of which are mapped to a class, are consided equivalent and will not trigger a re-authorization. Another way to think of this is to consider that all codecs not specifically mapped are essentially mapped to their own class.

The following diagram gives some examples:

sdp comparison simple flow

See SDP Comparison for an overview of the process

Session state inputs and outputs

Inputs

None

Outputs

Name Type Format Description

WriteCdrOnSDPChange

boolean

Indicates that a meaningful SDP change occurred on a monitored leg

Written when an SDP change has been accepted by the other party. Used by the Interim CDR feature.

Mappers

This feature uses two mappers:

  • The first is used to map an SDP match model to an SDP match model that has been adapted to contain code equivalence lookups. The default implementation is SdpMatchModelToSdpCcrMatchModelMapper

    // a mapper that takes a {{SDPMatchModel}} and generates a {{SDPMatchModel}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
        getSessionState().getSentinelSelectionKey(),
        matchModel.getClass(),
        SdpMatchModel.class,
        mappingPoint);

  • The second mapper takes a DiffModel representing the total differences of two SDP and filters it to only show those differences relative to charging. The default implementation is SdpDiffToSdpCcrDiffMapper

    // a mapper that takes a {{SDPDiffModel}} and generates a {{SDPDiffModel}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
    getSessionState().getSentinelSelectionKey(),
    arg.getClass(),
    SdpDiffModel.class,
    mappingPoint);

Configuration

The default configuration recognizes three equivalence classes - Audio8KHzSingleChannel, Audio16KHzSingleChannel, and Video90KHzSingleChannel. The codecs mapping to each class are as follows:

Equivalence Class

EncodingName/ClockRate/Channels

Audio8KHzSingleChannel

G726-40/8000/1
GSM-EFR/8000/1
DVI4/8000/1
GSM/8000/1
LPC/8000/1
G726-24/8000/1
G729D/8000/1
G726-32/8000/1
G726-16/8000/1
PCMA/8000/1
PCMU/8000/1
G729E/8000/1
G723/8000/1
G722/8000/1

Audio16KHzSingleChannel

DVI4/16000/1

Video90KHzSingleChannel

MPV/90000/1
JPEG/90000/1
H263-1998/90000/1
H263/90000/1
MP2T/90000/1
CelB/90000/1
H261/90000/1

See SDP Comparison for Rating Condition Change Determination for details of configuring the SDP comparison.

SDP Monitor Feature

The SDP Monitor system feature keeps track of all Session Description Protocol (SDP) offers and answers on a leg.

It works like this:

  1. When an SDP offer is received, the feature updates the leg’s latestReceivedSDP, previousReceivedSDP and latestReceivedSDPSequenceNumber and waits for the corresponding answer.

  2. When the corresponding SDP answer is sent, the feature updates the leg’s latestSentSDP, previousSentSDP and latestSentSDPSequenceNumber.

  3. If the offer/answer exchange is successful the current committedSDP becomes the previousCommittedSDP and the leg’s committedSDP is set to the latest sent SDP on the leg. The committedSDPSequenceNumber is set to the latest SDP sequence number.

  4. If the offer/answer exchange is unsuccessful, the previous committedSDP and committedSDPSequenceNumber value(s) (if any) are restored. At which point the feature waits for a new SDP offer and the offer/answer exchange continues.

The feature also maintains an SDP field specifying the exchange initiator. The field is used by the Diameter Service Info Feature feature to set the Media-Initiator-Flag AVP in charging requests. Other features can access the SDP information using the Sentinel SIP Leg API.

Details

Feature script name

SDPMonitor

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None

Feature execution points
Pre

SipAccess_SessionStart SipAccess_PartyRequest SipAccess_PartyResponse SipMidSession_PartyRequest SipMidSession_PartyResponse SipLegEnd SipInstructionExecutionFailure

Post

All execution points (to examine messages queued by other features).
Note
Pre- and Post- Execution Points

The SDP Monitor feature must run as a pre-system feature on the execution points given above, so that it sees all incoming SIP messages.

It must also run as a post-system feature on all execution points, to ensure that messages sent by other features can be inspected before transmission.

A feature parameter must be specified when invoking the feature in execution scripts. This will be either pre in Pre system feature execution points or post in all Post system feature execution points.

Leg SDP fields

These fields on the leg interface are available to other Sentinel SIP features.

Field What it specifies

LatestReceivedSDP

The latest SDP received on the leg.

LatestSentSDP

The latest SDP sent on the leg.

CommittedSDP

The SDP that was committed after the last successful offer/answer exchange.

LatestSentSDPSequenceNumber

The SDP origin sequence number in the last SDP sent on the leg.

LatestReceivedSDPSequenceNumber

The SDP origin sequence number in the last SDP received on the leg.

CommittedSDPSequenceNumber

The SDP origin sequence number in this leg’s committed SDP.

PreviousReceivedSDP

The previous SDP received on the leg.

PreviousSentSDP

The previous SDP sent on the leg.

PreviousSentSDPSequenceNumber

The previous origin sequence number in the previous SDP sent on the leg.

PreviousReceivedSDPSequenceNumber

The previous origin sequence number in the previous SDP received on the leg.

PreviousCommittedSDP

The SDP that was committed by the previous offer/answer exchange.

Session state inputs and outputs

This feature does not read from or write to session state.

Feature responses

Response Reason

featureHasFinished

Feature has finished.

featureCannotStart

Feature parameter error and was unable to start.

Configuration

This feature is not configurable.

Statistics

Statistic What it counts

SDPRollback

The number of times an offer/answer exchange failed and the latest SDP was rolled back. Caused by rejection or failure to send.

SDPOfferReceived

The number of SDP offers that have been received by the feature.

SDPOfferSent

The number of SDP offers that have been sent by the feature.

SDPAnswerReceived

The number of SDP answers that have been received by the feature.

SDPRejectionReceived

The number of sent SDP offers rejected by receiving final error responses.

SDPAnswerSent

The number of SDP answers the feature has sent.

SDPRejectionSent

The number of received SDP offers rejected by sending final error responses.

SDPCommitted

The number of times a successful offer/answer exchange has resulted in a committed SDP.

SDP Rewriter Feature

The SDP Rewriter system feature rewrites session descriptions in messages forwarded between certain legs, to avoid SDP conflicts.

Details

Feature script name

SDPRewriter

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite features

None

Feature execution points

All post execution points

Behaviour

When a feature requires SDP conflict management, it can call SdpRewriting.startSdpRewritingForLegs() to start an SDP rewriting association between a pair of legs. This association is persisted in session state, and includes rules for rewriting SDP sent in either direction, so that conflicts are avoided. The SDP Rewriter feature then examines SDP message bodies on all messages sent on these legs, and rewrites the SDP as appropriate. If either party updates their session description, this feature updates its rewriting rules for the legs, so that changes are propagated correctly to the other party.

For more details see SDP conflict management.

Note

The SDP Rewriter feature must run as a post-system feature on all execution points, to ensure that messages containing SDP sent by other features can be rewritten before transmission.

The feature must run before the SDP Monitor feature, so that SDP Monitor sees the updated SDP, if present.

Session state inputs and outputs

Inputs

Name Type Format Description

SdpRewriterMap

SdpRewriterMap

A map containing Leg associations and SDP rewriting rules, created by SdpRewriting.

Updated when the feature detects a change in the session description, such as a new media line. The rewriting rules are updated so that SDP is rewritten correctly in both directions.

Outputs

None

Configuration

This feature is not configurable.

Statistics

Statistic What it counts

SDPRewritten

The number of times that an SDP message body has been rewritten.

SIP Do Not Charge Feature

DoNotChargeSipSession is a system feature that is used to disable charging for a session.

It disables charging on a SIP session, and carries out these actions:

  • for each active ReservationChargingInstance in the session, clears any charging instructions that are pending and finalises charging if the charging instance is not in the Final state.

  • sets the MonitorCallOnly session state field to true.

Tip

Details

Feature script name

DoNotChargeSipSession

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

N/A

Session state inputs and outputs

Outputs

Name Type Format Description Behaviour if null/invalid

MonitorCallOnly

boolean

This field is true if the session is only being monitored. The initial value of this field is false.

Feature responses

Response Reason

featureHasFinished

feature has finished

SIP Downstream Forking Feature

What is downstream forking?

Downstream forking occurs when something downstream (e.g. S-CSCF) of the application (Sentinel) decides to fork a call (e.g a result of subscriber registration data). A downstream call branch to each destination will be created. All 1XX(with the exception of 100) and 2XX responses must be forwarded upstream and the first final response forwarded will result in all remaining forks with active transactions being terminated using the CANCEL method.

It is possible for one or more additional 200 OKs to arrive whilst the CANCEL is still being processed, in this event these will also be forwarded upstream. In the event this happens, 3GPP TS 24.229 states the UE should ACK the additional 200 OKs and follow immediately with a BYE.

Specification references

  • 3GPP TS 23.228

  • 3GPP TS 24.229

Call flows

S-CSCF Downstream Forking call flow examples. For simplicity, these examples have non-reliable provisional responses.

Downstream fork answers

SCSCF forks INVITE downstream of Sentinel. B-Party- B'' answer

sip downstream forking answers

Downstream fork error

SCSCF forks INVITE downstream of Sentinel. B-Party- B' send 487 Final response

sip downstream forking error

Calling party cancels

SCSCF forks INVITE downstream of Sentinel. A-Party Cancels Call

sip downstream forking cancel

Feature description

Feature script name

SipDownstreamForking

Applicable contexts

SIP service

SAS Support

No

Prerequisite Features

None

The SipDownstreamForking feature handles a SIP call forked downstream by the S-CSCF, an application, or other UAS. This feature must be triggered on every early response and request until the call has been setup.

For each new downstream forked leg (dialog) response, the feature will import the leg into the Sentinel SIP Service and if the original INVITE was received upstream, the feature will forward the response on a new upstream leg (dialog) which is created by the feature and linked with the downstream leg. Subsequent early dialog messages on these legs will be be ignored by this feature but handled in the default way by the Sentinel SIP Service until a final response is received.

When the feature receives a final response, it will detach all other downstream legs and their linked upstream legs from the Service, delegating responsibility to the SIP SIS RA to clean up these remaining dialogs. In the crossover case where a CANCEL is received from the Calling Party and a Called Party forked leg answers, the forked leg that answered will be released (resulting in a BYE request sent).

Note Regardless of which leg sends the final error response, the SIP SIS RA will always send it the initial calling party leg.

  • The imported downstream fork legs will have the following leg name format: downstreamfork[unique session id].

  • The created upstream fork legs will have the following leg name format: upstreamfork[unique session id].

The feature should be installed in the SipAccess_PartyRequest and as the first feature in the SipAccess_PartyResponse. It cannot be run in any other execution points.

Feature interaction

First response on a new forked dialog

The first response on a new forked dialog is delivered by the SIP SIS RA on the activity which sent the INVITE request. Subsequent responses are delivered on the leg created by this feature activity.

If another feature is also using this first response it will be necessary to determine the correct leg as follows:

Leg actualResponseLeg = legManager.getLeg(response.getSipSession());

The leg will only differ from the leg associated with the INVITE dialog if the response.isForked() returns true.

Session State inputs and outputs

This feature does not read from or write to session state.

Error scenarios

Scenario Handling

Error occurred when creating upstream forked Leg

Increment ImportUpstreamForkedLegError

Error occurred when importing downstream forked Leg

Increment ImportDownstreamForkedLegError

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interface.

Sequential Forked SDP Mediation

The Sequential Forked SDP Mediation Feature is used to mediate 183 and 2xx messages into UPDATE’s if multiple 183 messages with SDP content have been received due to a sequential fork.

The first 183 is sent through unchanged. When a subsequent 183 message or 2xx with SDP is received the feature will transform this into an UPDATE to be sent upstream. If a 2xx with SDP is mediated to an UPDATE, a 2xx without SDP is sent to the upstream party once the UPDATE has been responded to by the upstream party.

The one change that is made to the SDP is the session version number in the origin line, the feature ensures this value is always bigger than the previously sent version number if the SDP has changed.

The feature also runs on mid session messages such as a re-INVITE from downstream to ensure that the upstream party always receives SDP origin session version numbers that are bigger than have been previously sent if the SDP has changed.

If while an unreliable 183 is being mediated, a 2xx with SDP is received then the 2xx with SDP is cached until the UPDATE triggered by unreliable 183 is responded to and the 2xx is then mediated.

The Feature configuration allows users to change the behaviour of the feature. The default setting is ALLOWS_UPDATE, this means the feature will look at the allow header of the INVITE message to determine whether or not the UE supports UPDATE messages. If there is no UPDATE value present then the messages will simply be passed on, but if the INVITE did contain UPDATE in its allow list then any subsequent 183’s and 2xx with SDP will be changed into UPDATE messages. The other values of this config override the allow header, if set to ON then the feature will ignore the allow list and always behave as if the UE supports UPDATE messages. If OFF then the feature will not change 183’s or 2xx’s to UPDATEs.

Details

Feature script name

SequentialForkedSDPMediation

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite features

N/A

Feature execution points
Post

SipAccess_PartyResponse SipMidSession_PartyRequest SipMidSession_PartyResponse

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key
for example, <platform>::::

For selecting configuration data

Increment InputParameterErrors,
common cleanup actions

Feature responses

Response Reason

featureCannotStart

No feature configuration could be loaded

featureHasFinished

Feature has finished

Feature configuration

Parameter Type Description

Mediate183ToUpdate

enum

Determines behaviour of feature, valid value are ON, OFF, and ALLOWS_UPDATE

Statistics

Name Description

UpdateSupported

Incremented when the UE indicates that is supports UPDATE messages

UpdateNotSupported

Incremented when the UE indicates no support for UPDATE messages

SDPUpdated

Incremented when the feature modifies the outgoing SDP

Mediated183ToUpdate

Incremented when the feature changes a 183 message into an UPDATE

Example Flow

sequential update preconditions

Session Refresh Feature

The Session Refresh feature periodically instructs all INVITE dialog legs to refresh, and ends the call once the max duration is reached.

Details

Feature script name

SessionRefresh

Applicable contexts

SIP service

Call-Type

All

Session Plan

All

Execution points
Pre

SipAccess_SipRequest SipAccess_ChargingReauth SipMidSession_ChargingReauth SipEndSession

Post

SipAccess_SipResponse SipAccess_ServiceTimer

Feature Extension Events

None

Network Operator Config

Yes

Subscriber Config

None

POJO or SBB

POJO

Feature FSMs

None

Feature Parameters

None

SAS Support

No

Prerequisite features

None

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key + for example, <platform>::::

For selecting configuration data

Increment InputParameterErrors common cleanup actions

CallEstablished

Boolean

true or false

true if the session has been established

Initially set to false

Feature responses

Response Reason 
featureHasFinished

Feature has completed execution for the current invocation.

 
featureIssuedWarning

Feature has encountered a non-fatal issue during execution.

Feature Statistics

SessionRefresh statistics are tracked by the sentinel.sip SBB and can be found under the following parameter set:
SLEE-Usage → sentinel.sip service ID → sentinel.sip SBB ID → feature.SessionRefresh

Name Type Description 
Started

Counter

Incremented when the feature is triggered.

 
FailedToStart

Counter

Incremented when the feature fails to start.

 
FailedDuringExecution

Counter

Incremented when the feature fails while executing.

 
IssuedWarning

Counter

Incremented when the feature issues a warning.

 
TimedOut

Counter

Incremented when the feature times out during execution.

 
SessionRefreshTimerStarted

Counter

Incremented when the feature starts the periodic timer.

 
SessionRefreshTimerStopped

Counter

Incremented when the feature stops the periodic timer.

 
InstructRefreshOnTimerFire

Counter

Incremented when the feature instructs legs to refresh due to the timer firing.

 
InstructRefreshOnChargingReauth

Counter

Incremented when the feature instructs legs to refresh due to a charging reauth.

 
MaxCallDurationReached

Counter

Incremented when the feature ends a call due to the max duration being exceeded.

Configuration

This feature reads configuration from the SessionRefreshProfileTable profile table. Profiles in this table are named based on the Sentinel selection key that they should be applied to. The profile specification for this table is sentinel-sip-session-refresh-feature-profile.

Parameter Type Default Value Description 
TimerInterval
 
long
 
290

Interval of periodic timer (seconds)

 
RefreshPeriod
 
long
 
570

Period of no activity for leg to refresh (seconds)

 
MaxCallDuration
 
int
 
86400

Maximum time the call may be active for (seconds)

 
RefreshWithUpdateIfAllowed
 
boolean
 
false

Whether the session should be refreshed using UPDATE requests so long as the endpoint allows UPDATE requests.

Session Input Data

Name Type Description

SentinelSelectionKey

SentinelSelectionKey

Used to select configuration data. Issue a feature warning and use default configuration values.

CallEstablished

boolean

Used to determine whether the session should be considered established before receiving an ACK.

MaxCallDuration

Long

If this field is given a value greater than 0, it will be used in place of the configured max call duration for the session. The value is in milliseconds.

Session Output Data

Name Type Description

SessionEstablishedTime

long

Unix timestamp representing the time the session was established.

MaxCallDurationExpireTime

long

Unix timestamp representing the time at which the maximum call duration will be reached.

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

Behaviour

On an incoming initial ACK or when the callEstablished session state field is true, a repeating timer is set. The timer’s period is specified by the TimerInterval value in the feature’s configuration. This timer is armed redundantly if the session is replicated. The number of repetitions will be so such that the timer will stop firing soon after the maximum call duration is reached.

Each time the timer fires, the feature first checks if the maximum call duration has been exceeded. If the max call duration has been exceeded, the feature will end the session. If not, Leg.refreshSession is instructed on each leg using the RefreshPeriod from the feature’s configuration. The RefreshPeriod represents the period of no activity before a refresh request should occur. If no messages have been sent or received on a leg within the RefreshPeriod, a refresh request transaction will be initiated.

Refresh requests are by default re-INVITE requests. The Session Refresh feature can be configured using the RefreshWithUpdateIfAllowed configuration to use UPDATE requests instead. If an endpoint did not include the UPDATE method in it’s Allows header then the RefreshWithUpdateIfAllowed configuration is ignored.

Note RFC 6141 describes this process in SIP INVITE dialogs. This will cause all legs to be refreshed immediately.

Receipt of a Re-Auth-Request on the Ro interface

RFC 4005 (https://tools.ietf.org/html/rfc4005#page-13) states:

A Diameter server may initiate a re-authentication and/or re- authorization service for a particular session by issuing a Re-Auth- Request (RAR) message [BASE].

For example, for pre-paid services, the Diameter server that originally authorized a session may need some confirmation that the user is still using the services.

If a NAS receives an RAR message with Session-Id equal to a currently active session and a Re-Auth-Type that includes authentication, it MUST initiate a re-authentication toward the user, if the service supports this particular feature.

Therefore when receiving a RAR, Sentinel responds with an RAA, initiates a Credit Control Update Request (CCR-U) and triggers this feature. This means that one or more SIP dialog refreshes run in parallel to the CCR-U. If the session refresh is successful then no further action is necessary. However if SIP dialog refreshes are not successful then Sentinel will move to the End Session point-in-session, thereby sending a CCR-T.

Additionally when the Validity-Time timer expires, Sentinel acts as though a RAR was received.

Store Header Info Feature

The StoreHeaderInfo feature is responsible for extracting information from incoming SIP requests that is relevant for charging purposes. It looks at and records information relevant for charging purposes, specifically from the Contact, Call-ID, P-Charging-Vector, and P-Access-Network headers on SIP requests and responses received from the served user. It records information from the P-Early-Media, Allow, and Contact headers relevant to access transfer procedures. It also records the presence of the OC-Terminating-Domain header.

Details

Name in feature scripts

StoreHeaderInfo

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

Determine Call Type Feature

Feature execution points

Many, will be triggered once for each SIP request or response received by Sentinel.

Timer usage

N/A

Source Code

This feature’s source code is available in the Sentinel SDK in the sentinel-sip-service-information-modules module pack. It can be viewed by using the create-module command in the SDK with that module pack. This command will prompt you for information needed to create the new modules, once completed the original source for the feature can be found in the new modules.

The module-pack includes the following modules relevant to this feature:

Module Name Description

sentinel-sip-service-information-modules

Group module for all service information features, including the modules listed below.

sentinel-sip-service-information-session-state-library

Contains the session state interface for the feature.

sentinel-sip-store-header-info-feature

Contains the feature itself.

Session state inputs and outputs

Inputs

Name Type Purpose

CallType

Enum

Used when determining if a message was received from the served user.

Outputs

Name Type Description

ChargingIdentifier

String

The Charging Identifier for the served user, extracted from one of a number of possible parameters on the P-Charging-Vector header.

IMSChargingId

String

The IMS Charging Identifier for the served user, taken from the icid-value of the P-Charging-Vector header. May be equal to the ChargingIdentifier.

TerminatingInterOperatorIdentifier

String

The Terminating Inter-Operator Identifier, taken from the term-ioi parameter of the P-Charging-Vector header.

OriginatingInterOperatorIdentifier

String

The Originating Inter-Operator Identifier, taken from the orig-ioi parameter of the P-Charging-Vector header.

IMEI

String

The IMEI, extracted from the Contact header of the incoming message.

UserSessionId

String

The Call-ID for the access leg. Used as User Session Id in Diameter charging.

HeadersByLeg

HeadersByLeg

A map containing header name-value pairs, organized by leg name. eg records the value of the P-Early-Media header on the CalledParty leg.

IsOCTerminatingDomainPresent

boolean

Set to true if a response includes the OC-Terminating-Domain header.

Feature responses

Response Reason

featureHasFinished

feature has finished

Statistics

Name Description

SetAccessNetworkInfo

Counter incremented when the AccessNetworkInfo field is set in session state by the feature.

SetPEarlyMedia

Counter incremented when the P-Early-Media header is found in the message and set in the headersByLeg object in session state.

SetChargingIdentifier

Counter incremented when the ChargingIdentifier field is set in session state by the feature.

SetIMSChargingId

Counter incremented when then IMSChargingId field is set in session state by the feature.

SetTerminatingIOI

Counter incremented when TerminatingInterOperatorIdentifier is set in session state by the feature.

SetOriginatingIOI

Counter incremented when OriginatingInterOperatorIdentifier is set in session state by the feature.

SetIMEI

Counter incremented when IMEI is set in session state by the feature.

SetUserSessionId

Counter incremented when UserSessionId is set in session state by the feature.

Behaviour

The StoreHeaderInfo feature runs whenever a SIP request or response is received by Sentinel. Initially the feature examines which leg the message was received on to determine whether the message came from the served user (i.e. the calling party on the originating instance, and the called party on a terminating instance). If the message was not received from the served user, the feature will not attempt to modify headers related to charging. If the message was received from the served user, the feature will attempt to extract charging information from the message headers as described below. Other headers are examined in all cases, regardless of served leg. Once it has done this, the feature will finish execution.

P-Access-Network-Info Header

If the P-Access-Network-Info header is present on the message, it will be recorded in the headersByLeg session state field. If the active leg already had a value for this header, it will be updated.

Note

3GPP TS 24.229 (Release 8 and later) permits multiple P-Access-Network-Info header values in a message. However for charging purposes, 3GPP TS 32.299 Release 8 only allows a single Access-Network-Information AVP inside the IMS-Information grouped AVP. This discrepancy is corrected in Release 12, but this product targets Release 8 (specifically 8.13.0). So at this time we only read the first P-Access-Network-Info header value and use this in the single Access-Network-Information AVP in the AVP CDR and the final Ro Credit-Control-Request.

P-Charging-Vector Header

If the P-Charging-Vector header is present, then the feature will attempt to extract several pieces of information:

  • The value of the icid-value will be taken and stored in the IMSChargingId session state field.

  • If the term-ioi parameter is present, its value will be taken and stored in the TerminatingInterOperatorIdentifier session state field.

  • If the orig-ioi parameter is present, its value will be taken and stored in the OriginatingInterOperatorIdentifier session state field.

  • If any additional charging identifier parameters are present, one will be taken and stored in the ChargingIdentifier session state field.

    • Any of the following parameters can be used: gcid, dslcid, bcid, itc-id, or ecid.

    • If no additional charging identifiers are found, the icid-value will be used for the ChargingIdentifier.

Contact Header

If there is a +sip.instance parameter on the Contact header of the incoming message, the feature will look at its value and attempt to extract a valid IMEI from it. If an IMEI is found, it will be taken and stored in the IMEI session state field.

Call-ID

The value of the Call-ID header is used as an identifier for the session in Diameter charging. So, the value of this header will be taken and stored in the UserSessionId session state field.

P-Early-Media Header

If the P-Early-Media header is present, the header value will be recorded for the triggering leg in the headersByLeg session state field.

Allow Header

If the Allow header is present, the header values will be recorded for the triggering leg in the headersByLeg session state field. If there are multiple headers, these will all be preserved.

Remote Target

If the incoming message is a target refresh and the Contact header is present, the header value will be recorded for the incoming leg in the headersByLeg session state field.

OC-Terminating-Domain Header

If the OC-Terminating-Domain header is present in a SIP response, the IsOCTerminatingDomainPresent session state flag is set to true.

Subscribe Downstream Forking Feature

The Subscribe Downstream Forking Feature manages the additional SIP legs that can result from forked subscriptions.

  1. When Sentinel sends or forwards an initial SUBSCRIBE, a downstream proxy may fork the request to several targets.

  2. Each target that accepts the SUBSCRIBE will send an initial NOTIFY back to Sentinel.

  3. The first NOTIFY to arrive is associated with the original downstream leg, and will automatically be forwarded upstream by the B2BUA Feature if it previously forwarded the SUBSCRIBE .

  4. If additional NOTIFYs arrive as a result of a fork, then the SubscribeDownstreamForking feature is needed to determine how to handle them.

  5. Each additional NOTIFY potentially creates a new SIP dialog, or leg in Sentinel.

    • If the event package (determined by the NOTIFY Event: header) does not support forking, then the SubscribeDownstreamForking feature automatically rejects the NOTIFY with a 481 response, and no new leg is created.

    • If the event package does support forking, then the SubscribeDownstreamForking feature creates new downstream and upstream legs, and schedules the NOTIFY to be forwarded upstream. The new upstream and downstream legs are linked, and subsequent requests on these legs will be handled by the B2BUA Feature.

    • The names of event packages that are known to support forking are configured as per [forking-event-packages-configuration].

Details

Feature script name

SubscribeDownstreamForking

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

B2BUA Feature

Feature execution point

SubscriptionSipRequest [Pre]

Specification references

Example Call Flows

Forked subscription accepted

This call flow shows a downstream proxy forking a SUBSCRIBE request. The resulting NOTIFYs from each target are forwarded upstream.

subscribe downstream forking accepted

Forked subscription rejected

This call flow shows a downstream proxy forking a SUBSCRIBE request. In this case, assume that the subscribed event package does not allow forking. The SubscribeDownstreamForking feature rejects the forked NOTIFY immediately with a 481 response.

subscribe downstream forking rejected

Session state inputs and outputs

Inputs

Name Type Format Description

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key
for example, <platform>::::

For selecting configuration data

Outputs

Name Type Format Description

ForkedNotifyResult

ForkedNotifyResult

Enum values:
NONE,
REJECTED, or
FORWARDED

Describes the outcome of the feature:

  • NONE: no action was taken

  • REJECTED: the forked NOTIFY was rejected with a 481 response

  • ACCEPTED: the forked NOTIFY will be forwarded upstream, with new upstream and downstream legs created for the new subscription.

Configuration

Forking event packages configuration

Parameter Type Description

ForkingEvents

String[]

Names of SIP event packages that support forking.

The default set of event packages that support forking is:

  • call-completion

  • dialog

  • message-summary

  • refer

  • winfo

This is derived from the current list of standard event packages in the IANA SIP Event Packages Registry.

If an event package happens to be an event template package (such as winfo above), all event packages that derive from it are handled automatically. So the fictional package foo.winfo will automatically support forking because winfo does.

Additional event packages may be added as standards evolve, or to support proprietary events.

Statistics

Statistic When incremented

ForkedSubscriptionAccepted

A forked NOTIFY is accepted because the event package allows forked subscriptions.

ForkedSubscriptionRejected

A forked NOTIFY is rejected because the event package does not allow forked subscriptions.

ForkedSubscriptionDownstreamLegError

The feature is unable to create the leg representing the downstream side of a forked subscription.

ForkedSubscriptionUpstreamLegError

The feature is unable to create the leg representing the upstream side of a forked subscription.

SIP User Features

Sentinel includes many user features for SIP networks:

Accept SIP Feature

Description

Feature name

AcceptSip

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None

Sentinel feature which verifies the triggering event is a SIP INVITE and initializes a SIP session. This includes setting the session type to 'sipcall' and incrementing the accepted dialogs counter.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>:<network>:::)

Selection key to be initialized with session type

Runtime exception handled by feature runner

Outputs

Name Type Format Description

SessionType

com.opencloud.sentinel.common.SessionType

sipcall

Session type set to sipcall

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>:<network>:<session type>::)

Updated selection key including session type determined from application context

Error scenarios

Scenario Handling

Trigger not a SipRequest

Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

Trigger event is not a SipRequest

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

B2BUA Subscription Activity Guard Feature

The B2BUA Subscription Activity Guard feature tracks outstanding subscriptions and invalidates sessions which have not been correctly shut down.

The B2BUA Subscription activity guard feature is used to protect against servers not correctly terminating their subscriptions. For each non-terminating notify that is B2BUAed by Sentinel, this feature starts a timer which fires after the expiration of the notify. If another notify for the same subscription is received, the timer is updated. If a terminating notify is sent, the timer is cleared and removed. If the timer fires, this shows that a terminating notify has not been sent by the server. In this case, the feature invalidates and detaches from both legs of the call, freeing resources and cleaning up as appropriate.

Details

Feature script name

SubscriptionActivityGuard

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

B2BUA

Requisite Features execution point [script]

SubscriptionSipRequest [Pre]

Timer usage

Feature-targeted timer triggers feature directly on expiry. Does not need to be registered against SipAccess_ServiceTimer execution point.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key
for example, <platform>::::

For selecting configuration data

Increment InputParameterErrors Common cleanup actions

Feature responses

Response Reason

featureHasFinished

feature has finished

Statistics

Name Description

ActivityGuardTimeout

Number of times the timer fired and the feature had to terminate the subscription.

B2BUA Subscription Activity Guard configuration

The configuration for the B2BUA Subscription Activity Guard Feature is provisioned in the following table:

Parameter Type Description

ActivityGuardWaitTimeMillis

long

Number of milliseconds to wait after the expiry time before shutting down the legs.

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

Call Parties Address Determination Feature

Description

Feature name

CallPartiesAddressDetermination

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

Determine Call Type Feature

The Call Parties Address Determination feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature attempts to extract the called and calling parties addresses from the INVITE and set the ‘CallingPartyAddress’ and ‘CalledPartyAddress’ session state fields. The feature analyses the relevant ‘InviteRequest’ on the ‘callingParty’ leg and the ‘calledParty’ leg (the latter only being used in the third-party-triggered case when determining the called party address).

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

calledParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip javadoc

INVITE sent to the called party

Runtime exception handled by feature runner

callingParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip javadoc

INVITE received from (respectively, in the NetworkInitiated case, sent to) the calling party

Runtime exception handled by feature runner

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

For selecting which Leg InviteRequest to use for determining CalledPartyAddress

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

CalledPartyAddress

String

MSISDN

The called party address

CallingPartyAddress

String

MSISDN

The calling party address

Error scenarios

Scenario Handling

Address record in SIP Invite is null or missing URI

Report featureCannotStart

Feature responses

Response Reason

featureFailedToExecute

Address determination of calling and called parties failed

featureHasFinished

feature has finished

Configuration

Call Parties Address Determination Feature cannot be configured.

Determine Call Type Feature

Description

Feature name

DetermineCallType

Applicable contexts

SIP service

SAS Support

No

Prerequisite Features

None

The Determine Call Type feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature attempts to identify the call’s type, one of MobileOriginating, MobileTerminating, or MobileForwarded, which is stored in the CallType session state variable for future features.

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

callingParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip javadoc

INVITE received from (respectively, in the NetworkInitiated case, sent to) the calling party

Runtime exception handled by feature runner

Configuration

Parameters Type Description

additionalCallForwardingDetection

boolean

When true, additional parameters will be considered when distinguishing between MobileOriginating and MobileForwarded calls. (default: true)

Configuration feature naming

Configuration Profile Table Name Description Profile Naming

DetermineCallTypeConfigurationTable

Sentinel configuration table

SentinelSelectionKey (for example, OpenCloud::::)

Session state inputs and outputs

Outputs

Name Type Format Description

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call

Statistics

Statistic When incremented

Started

The feature is invoked.

FailedToStart

The feature fails to start.

IssuedWarning

The feature encounters a non-fatal error and alerts the core.

FailedDuringExecution

The feature encounters any fatal error and alerts that core.

TimedOut

The feature fails to complete execution within the allowable time frame.

CallTypeIsMobileOriginating

The feature determines that the call type is MobileOriginating.

CallTypeIsMobileTerminating

The feature determines that the call type is MobileTerminating.

CallTypeIsMobileForwarded

The feature determines that the call type is MobileForwarded.

Error scenarios

Scenario Handling

Failed to get INVITE request from calling party leg

Report featureCannotStart

Insufficient information to determine call type

Report featureFailedToExecute

Feature responses

Response Reason

featureCannotStart

CallingParty leg InviteRequest has not been set

featureFailedToExecute

Call type could not be determined

featureHasFinished

feature has finished

Behaviour

The call’s session type is classified as one of:

  • MobileOriginating

  • MobileTerminating

  • MobileForwarded

A CallType enum is defined to represent the values, and the session type is stored in session state variable CallType.

The feature uses either one of two headers on an incoming SIP request to determine the call type: P-Served-User and Route. The P-Served-User header is the preferred source of information. The Route header is only checked if the call type cannot be determined from the P-Served-User header.

P-Served-User Header

There are two parameters of interest on the P-Served-User header.

The first is a valueless orig-cdiv parameter, if this is present the call type will be classified as MobileForwarded. Otherwise, the feature will look for the sescase parameter, the value of that parameter will determine the call type as follows:

Parameter Value Resulting Call Type

orig

MobileOriginating or MobileForwarded (see Additional Call Forwarding Detection below)

term

MobileTerminating

orig-cdiv

MobileForwarded

If none of these parameters or values are present, the feature will check the Route header instead.

Route Header

The feature always looks at the top-most route header of the incoming message. It will look for the following valueless parameters on the header to determine the call type:

Parameter Name Resulting Call Type

orig

MobileOriginating or MobileForwarded (see Additional Call Forwarding Detection below)

term

MobileTerminating

orig-cdiv

MobileForwarded

If none of these parameters or values are present, the feature will use the default call type: MobileTerminating.

Additional Call Forwarding Detection

When a parameter on the P-Served-User or Route header indicates the call type is MobileOriginating and the AdditionalCallForwardingDetection config option is set to true, the feature will execute additional checks to determine if the call has been forwarded.

There two additional checks, one on the Request-URI the other on the History-Info header. The call type will be determined to be MobileForwarded if either one of the following conditions are met:

  1. The Request-URI has a cause parameter with one of the following values: 302, 404, 408, 480, 486, 487, 503.

  2. There is a History-Info header present on the request.

If neither condition is met, the call type will be determined to be MobileOriginating.

Determine Chargeable Leg Feature

Description

Feature name

DetermineChargeableLeg

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite Features

DetermineCallType

The Determine Chargeable Leg feature determines the chargeable leg of a call based on the call type. This information is then used to set a session state field which can be used by other VoLTE features that need to do charging-related activities.

By default the feature runs directly after the Determine Call Type feature.

Session input and output variables

Session input variables

Session state variable name Variable type 
CallType

Enum

Session output variables

Session state variable name Variable type Comments 
LegForCdrs

String

The leg that will be used for the interim CDR logic

Error scenarios

Scenario Handling

Call type not set in session state

Report featureFailedToExecute

Unable to access leg manager or incoming leg

Report featureFailedToExecute

Chargeable Leg

  • If the call type is "Mobile Originating" then the LegForCdrs session state field will get set to the name of the calling party leg, if it exists.

  • If the call type is "Mobile Terminating" then the LegForCdrs session state field will get set to the name of the leg linked to the calling party leg, if it exists.

  • If the call type is anything else then the session state field will not get changed.

Feature responses

Response Reason

featureFailedToExecute

Chargeable leg could not be determined

featureHasFinished

feature has finished

Configuration

Determine Chargeable Leg cannot be configured.

Determine Registration Status Feature

Description

Feature name

DetermineRegistrationStatus

Applicable contexts

SIP service

SAS Support

No

Prerequisite Features

None

The Determine Registration Status feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature attempts to identify the user’s registration state as one of Registered or Unregistered, which is then stored in the SipRegistrationStatus session state variable for future features.

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

callingParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip javadoc

INVITE received from the calling party Runtime exception handled by feature runner

Session State inputs and outputs

Outputs

Name Type Format Description

SipRegistrationStatus

com.opencloud.sentinel.common.SipRegistrationStatus

One of: Registered, Unregistered

Registration status of this call

Error scenarios

Scenario Handling

Failed to get an INVITE request from the calling party leg

Report featureCannotStart

Insufficient information to determine registration status

Report featureFailedToExecute

Registration status

The call’s registration status is classified as one of:

  • Registered

  • Unregistered.

A SipRegistrationStatus enum is defined to represent the values, and the registration status is stored in session state variable SipRegistrationStatus.

The session type is determined based on the following pseudo code:

Function determineRegistrationStatus(callingPartyInvite)

    regState = determineRegistrationStatusBasedOnPServedUser(callingPartyInvite)

    IF regState is null
    THEN
        featureFailedToExecute()
    ENDIF


SipRegistrationStatus Function determineRegistrationStatusBasedOnPServedUser(callingPartyInvite)
    header = callingPartyInvite.getAddressHeader(P_SERVED_USER)
    IF header is null
    THEN
        return null
    ENDIF

    regState = header.getParameter(REGSTATE)
    IF regState not set
    THEN
        return null
    ENDIF

    IF regState is REG
    THEN
        return Registered
    ELSEIF regState is UNREG
    THEN
        return Unregistered
    ELSE
        return null

Feature responses

Response Reason

featureCannotStart

CallingParty leg InviteRequest has not been set

featureFailedToExecute

Registration status could not be determined

featureHasFinished

feature has finished

Configuration

Determine Registration Status cannot be configured.

Determine Service Type Feature

Description

Warning This feature is a placeholder. The integrator will need to provide a feature which determines service type and sets the SipServiceType (one of Voice/Fax/Data/Video) session state field correctly in the context of the target network.

Feature name

DetermineServiceType

Applicable contexts

SIP service

SAS Support

No

Prerequisite Features

None

The Determine Service Type feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature classifies the call’s service Type, which is stored in a session state variable for future features.

Service type

The call’s service type is classified as one of:

  • Voice

  • Video

  • Data

  • Fax.

A ServiceType enum is defined to represent the values, and the service type is stored in session state variable ServiceType.

The service type is determined based on the following pseudo code:

Feature responses

Response Reason

Configuration

Configuration Profile Naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:ClassifyCallScenario:HomeVLR

${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable

Feature specific Address List entry table

${SELECTIONKEY}:ClassifyCallScenario:HomeVLR:${ADDRESS}

Determine if Roaming Feature

Description

Feature name

DetermineIfRoaming

Applicable contexts

SIP service

SAS Support

No

Prerequisite Features

None

The Determine If Roaming feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature sets the call’s Roaming Indicator, which is stored in a session state variable for future features. The DetermineIfRoaming feature analyses the p-visited-network-id header and compares it with the platforms set of home network ids.

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

callingParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip javadoc

INVITE received from the calling party

Runtime exception handled by feature runner

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting the Home Network IDs to determine RoamingIndicator \

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

RoamingIndicator

java.lang.Boolean

True: Roaming, False:NotRoaming

Roaming status indicator

Feature responses

Response Reason

featureCannotStart

SessionState SentinelSelectionKey is not set or CallingParty leg InviteRequest has not been set

featureFailedToExecute

Roaming status could not be determined

featureHasFinished

feature has finished

Roaming indicator

The call’s roaming indicator is classified as one of:

  • Roaming

  • NotRoaming

The roaming indicator is stored in session state variable RoamingIndicator as a Boolean.

The roaming indicator is determined based on the following pseudo code:

Function determineIfRoaming(callingPartyInvite)

    roamingIndicator = determineRoamingBasedOnPVisitedNetworkHeader(callingPartyInvite)

    IF roamingIndicator is null
    THEN
        roamingIndicator = determineRoamingBasedOnRecordRouteAnalysis(callingPartyInvite)
    ENDIF

    /* if that still didn't work report a feature error*/
    IF roamingIndicator is null
    THEN
        /* Roaming status could not be determined */
        featureFailedToExecute()
    ENDIF


RoamingIndicator Function determineRoamingBasedOnPVisitedNetworkHeader(callingPartyInvite)

    headers = callingPartyInvite.getHeaders("p-visited-network-id")
    IF header is null
    THEN
        return null
    ENDIF

    /* assumes all values are the same (RFC3455 says 'hopefully' they are!)
     * so just take the first one
     */
    visitedNetworkID = headers.next()

    List<String> homeNetworkIDs = getSessionState().getSentinelSelectionKey().getHomeNetworkIDs();

    IF homeNetworkIDs contain visitedNetworkIDs THEN
       return false
    ENDIF

    return true

/* Roaming based on record route anaylsis is NOT fully implemented.  However it will affect the
 * setting of the roaming indicator, so it is included here for completeness.
 */
RoamingIndicator Function determineRoamingBasedOnRecordRouteAnalysis(callingPartyInvite)

       headers = callingPartyInvite.getAddressHeaders(RecordRouteHeader.NAME);
       IF SipParseException THEN
           TRACE "Unable to parse. Interpreting call as non-roaming.")
           return false
       ENDIF

       IF headers is null OR headers is empty {
            TRACE ("No header present: Interpreting call as non-roaming.");
            return false;
       ENDIF

       return null;

Configuration Profile Naming

Configuration Profile Table Name Description Profile Naming

SipSentinelConfigurationTable

Sentinel configuration table (profile configuration containing home network ids)

${SELECTIONKEY}:homeNetworkIDs

End Mid Session Feature

Description

Feature name

EndMidSession

Applicable contexts

SIP Service

SAS Support

No

Prerequisite Features

None

Sentinel mid session feature to notify the Sentinel core to end the call. When notifying the core the cause code is determined according to the following pseudo-code:

    FUNCTION determineCauseCode()

        // an error set by another feature takes highest precedence
        cause = sessionState.getUserEndSessionCause()
        IF cause IS SET
            return cause

        // otherwise try to determine the release cause from the latest CCA
        cause = determineCauseFromCCA(sessionState.getLatestOcsAnswer())
        IF cause IS SET
            return cause

        // otherwise use a default
        return SipResponse.SC_FORBIDDEN


    FUNCTION determineCauseFromCCA(cca)

        //if there was no CCA, we cannot determine a code from there; CALL_REJECTED will be set
        if cca IS UNSET
            return null

        SWITCH (cca.getResultCode())
            CASE DiameterCcaResultCode.DIAMETER_USER_UNKNOWN
                return SipResponse.SC_NOT_FOUND
            CASE DiameterCcaResultCode.DIAMETER_CREDIT_LIMIT_REACHED
                return SipResponse.SC_PAYMENT_REQUIRED
            CASE DiameterResultCode.DIAMETER_SUCCESS
                return determineCauseFromMscc(cca)
            DEFAULT
                return SipResponse.SC_FORBIDDEN

Supports ‘sip_trigger’, ‘http_trigger’ and ‘sipcall’ session types.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SessionType

com.opencloud.sentinel.common.SessionType

One of: sip_trigger, http_trigger, sipcall

Session type of this call for choosing how to determine cause code from LatestOcsAnswer

Report featureFailedToExecute, featureHasFinished

UserEndSessionCause

Integer

Any release code

A pre-determined release cause

Attempt to determine cause from LatestOcsAnswer

LatestOcsAnswer

org.jainslee.resources.diameter.ro.types.CreditControlAnswer

Credit-Control-Answer

For determining release cause code if the UserReleaseCause is not set

Use default call release cause SC_FORBIDDEN

Outputs

This feature does not modify session state.

Error scenarios

Scenario Handling

SessionType is not supported

Report featureFailedToExecute

Feature responses

Response Reason

featureHasFinished

feature has finished

featureFailedToExecute

Invalid session type — trigger should be one of sip_trigger, http_trigger, or sipcall

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

End Session Feature

Description

Feature name

EndSession

Applicable contexts

SIP service

SAS Support

No

Prerequisite Features

None

Sentinel initial trigger feature to notify the Sentinel core to end the call. Supports ‘sip_trigger’, ‘http_trigger’ and ‘sipcall’ session types. When notifying the core the cause code is determined according to the following pseudo-code:

    FUNCTION determineCauseCode()

        // an error set by another feature takes highest precedence
        cause = sessionState.getUserEndSessionCause()
        IF cause IS SET
            return cause

        // otherwise try to determine the release cause from the latest CCA
        cause = determineCauseFromCCA(sessionState.getLatestOcsAnswer())
        IF cause IS SET
            return cause

        // otherwise use a default
        return SipResponse.SC_FORBIDDEN


    FUNCTION determineCauseFromCCA(cca)

        //if there was no CCA, we cannot determine a code from there; CALL_REJECTED will be set
        if cca IS UNSET
            return null

        SWITCH (cca.getResultCode())
            CASE DiameterCcaResultCode.DIAMETER_USER_UNKNOWN
                return SipResponse.SC_NOT_FOUND
            CASE DiameterCcaResultCode.DIAMETER_CREDIT_LIMIT_REACHED
                return SipResponse.SC_PAYMENT_REQUIRED
            CASE DiameterResultCode.DIAMETER_SUCCESS
                return determineCauseFromMscc(cca)
            DEFAULT
                return SipResponse.SC_FORBIDDEN

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SessionType

com.opencloud.sentinel.common.SessionType

One of: sip_trigger, http_trigger, sipcall

Session type of this call for choosing how to determine cause code from LatestOcsAnswer

Report featureFailedToExecute, featureHasFinished

UserEndSessionCause

Integer

Any release code

A pre-determined release cause

Attempt to determine cause from LatestOcsAnswer

LatestOcsAnswer

org.jainslee.resources.diameter.ro.types.CreditControlAnswer

Credit-Control-Answer

For determining release cause code if the UserReleaseCause is not set

Use default call release cause SC_FORBIDDEN

Outputs

This feature does not modify session state.

Error scenarios

Scenario Handling

SessionType is not supported

Report featureFailedToExecute

Feature responses

Response Reason

featureFailedToExecute

Invalid session type

endSession Instruct

sentinel core to end the session and report cause

featureHasFinished

feature has finished

Configuration

End Session cannot be configured.

Error Code Announcement Feature

This feature optionally plays an announcement based on the response status when an INVITE error response is being forwarded to the calling party during call setup.

Details

Feature name

ErrorCodeAnnouncement

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite features

None

Session State inputs and outputs

Inputs

Name Type Purpose

SentinelSelectionKey

SentinelSelectionKey

Used to select error code mappings.

EarlyMediaAnnouncementInfoQueue

List<SipAnnouncementInformation>

Used to see if announcements have already been set.

EarlyMediaAnnouncementInProgress

boolean

Used to determine if an announcement is already playing.

Outputs

Name Type Purpose

EarlyMediaAnnouncementInfoQueue

List<SipAnnouncementInformation>

Used to set a new announcement.

EndSessionAfterAnnouncement

int

Used to select a response status to terminate the call with after an announcement is played.

Configuration

This feature uses profile configuration to map SIP error response codes to announcements to be played. These mapping are kept in a profile table called ErrorCodeAnnouncementMappingTable. Entries in the table are scoped by Sentinel Selection Key along with the value of the error code they correspond to. For example, a profile may be named: Metaswitch:Metaswitch::::404.

Each profile has the following fields:

Name Type Description

ErrorCode

String

The error code the mapping applies to. Can be set to DEFAULT to apply to all error codes not otherwise included on the table. Must be equal to the final part of the profile name.

AnnouncementID

long

The ID number of the announcement to be played for the error code. Use 0 (or none in the provisioning interface) to explicitly prevent an announcement from being played.

EndCallWith487Response

boolean

If true, after the announcement is finished, the call will be terminated with a 487 response. If false, the call will be terminated using the original error response code that triggered the announcement.

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

Statistics

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

Name Type Description 
Started

Counter

Incremented when the feature is triggered.

 
FailedToStart

Counter

Incremented when the feature fails to start.

 
FailedDuringExecution

Counter

Incremented when the feature fails while executing.

 
IssuedWarning

Counter

Incremented when the feature issues a warning.

 
TimedOut

Counter

Incremented when the feature times out during execution.

 
PlayingAnnouncement

Counter

Incremented when the feature queues an announcement to be played.

 
SkippingDueToAnnouncementInProgress

Counter

Incremented when the feature skips response analysis because an announcement has already been set.

 
SkippingDueToAlreadyAnnouncedUpstream

Counter

Incremented when the feature does not play an announcement because it has detected that an error announcement has already been played by a downstream node.

 
SetCustomHeaderOnFinalResponse

Counter

Incremented when the feature successfully adds a header on the outbound final response to indicate that it has played an error announcement.

 
UnableToSetCustomHeaderOnFinalResponse

Counter

Incremented when the feature fails to add a header on the outbound final response to indicate that it has played an error announcement.

Behaviour

The feature is triggered by any incoming SIP response received during call setup.

Before attempting to play an announcement, the feature will check that a number of conditions have been met:

  1. No other announcement is in progress or has been queued to play.

  2. The incoming response is a 4xx, 5xx, or 6xx response to an initial INVITE request.

  3. The response was received on a leg that is linked to another leg.

  4. A response with the same status code has been queued to be sent on the linked leg.

  5. No other error code announcement has been played by a downstream node on the same network.

If any of these conditions are not met, the feature will finish execution without attempting to play an announcement.

If the conditions are met, then the feature will check the ErrorCodeAnnouncementMappingTable for a profile that matches both the status code of the incoming response, and the current Sentinel selection key. If no such profile is found the feature will look for a profile labelled DEFAULT (while still matching the selection key).

If a profile is found using either method, and it indicates that an announcement should be played (i.e. the profile has a non-zero AnnouncementID); then the feature will queue an announcement with the indicated AnnouncementID. The feature will also give an instruction to terminate the call after the announcement has been played. Depending on the value of the EndCallWith487Response field on the profile, the status code of the response used to terminate the call will either be 487, or the code from the original incoming response.

In the event no profile is found, the feature will finish execution without queuing an announcement.

The SIP Play Announcement Feature is responsible for actually playing the announcement.

Suppression Of Repeat Announcements

The feature uses a custom SIP header (OC-Error-Code-Announced) to prevent multiple error code announcements being played in the same call by different AS instances.

When the feature is invoked on an incoming error response it will check for the presence of this header on the response. If it is present, the feature will not attempt to play an error code announcement.

When the feature does play an announcement, it will add this header to the outbound final error response that is sent after the announcement is complete. The header value indicates the original error code that triggered the announcement (even when the actual response status code is changed to 487).

This header should be stripped before it leaves the network, therefore multiple error code announcements could still be played if some legs of the call are not in the same network.

North American Numbering Plan Feature

This feature identifies and classifies numbers dialled in the North American numbering plan (NANP).

Details

Feature name

NorthAmericanNumberingPlan

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite features

VerticalServiceCode

Session State inputs and outputs

Inputs

Name Type Description Behaviour if null/invalid

AnalysedDialledNumber

com.opencloud.sentinel.numbers.TaggedNumber

Has analysis of the dialled number.

Feature ends immediately.

AnalysedHomeCountryCode

String

The home country dialling code for the network.

Feature will be unable to identify a NANP number dialled without the country code.

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

For selecting area code configuration data.

Feature will be unable to get geographic information from the area code of a NANP number.

Outputs

Name Type Description

NANPNumberInfo

com.opencloud.sentinel.numbers.NANPNumberInfo

Contains the results of the feature’s analysis.

Behaviour

The NANP feature analyses the number dialled by the calling party, and has three tasks while doing so:

  1. Determine if the number is in the North American numbering plan.

  2. If so, identify the format of the number (i.e. 7 digit, 10 digit, or 1+10 digit).

  3. Extract the NANP area code for the number (if it is present) and retrieve geographic information for it.

In order to determine if the number is part of the North American numbering plan, the feature examines the analysed version of the dialled number as provided by the Vertical Service Code feature in the AnalysedDialledNumber session state field. The number will be considered part of the NANP if it meets any one of the following three criteria:

  • It was dialled with the network’s international escape code, and has 1 as the country code.

  • It was dialled in international format (i.e. starting with a + character), and has 1 as the country code.

  • The number does not have a country code, and the home network county code is 1.

If the number is in the NANP, the feature will move on to identify its format. For the purpose of checking number lengths in this stage in the analysis, any vertical service codes in the dialled number will be skipped over. Formats are classified in the following ways:

  • For numbers in international format or with an international escape code, the number is checked to make sure there are 10 digits after the country code. If so the format is classified as 10 digit, and if not the format is left unclassified.

  • For numbers that start with the national dialling prefix the same check is applied for the length of the number after the prefix. However, when the national prefix is 1 and there are 10 digits after the prefix, the number will be classified as 1+10 digit format rather than 10 digit.

  • For numbers lacking national or international prefixes, the length of the whole number is checked and if its seven or ten digits it will be classified accordingly. For other lengths, the number is left unclassified.

If the number was classified as 10 digit or 1+10 digit, the feature will extract the area code from the number. This area code will be looked up in the NorthAmericanNumberingPlanAreaCodes profile table, which has geographic information for each area code.

The feature will output the results of its analysis to the NANPNumberInfo session state field. This session state field contains a data structure with the following fields:

Field Name Description

Number

The part of the originally dialled number that is actually in the NANP (i.e. without service codes, dial prefixes, country codes etc.).

Format

The format of the number, one of: 7-Digit, 10-Digit, 1+10-Digit, or Unknown.

Area Code

The area code that was extracted from the number.

Country Name

The full name of the country that the area code is in.

ISO Country code

The two-letter ISO standard country code for the country that the area code is in.

Location

A more specific description of the location the area code is in. For the US, this will be the two-letter code for the state/territory. For Canada, this will be the full name of the province/territory. For other countries, this will be the same as the Country Name.

If no area code or geographic information was found, those fields will be empty. If no dialled number was found, or the dialled number was not in the NANP, then the entire session state field will be left null.

Relationship with number translation features

The NANP feature analyses the dialled number as it was originally received by Sentinel.

This means that if a number translation feature such as Location Based Dialling or SIP Short Code modifies the number and the resulting number is part of the NANP, it will not be analysed by the NANP feature.

Classification Examples

Number Format Area Code Notes

+14255550000

10 Digit

425

  • The number starts with the NANP country code (+1), which is excluded from the number when identifying the format.

  • This number would be identified as a NANP number regardless of what country it was dialled from.

18795550000

1+10 Digit

879

  • The number starts with the NANP national prefix (1), which is included in the number when identifying the format.

  • This number would only be identified as a NANP number if dialled from within the NANP.

7415550000

10 Digit

741

  • This number would only be identified as a NANP number if dialled from within the NANP.

5550000

7 Digit

None

  • No geographic information would be retrieved as it does not have an area code.

  • This number would only be identified as a NANP number if dialled from within the NANP.

Error scenarios

Scenario Handling

VSC feature number analysis not available

Record stat, report to SAS, and end feature normally.

Configuration

This feature’s behaviour is not configurable, however geographic data for the NANP area codes is. This data is stored in the NorthAmericanNumberingPlanAreaCodes profile table. The table is pre-populated with area code information from the North American Numbering Plan Authority, and is updated with each major release of Sentinel. Each profile on the table is scoped by Sentinel Selection Key and corresponds to a single area code.

Each profile has the following fields:

Field Name Type Description

Area Code

String

The area code.

Country Name

String

The full name of the country that the area code is in.

ISO Country code

String

The two-letter ISO standard country code (in upper case) for the country that the area code is in.

Location

String

A more specific description of the location the area code is in. For the US, this will be the two-letter code for the state/territory. For Canada, this will be the full name of the province/territory. For other countries, this will be the same as the Country Name.

Profile example:

Profile Name

Metaswitch:::::415

Area Code

415

Country Name

United States

ISO Country code

US

Location

CA

Provisioning interfaces

Area code data can be provisioned using the Sentinel web interface.

Statistics

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

Name Type Description 
Started

Counter

Incremented when the feature is triggered.

 
FailedToStart

Counter

Incremented when the feature fails to start.

 
FailedDuringExecution

Counter

Incremented when the feature fails while executing.

 
IssuedWarning

Counter

Incremented when the feature issues a warning.

 
TimedOut

Counter

Incremented when the feature times out during execution.

 
DialledNumberNotFound

Counter

Incremented when the dialled number analysis from the Vertical Service Code feature is not available in session state.

 
DialledNumberOutsideNANP

Counter

Incremented when the dialled number is not within the NANP.

 
DialledNumberInsideNANP

Counter

Incremented when the dialled number is within the NANP.

 
AreaCodeNotFound

Counter

Incremented when the dialled number is withn the NANP, but does not have an area code.

 
FoundAreaCodeInfo

Counter

Incremented when the geographic information for the area code is found.

 
AreaCodeInfoNotFound

Counter

Incremented when no geographic information is found for an area code.

Reauthorize Credit Feature

Description

Feature name

ReauthorizeCredit

Applicable contexts

SIP service

SAS Support

No

Prerequisite Features

None

Sentinel feature to notify the Sentinel Core to reauthorize credit post initial credit check. Used post-announcement where the rating may have changed due to the length of the announcement.

Sets the ReauthorizeCreditAfterInitialCreditCheck session state field to true.

Session state inputs and outputs

Inputs

This feature does not read session state.

Outputs

Name Type Format Description

ReauthorizeCreditAfterInitialCreditCheck

boolean

true

Notify the sentinel core to reauthorize credit post initial credit check.

Error scenarios

This feature always succeeds.

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

This feature cannot be configured.

SIP Determine Network Operator Feature

Description

Feature name

SIPDetermineNetworkOperator

Applicable contexts

SIP service

SAS Support

No

Prerequisite Features

None

The SIP Determine Network Operator Feature sets the network operator element of the Sentinel selection key for use in the selection of: feature execution scripts, mappers, and address lists.

The feature will set the Network Operator element of the Sentinel selection key, based on the value returned by the DetermineNetworkOperator function below. This feature requires that the calling party SIP INVITE contains a ‘sentinel-network-operator’ header. If this header is not present, then the platform-configured default network operator is used.

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

calledParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip javadoc

INVITE sent to the called party

Runtime exception handled by feature runner

callingParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip javadoc

INVITE received from the calling party

Runtime exception handled by feature runner

SIP headers

Inputs

Name Format Description Behaviour if absent

sentinel-network-operator

String

Header indicating which network operator to select use

Use default network operator.

Session state

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data and updating network operator field

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>:<network>:::)

Only updated if network operator is determined

Error scenarios

Scenario Handling

No calling party available

Report featureCannotStart (invalid session state)

No called party available

Report featureCannotStart (invalid session state)

Sessionstate SentinelSelectionKey is null

Report featureCannotStart (invalid session state)

“sentinel-network-operator” SIP header present but empty

Increment CouldNotDetermineNetworkOperator, continue executing.

No “sentinel-network-operator” header, and default network operator could not be determined

Report featureFailedToExecute (invalid configuration)

Feature responses

Response Reason

featureCannotStart

Missing called or calling party, missing SentinelSelectionKey, “sentinel-network-operator” SIP header present but empty, or SessionState SentinelSelectionKey is not set.

featureHasFinished

Feature has finished

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SentinelConfigurationTable

Sentinel configuration table (contains DefaultNetworkOperator)

SentinelConfiguration

SIP Mid Session Play Announcement Feature

The SipMidCallPlayAnnouncement feature plays a queue of announcements to the configured party during mid session.

Details

Feature script name

SipMidCallPlayAnnouncement

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite Features

Any feature setting the MidCallAnnouncementInfoQueue session state field and any feature that sets the LanguageConfig session state field, like Sip Set Language Feature feature.

Typical feature execution points

SipAccess_ServiceTimer, SipAccess_PartyResponse, SipMidSession_PartyRequest, SipMidSession_PartyResponse, and any other mid-session execution point where an announcement may be desired, such as SipMidSession_CreditLimitReached.

Timer usage

Execution-point targeted timer will trigger the feature at the SipAccess_ServiceTimer execution point on expiry.

Behaviour

The announcements are played by the MRF. The announcements to play are queued in the MidCallAnnouncementInfoQueue session state as SipAnnouncementInformation objects each with an announcement ID. The announcement may have an associated language otherwise the LanguageConfig session variable is used. If the MidCallAnnouncementInfoQueue is empty or null then the MidCallAnnouncementID session variable is used. If the MidCallAnnouncementID session variable is not set, the MidCallAnnouncementQueue is checked. If the MidCallAnnouncementQueue is empty or null then the feature returns without error or side effect to the dialog.

Another feature must be executed prior to the SipMidCallPlayAnnouncement feature to set the LanguageConfig and the MidcallAnnouncementId or queue.

All announcements which are played by the feature are appended to the PlayedAnnouncementIDs session state variable. This list of announcements is used by the standard CDR mappers and may be used in custom CDR mappers.

The LanguageConfig String is a language code in RFC 3066 format. Use of the LanguageConfig session state field is optional. The feature will search for a profile using the LanguageConfig and MidcallAnnouncementId as keys. If the feature can’t find a profile for the specified language, it will search for a profile just using the MidcallAnnouncementId.

If there are multiple announcements scheduled in the MidCallAnnouncementInfoQueue, each announcement will be attempted on a new MRF dialog when each previous announcement completes (whether or not it played successfully). Each subsequent announcement necessitates sending another Re-INVITE to the calling party. If the MRF times out at any point, the MRF session will be torn down appropriately and the call will proceed as normal including queued announcements (or be ended, as in the above scenario).

Passive Party Media

The feature supports multiple options for how the passive party’s media streams should be handled while the announcement is playing to the active party. The option to use is specified per-announcement on the SipAnnouncementInformation object by whatever queued the announcement. There are three possibilities, they are:

  • NO_HOLD: The passive party is not put on hold during the announcement, media streams are left as they were.

  • BLACK_HOLE_ONLY: SDP is renegotiated with the passive party so that for the duration of the announcement, all media streams are directed to a black hole IP.

  • FULL_HOLD: SDP is renegotiated with the passive party so that for the duration of the announcement, all media streams are directed to a black hole IP; and additionally the passive party is put on hold by setting the stream status to sendonly or inactive. This is the default.

Call flows

Mid-call low-credit announcement

In this scenario, a feature installed in SipAccess_CreditAllocatedPostCC analyzes the CCA-U and determines that the charged party has low credit. The feature script then runs the MidCallPlayAnnouncement feature. Points of interest are highlighted and explained below the diagram.

mid call play low credit announcement

Request from PlayedParty arrives while waiting for answer to PassiveParty hold INVITE

In this scenario, the PlayedParty sends an INVITE or an UPDATE while Sentinel is waiting for the PassiveParty to respond to the hold INVITE. The request is rejected and the announcement is set up as normal.

request from playedparty arrives waiting answer to passiveparty hold invite

PassiveParty does not accept being put on hold

The feature will simply end the announcement and allow the session to continue.

passiveparty does not accept being put on hold

MRS unresponsive after initial provisional response

When the INVITE request is sent to MRS, Sentinel receives a provisional 100 Trying response which cancels the SIP-Stack-internal request timeout timer; however, no further response is received. Sentinel fires its own ‘noResponse’ timer which ultimately times out. The PlayAnnouncement feature handles the timer event (the feature must be installed in the SipAccess_ServiceTimer execution point) and sends a CANCEL to MRS. The leg is subsequently released. The PAShouldEndSessionWhenFinished session state field indicates whether the feature should send endSession to the core or not. The call may continue afterwards.

mrs unresponsive after initial provisional response

Resume call during announcement

For this call flow to work, the Interruptable flag is set to true in the announcement configuration. This tells the feature that the announcement can be stopped by either the call being resumed by the passive party for hold cases, or the call ended if the passive party was to end it with a BYE. A call is put on hold with a long-running announcement. When the holding party resumes the call, a feature detects the resume request and sets the RequestIsResume session state field. When the announcement feature runs and sees this, as well as the interruptable flag, it will stop the announcement and re-connect the two parties for the call to proceed.

mid call announcement interrupted

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

callingParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip Javadoc

INVITE received from (and respectively, in the NetworkInitiated case, sent to) the calling party

Runtime exception handled by feature runner

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

Selection key (for example, <platform>::::)

For selecting configuration data

Increment InputParameterErrors
Common cleanup actions

SDP

String

Text

Session description

Outgoing request will not contain SDP

LanguageConfig

String

An optional String input containing a language code. The RFC 3066 defines language codes, but the feature does not validate the format.

The value of this fields will be used to get the proper announcement profile. Default is null.

If null the profile search will not consider the language

MidCallAnnouncementInfoQueue

List<SipAnnouncementInformation>

List of SipAnnouncementInformation

List of announcements to play

Check for MidcallAnnouncementId

MidcallAnnouncementId

Integer

Non-negative

ID of the announcement to be played — 0 indicates no announcement to play Increment InvalidAnnouncementIDs (deprecated)

Check the announcement queue

MidCallAnnouncementQueue

List<Integer>

Non-negative

ID of the announcements to be played (deprecated)

Report featureHasFinished

PlayedAnnouncementIDs

int[]

List of announcement IDs

Announcements which have already been played

Initialized to an empty array

PAShouldEndSessionWhenFinished

boolean

Indicates whether the feature will call endSession when finished playing all announcements (deprecated)

Default is false

 

MidCallEndSessionWithAnnouncement

boolean

Indicates whether the feature will call endSession when finished playing all announcements (replaces PAShouldEndSessionWhenFinished)

Default is false

 

MidCallAnnouncementPlayedParty

String

Leg name indicating which party the announcement will be played to

Linked leg will be passivated during announcement (deprecated)

Play to callingParty

RequestIsResume

boolean

Indicates whether the current request is a resume. Set by other features to be read by this one.

Default is false

Outputs

Name Type Format Description

MidCallAnnouncementInProgress

SipAnnouncementInformation

The announcement currently in progress, null if no announcement is in progress.

PlayedAnnouncementIDs

int[]

List of announcement IDs

Updated with each announcement ID the feature is invoked to play

PAShouldEndSessionWhenFinished

boolean

Set to true if the feature is invoked in the CreditLimitReached execution point. Can be cleared by a subsequent feature

Error scenarios

Scenario Handling

Null sessionstate MidcallAnnouncementId

Increment MissingAnnouncementIDs
Finish

MidcallAnnouncementId session state field is ⇐ 0

Increment InvalidAnnouncementIDs
Finish

Null sessionstate SentinelSelectionKey

Increment InputParameterErrors
Common cleanup actions

ACI not provided to the announcement feature

Increment InputParameterErrors
Common cleanup actions

SipSession object not provided to the announcement feature in the activity context interface

Increment InputParameterErrors
Common cleanup actions

Announcement properties not found for announcement ID

Increment InputParameterErrors
Common cleanup actions

Announcement resource config not found for resource config ID

Increment ConfigurationErrors
Common cleanup actions

Failed to send INVITE to Media Server

Increment SipSendErrors
Common cleanup actions

Error received from MRF on Invite

Send Ack with Rejection to played party
Increment SipErrors
Re-invite passive party to resume call if leg not already released
Common cleanup actions

Error received from MRF on Cancel due to played party BYE

Increment SipErrors
Release passive party leg
Common cleanup actions

MediaServer response timeout to INVITE

Send Ack with Rejection to played party
Increment SipErrors
Send Cancel to MRF
Re-invite passive party to resume call if leg not already released
Common cleanup actions

MediaServer response timeout to Cancel

Increment SipErrors
Send Cancel to MRF
Release passive party leg
Common cleanup actions

Failed to send 200 Prack response

Increment SipSendErrors
Report end Session with 500 ServerError to Sip Sentinel core

Failed to send ACK to MRF

Increment SipSendErrors
Common cleanup actions

Failed to send BYE to MRF

Increment SipSendErrors
Common cleanup actions

Failed to send CANCEL to MRF

Common cleanup actions

Failed to send 183 response due to unable to access INVITE from SIPSession

Increment InputParameterErrors
Send ACK to MRF
Cancel NoResponseTimer
Send Bye to MRF
Common cleanup actions

Failed to send 183 response

Increment SipSendErrors
Cancel NoResponseTimer
Send Bye to MRF
Common cleanup actions

Common cleanup actions

Here are some common cleanup actions:

  • If a BYE was received from the played or passive party during the feature, release the other party as well as the MRF leg.

  • If both parties are still present, re-link the legs for B2BUA behaviour.

  • Cancel the NoResponseTimer.

  • Release the MRF Leg (may have been done already).

  • Increment FeatureFSMCompletions.

  • If the PAShouldEndSessionWhenFinished session state field is true, call endSession.

  • Finish.

Feature responses

Response Reason

featureHasFinished

feature has finished

Announcement configuration

Announcements are referenced by ID. The following table shows configuration parameters for provisioning them.

Parameter Type Description

Description

String

Description of the announcement

Id

String

Announcement id (number) plus optional language (eg. 20:en_NZ)

AnnouncementURL

String

URL of the announcement

Delay

Integer

Delay interval between announcement repetitions (in ms)

Duration

Integer

Maximum duration of the announcement (in ms)

Locale

String

Locale of the announcement as a string

MimeType

String

MimeType of the announcement as a string

Repeat

Integer

How many times the media server should repeat the announcement. (-1 means 'forever')

ResourceConfig

String

Name of the profile holding the media resource configuration

SuspendCharging

Boolean

True if charging is suspended during the announcement (only applies to Mid Call Announcements)

Interruptable

Boolean

True if the announcement is interruptable (only applies to Mid Call Announcements)

EnforceOneWayMedia

Boolean

True if media should be unidirectional from the MRF to the played party for the announcement. The feature will modify SDP directionality attributes between the MRF and played party to do this. (only applies to Mid Call Announcements)

Example

Here is an example announcement table configuration:

ID Description AnnouncementURL Delay Duration Locale MimeType Repeat ResourceConfig SuspendCharging Interruptable EnforceOneWayMedia

15

Play message "You have insufficient credit to make this call"

file:msg_15.wav

0

4000

en

audio/vnd.wave

0

default

true

false

false

17

Play tone

file://cts71/annc/CallWaitingReactive.wav

500

100

audio/vnd.wave

2

default

false

false

false

The ResourceConfig is a reference by ResourceId to an entry in the Resource Configuration table with the resource configuration.

Resource configuration

Parameter Type Description

ResourceId

String

ID of this resource configuration
Used by the announcement configuration profile to reference this configuration

MediaServerURI

String

The configured value for the media server URI

RouteDirectToResource

Boolean

The configured value for the route direct to resource
If true, the service sends the Play Announcement INVITE directly to the media server (using Request URI) (values: true or false)

ServiceParameterType

String

The configured value for the service parameter type (for example, play, voicexml)

NoResponseTimeout

Long

The configured number of milliseconds that Sentinel will wait for the MRF to send a response to the INVITE or CANCEL

ICSCFURI

String

The configured value for the I-CSCF URI which is used put in the ROUTE header if RouteDirectToResource is false

Example

Here is an example resource configuration profile:

ResourceId MediaServerURI RouteDirectToResource ServiceParameterType NoResponseTimeout ICSCFURI default

sip:annc-audio@localhost:5260;lr;transport=tcp

true

play

1000

icscfhost:5054

voice

sip:dialog@mediaserver:5061;lr;transport=udp

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SipAnnouncementProfileTable

Announcement configuration profiles

SentinelSelectionKey:id
(for example, OpenCloud::::15)

SipAnnouncementProfileTable

Announcement configuration profiles

SentinelSelectionKey:id:language
(for example, OpenCloud::::15:en-NZ)

SipAnnouncementResourceConfigProfileTable

Announcement resource addresses and other resource configuration data

SentinelSelectionKey:resourceConfigName
(for example, OpenCloud::::voice)

SIP Normalization Feature

Description

Feature script name

SipNormalization

Applicable contexts

SIP service session

SAS Support

Yes

Prerequisite Features

SipPrefixAndSuffixAnalysis — where required

The SIP Normalization feature normalizes the request-URI and other select address headers in the received INVITE request.

The SipNormalization uses the Normalization Component to normalize:

  • request URI

  • From address

  • To address

  • P-Asserted-Id address (if present)

  • P-Served-User address (if present).

Note

The SipNormalization feature will only do analysis of an address if:

  • the address is a tel URL

  • the address is a SIP URI, where the user part of the URI is a digit string.

Addresses may contain the digits allowed in a global phone number as per RFC 2806.

URI Phone Context Parameter

If a local tel or SIP URI containing a phone-context parameter is normalised to an internationally formatted number the phone-context parameter will be removed from the updated URI as part of normalisation.

Leg Manager Inputs

Leg

Name

Type

Format

Description

Behaviour if null/invalid

calledParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip Javadoc

INVITE sent to the called party

Runtime exception handled by feature runner
Note

The Called Party INVITE request is fetched from the called party leg via the LegManager API.

The Called Party INVITE request is updated via the LegManager API.

Session state and leg inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

Selection key (for example, <platform>::::)

For configuring normalizer

Runtime exception handled by feature runner

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call

Report featureCannotStart, featureHasFinished

Error scenarios

Scenario Handling

Sessionstate selection key is null

Report featureCannotStart

Error during number normalization

Report featureFailedToExecute

Feature responses

Response Reason

featureCannotStart

Sessionstate selection key is null

featureFailedToExecute

Error during number normalization

featureHasFinished

feature has finished

Configuration

See Normalization Component.

Configuration profile naming

See Normalization Component.

Provisioning interfaces

See Normalization Component.

SIP Play Announcement Feature

The SipPlayAnnouncement feature plays a queue of announcements to the calling party during call establishment.

Description

Feature script name

SipPlayAnnouncement

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite features

Any feature setting the EarlyMediaAnnouncementInfoQueue session state field and any feature that sets the LanguageConfig session state field, like Sip Set Language Feature feature.

Typical feature execution points

SipAccess_PartyResponse, SipAccess_PartyRequest, SipMidSession_PartyResponse, SipMidSession_PartyRequest, SipAccess_ServiceTimer, and any SipAccess execution points where an announcement may be triggered, such as SipAccess_SubscriberCheck.

Timer usage

Execution-point targeted timer will trigger the feature at the SipAccess_ServiceTimer execution point on expiry.

The announcement is played by the MRF. The announcements to play are queued in the EarlyMediaAnnouncementInfoQueue session state as SipAnnouncementInformation objects each with an announcement ID. The announcement may have an associated language otherwise the LanguageConfig session variable is used. If the EarlyMediaAnnouncementInfoQueue is empty or null then the AnnouncementID session variable is used. If the AnnouncementID session variable is not set, the EarlyMediaAnnouncementQueue is checked. If the EarlyMediaAnnouncementQueue is empty or null then the feature returns without error or side effect to the dialog.

Another feature must be executed prior to the SipPlayAnnouncement feature to set the EarlyMediaAnnouncementInfoQueue and the LanguageConfig.

All announcements which are played by the feature are appended to the PlayedAnnouncementIDs session state variable. This list of announcements is used by the standard CDR mappers and may be used in custom CDR mappers.

The LanguageConfig String is a language code in RFC 3066 format. Use of the LanguageConfig session state field is optional. The feature will search for a profile using the LanguageConfig and AnnouncementID as keys. If the feature can’t find a profile for the specified language, it will search for a profile just using the AnnouncementID as key.

The SipPlayAnnouncement feature supports UE preconditions if present.

Example Callflows

Play Announcement without Preconditions - OCS Rejects Call

In this scenario, the CCA-I returns with result code 4012 (credit limit reached); and a feature setting the EndSessionAfterAnnouncement session state field to a non-zero value is installed in the SipAccess_CreditLimitReached execution point and runs before PlayAnnouncement, which is also installed in the same execution point. B-Party is never contacted.

sip play announcement feature

The MRF dialog is similar for other types of pre-call announcements, including successful calls.

If the A-Party cancels at any point, the MRF SIP dialog will be torn down appropriately. If there are multiple announcements scheduled (eg the AnnouncementID field has been set as well as at least one entry in the queue, or simply multiple entries in the queue), each announcement will be attempted on a new MRF dialog when each previous announcement completes (whether or not it played successfully). Each subsequent announcement necessitates sending another 183 to the calling party, which will be translated to an UPDATE as needed by the Sequential Forked SDP Mediation feature. If the MRF times out at any point, the MRF session will be torn down appropriately and the call will proceed as normal including queued announcements (or be ended, as in the above scenario).

Early media play announcement with preconditions and VoWiFi

In this scenario, the caller has resources available as the bearer is WiFi, so there is no value in resource reservation from the caller’s perspective.

Preconditions are in use in case the terminating party does not have resources available at INVITE time. However in this call flow the terminating party is the MRF which does have resources available.

wifi early media announce barred

The initial INVITE from the UE will contain these media attributes related to QoS.

a=sendrecv
a=curr:qos local sendrecv
a=curr:qos remote none
a=des:qos mandatory local sendrecv
a=des:qos none remote sendrecv

The 183 from the TAS towards the UE will not contain a conf line like this

a=conf:qos remote sendrecv

If in the initial INVITE the UE includes P-Early-Media: supported then the TAS must insert the P-Early-Media: sendrecv header in the 183 response.

This is because some devices includes a P-Early-Media: supported header in the initial INVITE and some MRFs do not include it in the 183 response. Some devices will not play early media unless they receive the P-Early-Media header in the 183 response.

Early media play announcement with preconditions and VoLTE

This case differs from the WiFi case as LTE allows the use of radio resource reservation.

Therefore the INVITE from A indicates that the current state is inactive.

The MRF already has resources available.

volte early media announce barred

The initial INVITE from the UE will contain these media attributes related to QoS.

a=inactive
a=curr:qos local none
a=curr:qos remote none
a=des:qos mandatory local sendrecv
a=des:qos none remote sendrecv

The 183 from the MRF will contain a conf line like this, instructing A to UPDATE when its resources are available

a=conf:qos remote sendrecv

If in the initial INVITE the UE includes P-Early-Media: supported then the TAS must insert the P-Early-Media: sendrecv header in the 183 response sent upstream. This is because some devices include a P-Early-Media: supported header in the initial INVITE and some MRFs do not include it in the 183 response. Some devices will not play early media unless they receive the P-Early-Media header in the 183 response.

Early media play announcement with preconditions not on MRF

In this scenario, the MRF does not support preconditions.

The call case is a Barring Announcement UE with preconditions supported, resources not initially available.

early media announce barred mrf not support preconditions

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

callingParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip javadoc

INVITE received from (respectively, in the NetworkInitiated case, sent to) the calling party

Runtime exception handled by feature runner

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>:::: )

For selecting configuration data

Increment InputParameterErrors Common cleanup actions

SDP

String

Text

Session description

Outgoing request will not contain SDP

EarlyMediaAnnouncementInfoQueue

SipAnnouncementInfo

non-negative

A list of announcements to be played in order. Each announcement specifies an ID and optionally a language to use.

Check the AnnouncementID and EarlyMediaAnnouncementQueue for further announcements to play.

AnnouncementID

Integer

non-negative

ID of the announcement to be played — 0, negative values and null indicate no announcement to play

Poll the EarlyMediaAnnouncementQueue

EarlyMediaAnnouncementQueue

List<Integer>

A list of positive integers

A list of IDs of the subsequent announcements to be played — entries such as 0, null or negative values will be ignored. The AnnouncementID field takes priority over the queue. The element at index 0 will always be treated as the head of the queue. (deprecated)

If the queue itself is null, report featureHasFinished. If one of the entries is null or invalid, increment InvalidAnnouncementIDs and play the next one in the queue.

PlayedAnnouncementIDs

int[]

List of announcement IDs

Announcements which have already been played

Initialized to an empty array

EndSessionAfterAnnouncement

int

The feature will call endSession with the provided error code upon completion if non-zero

Default value is 0 — does not end session

LanguageConfig

String

The RFC 3066 defines language formats, but the feature does not validates the format.

The feature will use the LanguageConfig supplied by the session state field as an input and use it to retrieve the proper announcement profile.

The default value is null, a null value runs the default profile without language configuration.

Outputs

Name Type Format Description

PlayedAnnouncementIDs

int[]

List of announcement IDs

Updated with each announcement ID the feature is invoked to play

EarlyMediaAnnouncementInProgress

SipAnnouncementInformation

Object

Set to the current announcement in progress. Null if no announcement is in progress.

EarlyMediaAnnouncementIsPlaying

boolean

true/false

Set to true when there is an announcement in progress, and false if no announcement is in progress.

Error scenarios

Scenario Handling

Null, negative or 0 found in EarlyMediaAnnouncementQueue

Increment InvalidAnnouncementIDs + retrieve next entry

Null sessionstate SentinelSelectionKey

Increment InputParameterErrors
Common cleanup actions

ACI not provided to the announcement feature

Increment InputParameterErrors
Common cleanup actions

SipSession object not provided to the announcement feature in the activity context interface

Increment InputParameterErrors
Common cleanup actions

Announcement properties not found for announcement

Increment InputParameterErrors
Common cleanup actions

Announcement resource config not found for resource config ID

Increment ConfigurationErrors
Common cleanup actions

Failed to send INVITE to Media Server

Increment SipSendErrors
Common cleanup actions

Error received from MRF

Increment SipErrors
Common cleanup actions

MediaServer response timeout

Increment SipErrors
Common cleanup actions

Failed to send 200 Prack response

Increment SipSendErrors

Report end Session with 500

ServerError to SIP Sentinel core

Failed to send ACK to MRF

Increment SipSendErrors
Common cleanup actions

Failed to send BYE to MRF

Increment SipSendErrors
Common cleanup actions

Failed to send CANCEL to MRF

Common cleanup actions

Failed to send 183 response due to unable to access INVITE from SIPSession

Increment InputParameterErrors
Send ACK to MRF
Common cleanup actions

Failed to send 183 response

Increment SipSendErrors
Common cleanup actions

Common cleanup actions:

  • Cancel NoResponseTimer

  • Release MRF Leg

  • End session if End Session Flag is set or if announcement is configured with EndSessionOnFailure set to true

  • Increment FeatureFSMCompletions

  • Finish

Feature responses

Response Reason

featureHasFinished

feature has finished

Announcement configuration

Announcements are referenced by id and language code. The configuration of each announcement id is provisioned in the following table:

Parameter Type Description

Description

String

Description of the announcement

Id

String

Announcement id (number) plus optional language (eg. 20:en_NZ)

AnnouncementURL

String

URL of the Announcement

Delay

Integer

Delay interval between announcement repetitions (in ms)

Duration

Integer

Maximum duration of the announcement (in ms)

Locale

String

Locale of the Announcement as a string

MimeType

String

MimeType of the Announcement as a string

Repeat

Integer

How many times the media server should repeat the announcement. (-1 means 'forever')

ResourceConfig

String

Name of the profile hold the media resource configuration

SuspendCharging

Boolean

True if charging is suspended during the announcement. (Only applies to Mid Call Announcements)

Interruptable

Boolean

True if the announcement is interruptable. (Only applies to Mid Call Announcements)

EndSessionOnFailure

Boolean

True if the call should be ended if this announcement fails to play. (Only applies to Early Media Announcements)

EnforceOneWayMedia

Boolean

True if media should be unidirectional from the MRF to the played party for the announcement. The feature will modify SDP directionality attributes between the MRF and played party to do this. (only applies to Mid Call Announcements)

Example announcement table configuration:

ID Description AnnouncementURL Delay Duration Locale MimeType Repeat ResourceConfig SuspendCharging Interruptable EnforceOneWayMedia

15

Play message "You have insufficient credit to make this call"

file:msg_15.wav

0

4000

en

audio/vnd.wave

0

default

true

false

false

17

Play tone

file://cts71/annc/CallWaitingReactive.wav

500

100

audio/vnd.wave

2

default

false

false

false

The ResourceConfig is a reference by ResourceId to an entry in the Resource Configuration table with the resource configuration.

Resource configuration

Parameter Type Description

ResourceId

String

Id of this resource configuration. It is used by the announcement configuration profile to reference this configuration.

MediaServerURI

String

The configured value for the media server URI

RouteDirectToResource

Boolean

The configured value for the route direct to resource. If true, the service sends the Play Announcement INVITE directly to the media server (i.e. using Request URI) (values: true or false)

ServiceParameterType

String

The configured value for the service parameter type e.g. play, voicexml

NoResponseTimeout

Long

The configured number of milliseconds that Sentinel will wait for the MRF to send a response to the INVITE.

ICSCFURI

String

The configured value for the I-CSCF URI which is used put in the ROUTE header if RouteDirectToResource is false.

Example resource configuration profile:

ResourceId MediaServerURI RouteDirectToResource ServiceParameterType NoResponseTimeout ICSCFURI

default

sip:annc-audio@localhost:5260;lr;transport=tcp

true

play

1000

icscfhost:5054

voice

sip:dialog@mediaserver:5061;lr;transport=udp

true

voicexml

1000

icscfhost:5054

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SipAnnouncementProfileTable

Announcement configuration profiles

SentinelSelectionKey:id (for example, OpenCloud::::15)

SipAnnouncementProfileTable

Announcement configuration profiles

SentinelSelectionKey:id (for example, OpenCloud::::15:en-NZ)

SipAnnouncementResourceConfigProfileTable

Announcement resource addresses and other resource configuration data

SentinelSelectionKey:resourceConfigName (for example, OpenCloud::::voice)

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

SIP Prefix and Suffix Analysis Feature

Description

Feature name

SipPrefixAndSuffixAnalysis

Applicable contexts

SIP Service

SAS Support

No

Prerequisite features

Determine Call Type Feature

The SIP prefix and suffix analysis feature performs prefix and suffix digit analysis on the request-URI of the received INVITE request.

Note

The SipPrefixAndSuffixAnalysis feature will only do analysis if;

  • the request-URI is a tel URL

  • the request-URI is a SIP URI, where the user part of the URI is a digit string.

Addresses may contain the digits allowed in a global phone number as per RFC 2806.

Sentinel has a set of configurable prefix and suffix address lists, scoped by Sentinel selection key, which are used for this digit analysis.

  • If a prefix or suffix matches an address in the request-URI, then the directive associated with the prefix (or suffix) is applied.

    • The directives are: strip prefix/suffix or retain prefix/suffix, and set session parameter with configured value.

  • If the directive is strip, then the request-URI is updated in the outgoing INVITE.

Note

The SipPrefixAndSuffixAnalysis feature will not do any analysis if the CallType is EmergencyCall or MobileTerminating.

Subsequent features may make additional changes to the request URI, so the final address sent in the INVITE will be dependent on those features.
Parameter Description

Address

Prefix or suffix to match

Description

ListId

  • ${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialPrefixList

  • ${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialSuffixList

ParameterName

Session state field to set (for example, AnnouncementID). Field name is in Java identifier format, and follows the rules of Java identifiers (such as not being a Java keyword).

ParameterType

boolean, integer, long, string

ParameterValue

Value to write to session state. Must be formatted correctly for the value specified in the Parameter Type field

PrefixDirective

strip, retain

Example of prefix analysis configuration:

Prefix/suffix address Directive Session Parameter Parameter Type Parameter Value Description

1234

STRIP

CLI

String

SUPPRESS

555

STRIP

TARIFF

String

Cheap-International-Calling

*591

STRIP

PROFILE

Integer

1

Profile selection

*592

STRIP

PROFILE

Integer

2

Profile selection

*593

STRIP

PROFILE

Integer

3

Profile selection

*594

STRIP

PROFILE

Integer

4

Profile selection

.

STRIP

Strip ST (end of pulsing) digit
Note Prefixes and suffixes may contain the digits allowed in a global phone number as per RFC 2806.

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

calledParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip javadoc

INVITE sent to the called party

Runtime exception handled by feature runner
Note

The Called Party INVITE request is fetched from the called party Leg via the LegManager API.

The Called Party INVITE request is updated via the LegManager API.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call for determining whether to analyse the INVITE

Report featureCannotStart, featureHasFinished

Outputs

Name Type Format Description

Other session state fields

see Description

see Description

This feature can update other session state fields according to configuration data when a prefix or suffix match is found

Error scenarios

Scenario Handling

Sessionstate SentinelSelectionKey is null

Report featureCannotStart

Attempt to set non-existent SessionState parameter

Report featureFailedToExecute

Feature responses

Response Reason

featureCannotStart

SessionState SentinelSelectionKey is not set

featureFailedToExecute

Attempt to set non-existent SessionState parameter

featureHasFinished

feature has finished

Configuration

Prefix and Suffix Analysis uses Sentinel AddressLists for configuration data. See Address Lists on how to provide the configuration data.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_PrefixAndSuffixAnalysisFeature_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialPrefixList or ${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialSuffixList

${PLATFORMOPERATOR}_PrefixAndSuffixAnalysisFeature_AddressListEntryTable

Feature specific Address List entry table

${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialPrefixList:${ADDRESS} or ${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialSuffixList:${ADDRESS}
Note The SipPrefixAndSuffixAnalysis feature address list configuration uses the same profile tables as the SS7 version of the feature. The names of the address lists are, however, particular to the SipPrefixAndSuffixAnalysis feature.

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

SIP Short Code Feature

Description

Feature name

SipShortCode

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite features

Classify Call Scenario Feature

The Short Code feature is a pre-credit check feature that performs number translation of short-codes in the request-URI of the received INVITE request. If the request-URI does include a short-code, then SipShortCode updates the request-URI and To addresses in the received INVITE, using a short-code translation table.

Note

The SipShortCode feature will only do analysis if:

  • the request-URI is a tel URL

  • the request-URI is a SIP URI, where the user part of the URI is a digit string.

Addresses may contain the digits allowed in a global phone number as per RFC 2806.

If the number is in international format and is prefixed by the home country code then the prefix will be removed before performing analysis. The feature makes use of the Normalization Component to remove the prefix.

If the number is in international format and is not prefixed by the home country code then no analysis will be performed.

Sentinel has a configurable short-code address list, scoped by the Sentinel selection key, which is used for this digit analysis. If a short-code matches an address in the request-URI, then both the request-URI and the To address are updated with a translated address (that corresponds to the short-code).

Note

The SipShortCode feature will not do any analysis if the CallType is EmergencyCall or MobileTerminating.

Subsequent features may make additional changes to the request URI, so the final address sent in the INVITE will be dependent on those features.

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

calledParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See the EasySIP javadoc

INVITE sent to the called party

Runtime exception handled by feature runner
Tip

The Called Party INVITE request is fetched from the called party Leg via the LegManager API.

The Called Party INVITE request is updated via the LegManager API.

Session State and Leg inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call

Throw runtime exception, report featureHasFinished

Error scenarios

Scenario Handling

Sessionstate SentinelSelectionKey is null

Report featureCannotStart

Called Party Leg is null

Throw runtime exception Report featureHasFinished

Called Party Invite Request is null

Throw runtime exception Report featureHasFinished

Sessionstate CallType is null

Throw runtime exception Report featureHasFinished

Feature responses

Response Reason

featureCannotStart

SessionState SentinelSelectionKey is not set

featureHasFinished

feature has finished

Configuration

Short Code feature configuration

Parameters Type Description

MinLength

Integer

Minimum short code length

MaxLength

Integer

Maximum short code length

Example configuration:

MinLength MaxLength

3

3

Short Code address list configuration

The SipShortCode address list entry is an extension of the standard Address list entry, the addition being the ‘translatedAddress’ field which is used for number translation:

Parameter Type Description

…​

…​

…​

TranslatedAddress

String

the value of the short code translated address (in international format)

Example configuration:

Address TranslatedAddress

100

6422987654

200

6422123456

The SipShortCode address is a digit string which can contain any digits valid for the network.

TranslatedAddress is a digit string in international format.

The short code list applies to all subscribers scoped to Sentinel selection key.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

ShortCodeFeatureConfigProfileTable

Short code feature configuration

SentinelSelectionKey (for example, OpenCloud::::)

${PLATFORMOPERATOR}_SipShortCode_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:SipShortCode:SipShortCodeAddressList

${PLATFORMOPERATOR}_SipShortCode_AddressListEntryTable

Feature specific Address List entry table

${SELECTIONKEY}:SipShortCode:SipShortCodeAddressList:${ADDRESS}
Note The SipShortCode feature address list configuration uses the same profile tables as the SS7 version of the feature. The names of the address lists are, however, particular to the SipShortCode feature.

Normalization Configuration

See Normalization Component.

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

Statistics

Name Description

ShortCodeTranslated

Counter incremented when a short code is translated.

InternationalNumberIgnored

Counter incremented when a number is ignored as it is international and not prefixed by the home country code.

StrippedHomeCountryCode

Counter incremented when the home country code prefix is removed from a number before attempting analysis.

SIP Subscriber Determination Feature

Description

Feature name

SubscriberDetermination

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

DetermineCallType

The Subscriber Determination feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature inspects the SIP INVITE to determine the subscriber address for this session and set the Subscriber session state field.

It determines the subscriber address either by:

  • returning the value already stored in the Subscriber session state field; otherwise

  • returning the value of the P-Served-User header (if that header is present); otherwise

  • analysing the FROM or RequestURI headers, depending on the call type:

    • moc: subscriber address is the URI in the FROM header

    • mtc: subscriber address is the URI in the RequestURI header

    • networkinitiated: subscriber address is the URI in the FROM header

The feature will string the parameters from the URIs in case some is present.

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

calledParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See EasySIP javadoc

The invite to be sent to the called party

Runtime exception handled by feature runner

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call

Subscriber will not be determined unless it can be determined from PServedUserHeader

Subscriber

String

SIP URI

Check the subscriber is not already set before proceeding

Subscriber determination will take place

Outputs

Name Type Format Description

Subscriber

String

SIP URI

The subscriber address

Error scenarios

Scenario Handling

Called Party leg Invite Request is null or does not contain Subscriber address

Report featureFailedToExecute

Feature responses

Response Reason

featureFailedToExecute

Invalid subscriber, if the feature was unable to determine any sensible subscriber address in any of the above ways

featureHasFinished

feature has finished

Configuration

This feature cannot be configured.

SIP Third Party Call Setup Feature

The SIP Third Party Call Setup feature manages the actual call setup and SDP negotiation

Details

Feature name

SipThirdPartyCallSetup

Applicable contexts

SIP service

SAS Support

No

Typical feature execution points

SipThirdPartyAccess_SubscriberCheck, SipAccess_CreditAllocatedPostCC, SipAccess_ControlNotRequiredPostCC, SipAccess_PartyRequest, SipAccess_PartyResponse, SipAccess_ServiceTimer, SubscriptionSipRequest, SipMidSession_PartyResponse

Prerequisite Features

SIP Third Party HTTP Trigger Feature

Timer usage

Execution-point targeted timer will trigger the feature at the SipAccess_ServiceTimer execution point on expiry.

The SIP Third Party Call Setup feature:

  1. First unlinks the legs created by SIP Third Party HTTP Trigger Feature.

  2. Starts to set up the call.

  3. The setup begins with A party negotiation.

  4. When it receives a positive answer from the A party, the feature start negotiation with the B party, using the SDP received from the A party.

  5. The call will be established if a positive answer was received from the B party.
    Otherwise the call setup fails.

Note The SIP Third Party Call Setup feature can also be used to provide Third Party Call Control (3pcc) functionality for other services.

Example call flows

Sentinel starts a call setup on valid HTTP requests from the SIP Third Party HTTP Trigger Feature. Below are examples of these call flows: successful; and A party busy, B party busy, and A party disconnects before B party answers failures.

Successful call setup flow

This call flow represents a successful call setup. The B party accepts the SDP offer. Sentinel sends an ACK message to the A party with the SDP answer received from the B party.

sip third party call setup success

A party busy failure flow

This flow represents a case where the A party is busy.

sip third party call setup a busy

B party busy failure flow

This flow represents a case where the B party is busy.

sip third party call setup b busy

A party disconnects before B party answers failure flow

This flow represents a case where the A party disconnects before the B party answers.

sip third party call setup a disconnects

Session state inputs and outputs

Inputs

Name Type Format Description

APartyLegName

String

Text

A party leg name

BPartyLegName

String

Text

B party leg name

PreserveSessionOnAPartyFailureResponse

boolean

true or false

Determines if the feature should end or preserve the SIP session if the A Party responds with a failure response.

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key
for example: <platform>::::

For selecting configuration data

Outputs

Name Type Format Description

CallEstablished

Boolean

true or false

Sets true if the session has been established.

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

See under SIP Third Party Call Configuration. The only parameter used by this feature is NoAnswerApplicationTimer.

Statistics

Name Description

FailedToSetupCall

Counter incremented when failed to setup the call.

CallEstablished

Counter incrremented when successfully setup the call.

SIP Third Party HTTP Trigger Feature

THe SIP Third Party HTTP Trigger feature processes an HTTP request, creates the A and B party legs, and maps the HTTP request to SIP INVITE messages.

Details

Feature name

SipThirdPartyHttpTrigger

Applicable contexts

SIP service

SAS Support

No

Prerequisite Features

N/A

Typical feature execution points

SipThirdPartyAccess_SessionAccept, SipThirdPartyAccess_SubscriberCheck, SipAccess_CreditAllocatedPostCC, SipAccess_ControlNotRequiredPostCC, SipEndSession

Processing HTTP requests

The SIP Service accepts HTTP requests in the following format:

http://<host>:<port>/sentinel-sip?subscriber=447408800855&cgpn=642200001&cdpn=642200002

The feature checks for presence of the subscriber, cgpn, and cdpn request parameters. If all parameters are available, the feature creates the suspended legs with the initial INVITE messages, according to the parameters from the HTTP request and feature configuration. The legs after creation are suspended and linked.

If the feature is being used in an uncharged scenario, it should run in the SipThirdPartyAccess_SubscriberCheck script in order to trigger the sending of an HTTP 200 (callIsBeingSetup) response without waiting for a CCA. In a charged scenario, it should not run in SipThirdPartyAccess_SubscriberCheck, to ensure that it waits for a success CCA before sending the response. See Configuration for an example of configuring the script to cover both cases.

Example Call Flows

Successful flow

This call flow shows a case when Sentinel receives valid HTTP request. Sentinel responds with 200 OK with callIsBeingSetup in the message body.

sip third party http trigger

Invalid HTTP request

This call flow shows a case when Sentinel receives invalid HTTP request. The request is invalid if any of required HTTP request parameters subscriber, cgpn or cdpn is missing. Sentinel responds with 200 OK with callSetupFailed in the message body.

sip third party http trigger invalid

Session state inputs and outputs

Outputs

Name Type Format Description

CallType

com.opencloud.sentinel.common.CallType

NetworkInitiated

Call type of this call

SessionType

com.opencloud.sentinel.common.SessionType

http_trigger

Session type of this call

APartyLegName

String

AParty

A party leg name created by the feature

BPartyLegName

String

BParty

B party leg name created by the feature

HttpAci

javax.slee.ActivityContextInterface

ACI on which the HTTP request was received, and which will be used to send the response

Error scenarios

Scenario Handling

Missing any of required HTTP request parameters: subscriber, cgpn, cdpn

Sends HTTP 200OK response with the callSetupFailed as the content

Error on leg creation

Sends HTTP 200OK response with the callSetupFailed as the content

On CreditLimitReached or OCSFailure

Sends HTTP 200OK response with the callRefused as the content

Mappers

This feature uses three mappers:

  • The first two are used to map HTTP requests to outgoing SipRequests, as determined by the mapper execution point. The default implementations are HttpRequestToCallingPartySipRequest:

    // a mapper that takes a {{HttpRequest}} and generates a {{SipRequest}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
        getSessionState().getSentinelSelectionKey(),
        HttpRequest.class,
        SipRequest.class,
        SipMappingPoint.CallingPartySipRequest
        );

    and HttpRequestToCalledPartySipRequest:

    // a mapper that takes a {{HttpRequest}} and generates a {{SipRequest}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
        getSessionState().getSentinelSelectionKey(),
        HttpRequest.class,
        SipRequest.class,
        SipMappingPoint.CalledPartySipRequest
        );

  • The third mapper maps a SipThirdPartyCallOutcomes to a HTTP response The default implementation is SdpDiffToSdpCcrDiffMapper:

    // a mapper that takes a {{SipThirdPartyCallOutcomes}} and generates a {{HttpResponse}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
    getSessionState().getSentinelSelectionKey(),
    SipThirdPartyCallOutcomes.class,
    HttpResponse.class,
    mappingPoint);

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

To support both charged and uncharged calls, the SipThirdPartyAccess_SubscriberCheck script should be configured as follows:

featurescript SipThirdPartyAccessSubscriberCheck {
    ...
    if not session.MonitorCallOnly { run SipThirdPartyCharging }
    else { run SipThirdPartyHttpTrigger run SipThirdPartyCallSetup }
    ...
}

The configuration for mapping HTTP request to the SIP INVITE message is available under SIP Third Party Call Configuration. The parameters used by the feature are:

  • ExpiresHeader

  • MaxForwardsHeader

  • RouteHeaderURI

  • SupportedHeader

  • UserAgentHeader

  • Transport

  • IsSipURIUsed

  • SipURIDomain

Statistics

Statistic Incremented when…​

APartyLegCreated

A party leg is created

BPartyLegCreated

B party leg is created

LegsLinked

legs have been linked

Send Failure End Session Feature

The Send Failure End Session feature is an instruction execution failure feature.

The feature instructs LegManager.endSession(403) if the triggering instruction failure was a sendMessage. This will result in any outstanding requests receiving a 403 response.

Details

Feature name

SendFailureEndSession

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None

Typical feature execution point

SipInstructionExecutionFailure

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

Send Failure End Session cannot be configured.

Sip Proxy and Do Not Record Route Feature

Description

Feature name

SipProxyAndDoNotRecordRoute

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite Features

N/A

The Sip Proxy And Do Not Record Route feature calls the leg manager instruction proxyAndDoNotRecordRoute on the leg associated with an initial SIP request.

Session input and output variables

Sip Proxy and Do Not Record Route does not define any session state.

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

Sip Proxy and Do Not Record Route cannot be configured.

Statistics

Name Description

InvokedProxyAndDoNotRecordRouteForRequest

Counter incremented when a request is proxied.

Sip Set Language Feature

The Sip Set Language feature is used to set the language used on play announcements. It sets the session state field LanguageConfig to the value present in the profile.

Details

Feature name

SipSetLanguage

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

None

Typical feature execution point

SipAccess_PartyResponse, SipAccess_PartyRequest, SipMidSession_PartyResponse, SipMidSession_PartyRequest, SipAccess_ServiceTimer, and any SipAccess execution points where an announcement may be triggered, such as SipAccess_SubscriberCheck.

Configuration

Parameters

Description

LanguageConfig

a string containing the language. The recommendation is to use the RFC 3066 as format (for example, en-UK), but the feature does validate the format.

Configuration feature naming

Configuration Profile Table Name Description Profile Naming

SipSetLanguageProfileTable

Sentinel configuration table

SentinelSelectionKey (for example, OpenCloud::::)

Outputs

Name

Type

Format

Description

LanguageConfig

Session state field

String

The language string, for example en-UK.

Sip Third Party Charging Feature

The SIP Third Party Charging feature creates the SCUR charging instance, maps initial SIP INVITE message to a session counter address, and makes the credit reservation.

The SIP INVITE message used is the message created by the SIP Third Party HTTP Trigger Feature from the incoming HTTP request.

Since the SIP Third Party Charging feature only creates the charging instance and makes credit reservation, the rest of the charging process must be handled by the B2BUA SCUR Features.

Details

Feature name

SipThirdPartyCharging

Applicable contexts

SIP service

SAS Support

No

Prerequisite features

SIP Third Party HTTP Trigger Feature

Related features

B2BUA SCUR Features

Typical feature execution points

SipThirdPartyAccess_SubscriberCheck

Feature responses

Response Reason

featureHasFinished

feature has finished

Session State inputs and outputs

Outputs

Name Type Format Description

B2BUAChargingCounterAddress

com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress

Session counter address

Session counter address mapped from the initial INVITE message

Mappers

This feature uses a mapper to convert the SIP request to a SessionCounterAddress. The default implementation is SipRequestToSessionCounterAddress:

// a mapper that takes a {{SipRequest}} and generates a {{SessionCounterAddress}}.
final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
        getSessionState().getSentinelSelectionKey(),
        SipRequest.class,
        SessionCounterAddress.class,
        mappingPoint);

Configuration

The feature is not configurable.

Subscription Expiry Feature

The Subscription Expiry Feature ensures that subscriptions end when they expire and Sentinel is acting as the subscription server (endpoint).

The feature monitors the active subscriptions by inspecting the outgoing NOTIFY messages, and sets a timer based on the Subscription-State.expires parameter. If any of the timers associated with the Subscription Expiry feature expire, then leg.endSubscription is used to end the associated subscription. The subscription timers will be cancelled when the subscription has ended (SIP NOTIFY message with subscription-state terminated or leg/session ended).

Details

Feature name

SubscriptionExpiry

Applicable contexts

SIP service

SAS Support

No

Prerequisite Features

None

Typical feature execution points

SubscriptionSipRequest
SipEndSession
SipLegEnd

Timer usage

Feature-targeted timer triggers feature directly on expiry. Does not need to be registered against SipAccess_ServiceTimer execution point

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

All

NotifyRequest

org.jainslee.resources.sip.OutgoingSipRequest

See Easysip javadoc

NOTIFY sent to the subscribing party

N/A

SIP headers

Inputs

Name Format Description Behaviour if absent

Subscription-State

String

Header indicating state of subscription

N/A

Feature responses

Response Reason

featureHasFinished

Feature has finished

Unconditional Reject Session Feature

Description

Feature name

UnconditionalRejectSession

Applicable contexts

Diameter Mediation Service

SAS Support

No

Prerequisite Features

None

Sentinel feature which unconditionally rejects a session with SIP response of SC_FORBIDDEN. Used primarily in a vanilla install of sentinel that has yet to be configured. I.e a plain install of sentinel will reject all sessions it receives.

Session state inputs and outputs

This feature does not read from or write to session state.

Error scenarios

This feature always succeeds.

Feature responses

Response Reason

refuseSession

intended behaviour

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Vertical Service Code Feature

This feature analyses the dialled number to identify its components, and modifies the session as required to give effect to service codes it finds in the process.

Details

Feature name

VerticalServiceCode

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite features

None

Session State inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

N/A

Outputs

Name Type Description

AnalysedHomeCountryCode

String

The home country code as configured in the normalizer.

AnalysedDialledNumber

TaggedNumber

The original dialled number with its components tagged.

OriginalRequestUri

String

The Request URI before any modification by the feature.

SentinelSelectionKey

SentinelSelectionKey

When a matched Action changes the Plan ID.

EarlyMediaAnnouncementInfoQueue

List<SipAnnouncementInformation>

When a matched Action has an announcement ID

<any>

Integer, Long, Boolean, (and their primitives), String, and any Enum type.

Constant value specified in the Action for the service code, converted as specified in the Action and in consideration of the type of the session state field.

<any>

String

The service code prefix, or the dialled suffix to that service code may be stored into the String session state field specified in the Action for the service code.

Behaviour

The feature has two functions. One is to identify and set up behaviour for service codes. The other is to identify parts of the number that are relevant to normalization.

For service codes, both prefix and full dial string matching is supported. Possible modifications to the session include:

  • Strip the matched service code from the Request URI and To header

  • End the session with a specific response code

  • Set up session state to play a specific announcement

  • Change the session plan

  • Store a specified value, the matched service code or the dial string suffix to a specified session state field.

For normalization related analysis, the feature will identify any of the following components within the number:

  • The international escape code

  • The international format indicator (i.e. "+").

  • The national dialling prefix

  • The home network dialling prefix

  • The home country dialling code.

In most cases, the feature only looks for normalization components in the part of the number that’s left after service codes have been identified. The exception to this is the international format indicator followed by the home country code (e.g. +64 for New Zealand), this will be identified anywhere that it appears within the number. Also note that if the feature finds the international format indicator followed by a foreign country code, it will stop looking for further service codes and will not attempt to identify normalization components.

The feature will output the results of its analysis as a tagged number in the AnalysedDialledNumber session state field. A tagged number is a data structure that breaks down a number into labelled components. It can be used by other features to simplify their own number analysis or manipulation procedures.

Service code matching

The feature first extracts the dialled digit String from the Request URI. If no digits can be found the feature finishes.

If the request URI is a tel: URL with phone-context parameter of geo-local then the feature skips service code matching.

The feature then attempts to match the remaining dial string first against the FullNumber, and failing that against the Prefix AddressLists.

If a match is found …​

  • The Action profile whose name is specified in the matched AddressList Entry is loaded.

  • The actions specified in the Action profile and AddressList entry are performed as described below in [Performing Actions].

  • If the match is a prefix match and the action’s AllowAdditionalPrefixes is true, matching is repeated against the remainder of the dial string.

If any matched actions have StripMatch set to true then the Request URI, and To: header are updated to reflect that.

Performing service code actions

Play announcement

If the AddressListEntry’s AnnouncementID is > 0 it is added to the SessionState’s EarlyMediaAnnouncementInfoQueue without chargeForAnnouncement or a specified Language.

End the session with a specific response code

If the Action’s EndSessionResponseCode is > 0 it is used to terminate the session after any queued announcements have played or immediately if no announcements are queued.

Change the session plan

If the Action’s PlanId is a non empty string, it is set into the SentinelSelectionKey. This PlanID will be used from the next ExecutionPoint.

Set a specified session state field to a specified value

If the Action’s SessionStateFieldName is the name of an actual SesionState field …​

  • if the Action’s SessionStateDataSource is set to SERVICE_CODE_VALUE and the SessionState field is a String field, the matched code is set in that field.

  • if the Action’s SessionStateDataSource is set to SUFFIX and the SessionState field is a String field, the dial string following the prefix code is set in that field. This may include other service codes that have yet to be processed.

  • if the Action’s SessionStateDataSource is set to CONSTANT then

    • The Action’s ValueForConstantDataSource is attempted to be converted according to the Action’s TypeForConstantDataSource.

    • If conversion is successful, the converted value is attempted to be assigned to the SessionState field.

Any failures to find the session state field, or convert or assign a value will generate SAS events, trace logs and the feature reports featureFailedToExecute.

Service code precedence

If multiple matched AddressList Entries request an announcement, then all such announcements will be queued in the order they are matched.

If multiple matched service code Actions specify an EndSessionResponseCode the last one matched applies.

If multiple matched service code Actions set the same SessionState field, the last matched one applies.

If multiple matched service code Actions change the session plan, the last matched one applies.

Number Tagging Examples

As the feature analyses a number it tags each part and outputs the results to AnalysedDialledNumber session state field.

The following table gives examples for how a number will be tagged based on the following configuration:

  • Home Country Code: 64

  • International Escape Code: 00

  • National Dialling Prefix: 0

  • Home Network Dialling Code: 55

  • Prefix Service Codes: *67, *800

  • Full Number Service Codes: 200

Dialled Number Tags

+6455123456

  • INTERNATIONAL_FORMAT_INDICATOR (+)

  • HOME_COUNTRY_CODE (64)

  • HOME_NETWORK_DIALLING_CODE (55)

  • NO_TAG (123456)

+6312345678

  • INTERNATIONAL_FORMAT_INDICATOR (+)

  • NO_TAG (6312345678)

006412345678

  • INTERNATIONAL_ESCAPE_CODE (00)

  • HOME_COUNTRY_CODE (64)

  • NO_TAG (12345678)

055123456

  • NATIONAL_PREFIX (0)

  • HOME_NETWORK_DIALLING_CODE (55)

  • NO_TAG (123456)

+64*6755123456

  • INTERNATIONAL_FORMAT_INDICATOR (+)

  • HOME_COUNTRY_CODE (64)

  • SERVICE_CODE (*67)

  • HOME_NETWORK_DIALLING_CODE (55)

  • NO_TAG (123456)

*67055123456

  • SERVICE_CODE (*67)

  • NATIONAL_PREFIX (0)

  • HOME_NETWORK_DIALLING_CODE (55)

  • NO_TAG (123456)

+64200

  • INTERNATIONAL_FORMAT_INDICATOR (+)

  • HOME_COUNTRY_CODE (64)

  • SERVICE_CODE (200)

*8000064123456

  • SERVICE_CODE (*800)

  • INTERNATIONAL_ESCAPE_CODE (00)

  • HOME_COUNTRY_CODE (64)

  • NO_TAG (123456)

12345678

  • NO_TAG (12345678)

Error scenarios

Scenario Handling

Calling Party Leg is null

Throw runtime exception Report featureHasFinished

Leg manager is null

Report featureFailedToExecute

Cannot load Full or Prefix Address List

Report featureFailedToExecute

Invite Request is null

Report featureFailedToExecute

Trigger is not a SIP Request

Report featureFailedToExecute

AddressListEntry specifies an action but the Action profile cannot be found

Report featureFailedToExecute

Missing Normalizer home country code configuration

Report featureFailedToExecute

All digits have been stripped by service code actions

Report featureFailedToExecute

Unable to convert valueForConstantDatasource value to the specified type when assigning to a session state field

Reports featureFailedToExecute with specifics in Tracing and SAS event

Unable to assign a value to specified session state field,

  • Session State field does not exist

  • Specified conversion type is incompatible with field’s actual type

  • Assigning null to a primitive field

  • ValueForConstantDataSource is not a valid enum value for the enum field.

Reports featureFailedToExecute with specifics in Tracing and SAS event

Configuration

Configuration is split between address lists and profile tables. The address lists contain data that needs to be configured by an operator, such as choosing specific service codes for supplied actions and setting which announcement (if any) is appropriate to that action.

The profile table contains data related to how Sentinel or another feature should be triggered to perform certain service code actions. Any new features which have functionality that could usefully be triggered by service codes should supply their own entries in the profile table.

Vertical Service Code address list configuration

The feature uses an AddressListCollection VerticalServiceCode with lists named Prefix and FullNumber for matching prefix and full number service codes respectively.

They are extensions of the standard Address list entry and both have the same structure with the following additional fields.

Parameter Type Description

…​

…​

…​

Action

String

The name of a Vertical Service Code Actions profile to be applied when this service code is found. REM provides a list to select from.

AnnouncementID

Integer

ID of an announcement to be played when this service code is found, set to 0 to disable announcements. REM provides a list to select from.

Example configuration:

Address Action AnnouncementID

*87

MMTel_OIR_ID_Restriction_Current_Session_Disable

0

*63

MMTel_CDIV_Disable

20

The service code lists apply to all subscribers scoped to Sentinel selection key.

Vertical Service Code Actions profile table configuration

Standard and customised actions are stored in a profile table VerticalServiceCodeActions. The table maps an Action name to the actions to perform. The Action name is the result of looking up the dialstring in the Prefix or FullNumber VerticalServiceCode address lists.

Parameter Type Description

actionID

String

The name of this profile without the Sentinel Selection key prefix.

displayName

String

Used by REM to allow the user editing the address lists to choose this Action.

stripMatch

Boolean

If true the matching prefix should be stripped from the Request URI and To: headers. Set to false for the FullNumber addressList otherwise there will be no digits in the request URI and the call will fail.

allowAdditionalPrefixes

Boolean

If true, further matching will be attempted on the remaining dial string. Not applicable to the FullNumber addressslist as that consumes the whole dialled digit string and there is nothing further to match against.

endSessionResponseCode

Integer

If set to a valid SIP error response code, this action will end the session with that response code. Set to 0 when the action should not end the session.

planID

String

This plan ID will be set on the Sentinel selection key when this service code action is performed. Leave unset or empty to not change the service plan.

sessionStateFieldName

String

The name of a session state field to set when this service code action is performed. Leave unset or empty to not set any field.

sessionStateDataSource

String

Determines where to get the value from to set in the session state field, must be one of: 'SUFFIX', 'SERVICE_CODE_VALUE', or 'CONSTANT'.

valueForConstantDatasource

String

The value to put in the session state field if the Session State Data Source is CONSTANT. Will be parsed as specified by sessionStateFieldType.

sessionStateFieldType

String

The type of conversion to apply to valueForConstantDatasource, must be one of: 'INTEGER', 'BOOLEAN', 'LONG', 'STRING' or 'ENUM'. Only applicable when sessionStateDataSource is CONSTANT. Must correspond to the type of the session state field or the assignment will fail.

Example configuration: ${platform.operator.name}:::::MMTel_OIR_ID_Restriction_Current_Session_Disable

Parameter Value

actionID

'MMTel_OIR_ID_Restriction_Current_Session_Disable'

displayName

'MMTel OIR - Disable Identity Restriction For Current Session'

stripMatch

true

allowAdditionalPrefixes

true

endSessionResponseCode

0

planID

''

sessionStateFieldName

'DialledCallerIDRestriction'

sessionStateDataSource

'CONSTANT'

sessionStateFieldType

'ENUM'

valueForConstantDatasource

'OIR_CALLER_ID_UNBLOCK'

Normalization Configuration

The normalizer configuration is used for identifying normalization related components in the number. See Normalization Component.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_VerticalServiceCode_AddressListConfigurationTable

Address list configuration

${PLATFORMOPERATOR}:::::VerticalServiceCode:FullNumber: ${PLATFORMOPERATOR}:::::VerticalServiceCode:Prefix:

${PLATFORMOPERATOR}_VerticalServiceCode_AddressListEntryTable

Feature specific Address List entry table

${PLATFORMOPERATOR}:::::VerticalServiceCode:FullNumber:${ADDRESS} ${PLATFORMOPERATOR}:::::VerticalServiceCode:Prefix:${ADDRESS}

${PLATFORMOPERATOR}_VerticalServiceCodeActionsTable

Actions

${PLATFORMOPERATOR}:::::VerticalServiceCode:${ACTION_NAME}

Provisioning interfaces

The feature is provisioned using the Sentinel web interface.

Statistics

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

Name Type Description 
Started

Counter

Incremented when the feature is triggered.

 
FailedToStart

Counter

Incremented when the feature fails to start.

 
FailedDuringExecution

Counter

Incremented when the feature fails while executing.

 
IssuedWarning

Counter

Incremented when the feature issues a warning.

 
TimedOut

Counter

Incremented when the feature times out during execution.

 
RequestUriIsGeoLocal

Counter

Incremented when the feature does not proceed because the Request URI is geolocal.

 
DialledNumberOutsideHomeCountry

Counter

Incremented when the feature does not proceed because the dialled number is international and outside the home country.

 
NoDialStringInRequestUri

Counter

Incremented when the feature does not proceed because no dial string can be found.

 
FoundDialStringToAnalyse

Counter

Incremented when the feature finds a dial string to analyse.

 
FoundPrefixServiceCode

Counter

Incremented when the feature finds an entry in the prefix address list matching the dial string.

 
FoundFullNumberServiceCode

Counter

Incremented when the feature finds an entry in the full number address list matching the dial string.

 
NoServiceCodesFound

Counter

Incremented when the feature finds no service codes in the dial string.

 
SessionStateFieldSet

Counter

Incremented when an Action sets a session state field.

 
PlanIdSet

Counter

Incremented when an Action changes the session plan.

 
AnnouncementQueued

Counter

Incremented when an Action queues an announcement.

 
PreparedToEndSession

Counter

Incremented when an Action schedules the session to end.

 
ServiceCodeStrippedFromRequestUri

Counter

Incremented when an Action strips a matched service code from RequestURI.

 
EndSessionInstructed

Counter

Incremented when the feature ends the session.

 
UpdatedUris

Counter

Incremented when the feature updates the Request URI, and the To: header.

 
FailedToUpdateUris

Counter

Incremented when the feature is unable to update the URIs.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/diameter-service-features/index.adoc

:here: sentinel-components/features/diameter-service-features/ :idprefix: diameter-service-features

:leveloffset: 1

= Diameter Service Features :indexpage: :sortorder: 6

Sentinel includes many features for Diameter networks:

==== * Accept Diameter Mediation Session Feature  — Sets the Sentinel selection key session type to ‘diametermediation’ * Diameter Determine Network Operator Feature  — Sets the Network Operator element of the Sentinel selection key based on the value returned by the DetermineNetworkOperator function * Diameter Subscriber Determination Feature  — Used to determine the subscriber address based on AVPs in the CreditControlRequest(INITIAL) * Diameter Unconditional Reject Session Feature  — Unconditionally rejects a Diameter session. ====

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/diameter-service-features/accept-diameter-mediation-session-feature.adoc

:here: sentinel-components/features/diameter-service-features/ :idprefix: accept-diameter-mediation-session-feature

:leveloffset: 1

= Accept Diameter Mediation Session Feature

== Description

[cols="h,<" width="50"]

|Feature name |AcceptDiameterMediationSession |Applicable contexts |Diameter Service |SAS Support | No |Prerequisite features |None

Sets the Sentinel selection key session type to diametermediation.

== Session state inputs and outputs

=== Inputs

[cols="5*" options="header"]

|Name |Type |Format |Description |Behaviour if null/invalid

|SentinelSelectionKey |com.opencloud.sentinel.common.SentinelSelectionKey |selection key (for example, <platform>:<network>:::) |To be updated with the session type for this session |Runtime exception handled by feature runner

=== Outputs

[cols="4*" options="header"]

|Name |Type |Format |Description

|SessionType |com.opencloud.sentinel.common.SessionType |diametermediation |Session type of SessionType.diametermediation

|SentinelSelectionKey |com.opencloud.sentinel.common.SentinelSelectionKey |selection key (for example, <platform>:<network>:diametermediation::) |Updated selection key including session type determined from application context

== Error scenarios

This feature always succeeds.

== Feature responses

[width="40"]

|Response |Reason

|featureHasFinished |feature has finished

== Configuration

This feature is not configurable.

== Provisioning interfaces

This feature has no provisioning interfaces.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/diameter-service-features/diameter-determine-network-operator-feature.adoc

:here: sentinel-components/features/diameter-service-features/ :idprefix: diameter-determine-network-operator-feature

:leveloffset: 1

= Diameter Determine Network Operator Feature

== Description

[cols="h,<" width="55"]

|Feature name |DiameterDetermineNetworkOperator |Applicable contexts |Diameter Service |SAS Support | No |Prerequisite Features |None

The Diameter Service’s Determine Network Operator Feature sets the network operator element of the Sentinel selection key for use in the selection of feature execution scripts, mappers and address lists.

The feature will set the Network Operator element of the Sentinel selection key based on the value returned by the DetermineNetworkOperator function below.

Determine Network Operator feature uses the 3GPP-IMSI-MCC-MNC of the initial CCR to determine the network operator. It uses a map of (3GPP-IMSI-MCC-MNC → network operator). If no mapping can be found, then a default network operator is returned.

[quote, From 3gpp TS 32.299, which references 3gpp TS 29.061] 3GPP-IMSI-MCC-MNC : MCC and MNC extracted from the user’s IMSI (first 5 or 6 digits, as applicable from the presented IMSI).

== Session state inputs and outputs

=== Inputs

[cols="5*" options="header"]

|Name |Type |Format |Description |Behaviour if null/invalid

|SentinelSelectionKey |com.opencloud.sentinel.common.SentinelSelectionKey |selection key e.g <platform>:::: |To be updated with network operator determined from triggering initial CCR |Runtime exception to be handled by feature runner

=== Outputs

[cols="4*" options="header"]

|Name |Type |Format |Description

|SentinelSelectionKey |com.opencloud.sentinel.common.SentinelSelectionKey |selection key e.g <platform>:<network>::: |Updated with network operator determined from triggering initial CCR

== Error scenarios

[cols="3,4" width="80"]

|Scenario |Handling

|Trigger not CreditControlRequest |Report featureCannotStart |Cannot map 3GPP-IMSI-MCC-MNC to a network operator and no default is available |Increment CouldNotDetermineNetworkOperator
Report featureFailedToExecute

== Feature responses

[cols="1,3" width="85"]

|Response |Reason

|featureCannotStart |Trigger event must be CreditControlRequest |featureFailedToExecute |Cannot map 3GPP-IMSI-MCC-MNC to a network operator and no default is available |featureHasFinished |feature has finished

== Configuration

IMSI-MCC-MNC to network operator mapping table:

[cols="1,1,3" width="75"]

|Parameter |Type |Description

|Address |GT Address |The ImsiMccMnc address (for example: 00101) |NetworkOperator |String |The Network Operator to set (for example: MVNO1)

The default is stored in the Sentinel configuration table.

Example table:

[cols="1,2" width="30"]

|Address |NetworkOperator

|00101 |OpenCloud |00102 |MVNO1

== Configuration profile naming

[cols="2,2,1"]

|Configuration Profile Table Name |Description |Profile Naming

|SentinelImsiMccMncToNetworkOperatorProfileTable |IMSI MCC MNC to network operator mapping table |ImsiMccMnc address

== Provisioning interfaces

The feature is provisioned using the web interface.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/diameter-service-features/diameter-subscriber-determination-feature.adoc

:here: sentinel-components/features/diameter-service-features/ :idprefix: diameter-subscriber-determination-feature

:leveloffset: 1

= Diameter Subscriber Determination Feature

== Description

[cols="h,<" width="45"]

|Feature name |SubscriberDetermination |Applicable contexts |Diameter Service |SAS Support | No |Prerequisite Features |None

The Subscriber Determination Feature is used to determine the subscriber address based on AVPs in the CreditControlRequest(INITIAL).

If the Subscriber session state field is not set, then the Subscriber Determination feature will set it based on value of creditControlRequest/SubscriptionId[0]/SubscriptionIdData.

NOTE: This feature will not change the Subscriber session state field if it is already set.

== Session state inputs and outputs

=== Inputs

[cols="5*" options="header"]

|Name |Type |Format |Description |Behaviour if null/invalid

|Subscriber |String |Arbitrary |Use existing value if set |Proceed with subscriber determination

|InitialCcr |org.jainslee.resources.diameter.ro.types.CreditControlRequest |Credit-Control-Request |Initial CCR which triggered this session |Unless subscriber was pre-determined, report featureFailedToExecute, featureHasFinished

=== Outputs

[cols="1,1,1,6" width="80"]

|Name |Type |Format |Description

|Subscriber |String |Arbitrary |Subscriber determined from initial CCR, unless already set

== Error scenarios

[cols="2,1" width="85"]

|Scenario |Handling

|Session state InitialCcr is null or does not contain a SubscriptionId AVP |Report featureFailedToExecute

== Feature responses

[cols="1,3" width="75"]

|Response |Reason

|featureFailedToExecute |Subscriber address determination failed. Flag invalid subscriber |featureHasFinished |feature has finished

== Configuration

This feature is not configurable.

== Configuration profile naming

This feature is not configurable.

== Provisioning interfaces

This feature has no provisioning interfaces.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/diameter-service-features/diameter-unconditional-reject-session-feature.adoc

:here: sentinel-components/features/diameter-service-features/ :idprefix: diameter-unconditional-reject-session-feature

:leveloffset: 1

= Diameter Unconditional Reject Session Feature

== Description

[cols="h,<" width="45"]

|Feature name |UnconditionalRejectSession |Applicable contexts |Diameter Service |SAS Support | No |Prerequisite Features |None

Unconditionally rejects a Diameter session. Used primarily in a vanilla install of Sentinel that has yet to be configured. (A plain install of Sentinel will reject all sessions it receives.)

Result code is set to DIAMETER_UNABLE_TO_COMPLY.

== Session state inputs and outputs

This feature does not read from or write to session state.

== Error scenarios

This feature always succeeds.

== Feature responses

[width="45"]

|Response |Reason

|respondDiameterBaseResult |intended behaviour |featureHasFinished feature |has finished

== Configuration

This feature is not configurable.

== Provisioning interfaces

This feature has no provisioning interfaces.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/test-features/index.adoc

:here: sentinel-components/features/test-features/ :idprefix: test-features

:leveloffset: 1

= Test Features :indexpage: :sortorder: 8

Sentinel includes features for testing purposes:

[cols="2*" options="header"]

|Feature |Description

|com.opencloud.sentinel.feature.common.test.TestNeverFinish |This feature starts (calls startFeature()) but does not finish (it never calls featureHasFinished()). It is intended for testing Sentinel feature timeout behaviour for incorrectly designed features

|com.opencloud.sentinel.feature.notification.TestSetNotificationMessage |This feature sets the “NotificationMessage” session state field to the string “notification”

|com.opencloud.sentinel.feature.initialtrigger.TestSetAnnouncementId |Test Set Announcement ID

|com.opencloud.sentinel.feature.initialtrigger.TestFailingFeature |This SS7 feature throws a RuntimeException when run

|com.opencloud.sentinel.feature.initialtrigger.TestFailingSs7CallbackFeature |This SS7 feature throws a RuntimeException on SS7 callbacks (e.g. SS7 aborts, disconnects, etc.)

|com.opencloud.sentinel.feature.initialtrigger.TestFollowOnCall |This SS7 feature will attempt a follow on call when run in the BPartyNotEstablished execution point. The new b-party address for the follow on call is set in the TestFollowOnCallSessionState.

|com.opencloud.sentinel.feature.initialtrigger.TestAVPToFCI |This SS7 feature will send a FurnishChargingInformation and (optionally) send a delimiter when run in the PostCreditCheck or BPartyNotEstablished_PostCC execution points. It will also accept the dialog if necessary to send the FCI.

|com.opencloud.sentinel.feature.enddialog.TestSetUserReleaseCause |This SS7 feature sets the “UserReleaseCause” session state field to Cause.CauseValue.CLASS1_INVALID_NUMBER_FORMAT (0x1c)

|com.opencloud.sentinel.feature.common.test.TestSetSessionState Test |bxref:test-set-session-state[Set Session State}

|com.opencloud.sentinel.feature.common.test.TestRouteHeaderConfiguration |This SIP feature randomly sets the “RouteHeaderURI” session state field to either “scscf1:5160” or “scscf2:5160”

IMPORTANT: These features are included for test purposes and may not be suitable for use in production environments.

NOTE: Some (or all) of these features may not be available in a given Sentinel release.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/test-features/test-set-announcement-id.adoc

:here: sentinel-components/features/test-features/ :idprefix: test-set-announcement-id

:leveloffset: 1

= Test Set Announcement ID

[cols="h,<" width="50"] == Description

[cols="h,<" width="45"]

|Feature name |TestSetAnnouncementID |Applicable contexts |SS7 service, SIP service |SAS Support | No |Prerequisite features |none

The Test Set Announcement ID feature sets the AnnouncementID session state field to a value based on the Subscriber session state field. The value used to populate the AnnouncementID field will be picked from the TestSetAnnouncementID/testPrefixesToPlayAnnouncement address list based on the Subscriber ID.

The default announcement ID set by this feature is 17, but several other values can be set based on the value looked up from the address list.

== Session state inputs and outputs

=== Inputs

[cols="5*" options="header"]

|Name |Type |Format |Description |Behaviour if null/invalid

|SentinelSelectionKey |com.opencloud.sentinel.common.SentinelSelectionKey |selection key (for example, <platform>::::) |For selecting configuration data |Report featureCannotStart, return

|Subscriber |String |N/A |Subscriber identifier |

=== Outputs

|Name |Type |Format |Description

|AnnouncementID |int |N/A |The Announcement ID to set

== Error scenarios

[width="50"]

|Scenario |Handling

|Null sentinel selection key |Report featureCannotStart |Missing address list |Report featureCannotStart |Missing address list prefixes |Report featureCannotStart

== Feature responses

[width="40"]

|Response |Reason

|featureHasFinished |feature has finished

== Configuration

The Test Set Announcement ID configuration requires an address list for configuration.

[width="40"]

|SchemaName |List Name

|TestSetAnnouncementId |testPrefixesToPlayAnnouncement

The announcement ID will be set based on the value looked up from the address list as follows:

[width="35"]

|Matched Address |Announcement ID

|34915 |15 |34916 |17 |34917 |17 |34918 |18 |34919 |19 |default |17

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/test-features/test-set-session-state.adoc

:here: sentinel-components/features/test-features/ :idprefix: test-set-session-state

:leveloffset: 1

= Test Set Session State

== Description

[cols="h,<" width="50"]

|Feature name |TestSetSessionState |Applicable contexts |SS7 service, SIP service |SAS Support | No |Prerequisite Features |none

The Test Set Session State feature allows setting session state fields to arbitrary values based on its configuration.

== Session state inputs and outputs

=== Outputs

One or more session state fields will be set to pre-configured values. Only specific field types can be set — see the configuration section below.

== Error scenarios

[width="50"]

|Scenario |Handling

|Missing configuration |Report featureCannotStart |Invalid configuration |Report featureCannotStart

== Feature responses

[width="40"]

|Response |Reason

|featureHasFinished |feature has finished

== Configuration

The Test Set Session State feature:

* is configured through the TestSetSessionStateConfigTable profile table * uses all configuration profiles found in this table

Each profile used represents configuration for a single session state field. The naming of the individual profiles does not matter.

Each profile has the following fields:

[cols="1,6"]

|Parameters |Description

|FieldName |The name of the field to set. (e.g. MySessionStateField) |FieldType |The type of the field to set. This must equal one of the valid types as listed in the table below. (e.g. java.lang.Integer) |FieldValue |The value to set the field to. (e.g. 7)

The feature supports the following session state field types:

* java.lang.String * java.lang.Integer * java.lang.Long * java.lang.Boolean

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/utility-components/index.adoc

:here: sentinel-components/utility-components/ :idprefix: utility-components

:leveloffset: 1

= Utility Components :indexpage: :sortorder: 3

Sentinel includes a number of utility software components that are used by features bundled with Sentinel and may also be used by new features added with the SDK. The utility components include:

==== * Normalization Component — The Sentinel Normalizer normalizes International, Unknown, National, or Subscriber NADI format addresses * Service Timer Provider — The ServiceTimerProvider API is used by features to raise feature-specific timers. * XPath Language Component — The Sentinel XPath component supports a subset of the XPath language, which supports Diameter messages in Sentinel. * CAP Charging Component --The Sentinel ChargingGTFormatter allows the generation of global titles for use in CAP charging requests. * PLMN ID Analyser Component  — The Sentinel PlmnIdAnalyser analyses PLMN IDs to determine if they are home PLMN IDs. ====

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/utility-components/cap-charging-component.adoc

:here: sentinel-components/utility-components/ :idprefix: include-cap-charging-component

:leveloffset: 1

= CAP Charging Component :page-id: include-cap-charging-component

== Description

[cols="h,a" width= "55"]

|Component name | ChargingGTFormatter |Applicable contexts | * VoLTE Service * IP-SM-GW Service |Features using component | * Cap Location Headers * MO Submission Location

The Sentinel ChargingGTFormatter allows the generation of global titles for use in CAP charging requests.

== Configuration

Configuration is stored on a profile table called CapChargingConfigProfileTable.

Data is scoped according to a Sentinel selection key.

[cols="2l,1,1,6" options="header"]

|Attribute Name |Type |Default |Description |ChargingGTFormatString |String |null |The format template to use when creating Charging GTs. It must be a digit string except for tokens ('{iso}', '{mcc}', '{mnc}) which are substituted in. |UnknownLocationChargingGT |String |null |The Charging GT to use when one could not be generated because the user’s location could not be determined.

== Session Input Variables

[cols="1,1,3a" options="header"]

|IsoCountryCode |String |The ISO country code that the subscriber is registered with. It is used for formatting the OC-Charging-GT header. |PaniMccMncs |List<MccMnc> |The MCCs and MNCs that the subscriber is registered with. They are used for formatting the OC-Charging-GT header.

== Behaviour

The ChargingGTFormatter allows the generation of global titles from the ChargingGTFormatString.

The ChargingGTFormatter will attempt replace any {iso} tokens in the ChargingGTFormat string with the ASCII digit values for the characters in the IsoCountryCode session state field. The IsoCountryCode should be upper case characters.

==== A ChargingGTFormatString of 555{iso}555 and IsoCountryCode of NZ would result in 5557890555. ====

The ChargingGTFormatter will attempt replace any {mcc} and {mnc} tokens in the ChargingGTFormat string with the MCC and MNC values from the first entry in the PaniMccMncs session state field.

==== A ChargingGTFormatString of 55{mcc}55{mnc}55 and first PaniMccMncs entry of mcc.123.mnc.456 would result in 551235545655. ====

If the ChargingGTFormatString contains any tokens other than {mcc}, {mnc}, or {iso} then the ChargingGTFormatter will do nothing and return null.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/utility-components/normalization-component.adoc

:here: sentinel-components/utility-components/ :idprefix: include-normalization-component

:leveloffset: 1

= Normalization Component :page-id: include-normalization-component

== Description

[cols="h,a" width= "55"]

|Component name | Normalizer |Applicable contexts | * SS7 Service * SIP Service * VoLTE Service * XCAP |Features using component | * (SS7) Normalization * (SS7) SMSNormalization * (SIP) SipNormalization * MMTelCDIV * MMTelICB * MMTelOCB

The Sentinel Normalizer normalizes International, Unknown, National, or Subscriber NADI format addresses into either:

* international address format — starting with CC + MNC * national format — starting with MNC

where MNC is specified in the NetworkDialingCode configuration setting.

The Sentinel Normalizer may decide to not normalize the address if the address is either:

* shorter than the MinNormalizableLength * an entry in the SkipNormalizationAddressList

This allows for short codes and specific longer length numbers to avoid normalization. The SkipNormalizationAddressList is a configurable address list scoped by the Sentinel selection key; it is only used by the SIP normalization component.

Normalization is invoked by the call type specific normalization features Voice Call Normalization Feature, SMS Normalization Feature and SIP Normalization Feature. It is also invoked by the XCAP Server to reject requests containing numbers which are not normalizable. Furthermore, MMTelCDIV, MMTelICB and MMTelOCB use the normalization component to normalize numbers in outgoing requests, and when comparing numbers.

[NOTE] ==== Support for formatting of special characters in SS7 signalling (such as: * → B, # → C) is provided by the SS7 Prefix and Suffix Analysis Feature.

Sentinel supports special character mapping only if they are prefixes or suffixes. ====

== Configuration

[cols="1,1,3"]

|Parameter |Type |Description

|NationalPrefix | String | National dialling prefix (for example, 0) |CountryCode | String | Country code |NetworkDialingCode | String | Network dialling code, used as the MNC |InternationalEscapeCode | String | Escape code for dialing international numbers (for example, 00) |NormalizeTo | String | Indicates the default format of Nature of Address Indication (NADI); one of: [international, national] |ProfileVersion | Integer | The current profile’s version (used for determining if reloading is required) |MinNormalizableLength | Integer | The minimum length of an address for it to be normalizable.

== Normalization address list configuration

The SkipNormalizationAddressList address list uses the standard Address list entry. Addresses that prefix match against entries in the list are not normalized.

[NOTE] ==== Using the 'SkipNormalizationAddressList' to avoid normalizing numbers is only supported by the (SIP) SipNormalization and the SCCCamelToIMSReOriginationSIPFeature in Sentinel-Volte. ====

== Configuration profile naming

|Configuration Profile Table Name |Description |Profile naming

|NormalizationFeatureConfigProfileTable |Normalization parameter configuration |SentinelSelectionKey (for example, OpenCloud::::)| |${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable |Address list configuration |${SELECTIONKEY}:Normalizer:SkipNormalizationAddressList |${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable |Feature specific Address List entry table |${SELECTIONKEY}:Normalizer:SkipNormalizationAddressList:${ADDRESS}

== Provisioning interfaces

The Normalizer component is provisioned using the Managing Normalization web interface.

== Behaviour

The Normalizer component normalizes addresses based on its configuration. Initially the address to normalize is checked for length against the MinNormalizableLength, and against the SkipNormalizationAddressList. If the address is under the MinNormalizableLength, or matches the prefix list, normalization is skipped.

Then the configuration of the component is checked to determine whether the address should be normalized to national or international format.

* If the number should be normalized to international format if the number is in national format, the configured CountryCode will be prepended to the address. if the number is in subscriber format, the CountryCode and the configured NetworkDialingCode will be prepended to the address. If the current format of the number is unknown, the format will be determined by checking against the configured InternationalEscapeCode and NationalPrefix, and then normalizing as appropriate. If neither of those prefixes match the address, it will be returned unchanged.

* If the number should be normalized to national format if the number is in international format, the length of the configured CountryCode will be removed from the start of the address. if the number is in subscriber format, the configured NetworkDialingCode will be prepended to the address. If the current format of the number is unknown, the format will be determined by checking against the configured InternationalEscapeCode and NationalPrefix, and then normalizing as appropriate. If neither of those prefixes match the address, it will be returned unchanged.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/utility-components/plmn-id-analyser-component.adoc

:here: sentinel-components/utility-components/ :idprefix: plmn-id-analyser-component

:leveloffset: 1

= PLMN ID Analyser Component :page-id: plmn-id-analyser-component

== Description

[cols="h,a" width= "55"]

|Component name | Normalizer |Applicable contexts | * SIP Service * VoLTE Service * IPSMGW |Features using component | * (SIP) Extract Network Info Feature * (VoLTE) Determine International and Roaming Status * (VoLTE) Conference Factory PSI Analyser * (VoLTE) DetermineRoamingFromHlr * (IP-SM-GW) IPSMGW Extract Network Info Feature * (IP-SM-GW) Generate MT Correlation Id

The Sentinel PLMN ID Analyser component analyses a PLMN ID (an MCC together with an MNC) to determine if it is a home PLMN ID for the network. In addition, if it is not a home PLMN ID, it can determine if the MCC is a home MCC for the network.

== Configuration

Configuration can be set up using the Sentinel SDK installers for VoLTE and IP-SM-GW or using the provisioning interface (see below). Configuration is stored in the HomePlmnIdConfigProfileTable SLEE profile table, with one profile for each MCC which is part of a home PLMN ID. [cols="1,1,3"]

|Parameter |Type |Description

|MCC |String |The mobile country code

|MNCs |String |List of home MNCs for this MCC

== Provisioning interfaces

The PLMN ID Analyser component is provisioned using the Provisioning Web Interface. Configuration can be found under Sentinel → Service Configuration → SIP Service Configuration (sip) → PLMN IDs.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/utility-components/servicetimerprovider.adoc

:here: sentinel-components/utility-components/ :idprefix: servicetimerprovider

:leveloffset: 1

= ServiceTimerProvider

== Description

[cols="h,<" width="50"]

|Component name |ServiceTimerProvider |Applicable contexts |SIP service |Features using component |CallDiversion

The ServiceTimerProvider API can be used by features to set feature specific timers and receive TimerEvents, when the timers fire.

NOTE: ServiceTimerProvider is currently only available in the Sentinel SIP frontend, but the concept eventually will be extended to the other cores.

See ServiceTimerProvider of the Sentinel Overview and Concepts Guide for usage and API documentation.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/utility-components/xpath-language-component.adoc

:here: sentinel-components/utility-components/ :idprefix: include-xpath-language-component

:leveloffset: 1

= XPath Language Component :page-id: include-xpath-language-component

== Description

[cols="h,a" width="60"]

|Component name |Sentinel-XPath |Applicable contexts | * SS7 service * Diameter Mediation Service |Features using component | * PlayAnnouncement * ScriptedPromotions

The Sentinel XPath component supports a subset of the XPath language, which supports Diameter messages in Sentinel.

It supports path expressions for querying Diameter messages. The path elements are Diameter AVPs with ‘-’ removed. For example, Multiple-Services-Credit-Control has path element MultipleServicesCreditControl.

NOTE: The elements are case sensitive.

== Examples

Query the Validity-Time AVP from the first Multiple-Services-Credit-Control AVP:

MultipleServicesCreditControl[1]/ValidityTime

Query the command-level Result-Code AVP:

ResultCode

Query the Subscription-Id AVP:

SubscriptionId

XPath predicates can be used to query specific AVPs where multiple AVPs of that type are permitted. For instance, multiple MultipleServicesCreditControl AVPs are permitted in CreditControlRequest and CreditControlAnswer.

To return the Result-Code AVP from the MultipleServiceCreditControl AVP with Rating-Group set to 1, use the following expression:

* MultipleServicesCreditControl[RatingGroup=1]/ResultCode

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/index.adoc

:here: sentinel-components/promotions/ :idprefix: promotions

:leveloffset: 1

= Promotions :indexpage: :sortorder: 4

This section covers:

==== * OCS failure handling promotions * Promotions buckets * Promotions commit used units feature * Promotions free reservations feature * Scripted promotions feature ====

TIP: For an overview of what promotions are and how they work, see the Sentinel Overview and Concepts Guide.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/ocs-failure-handling-promotions/index.adoc

:here: sentinel-components/promotions/ocs-failure-handling-promotions/ :idprefix: ocs-failure-handling-promotions

:leveloffset: 1

= OCS Failure Handling Promotions :indexpage: :sortorder: 1

OCS failure handling promotions features include:

* OCS failure handling data promotion feature * OCS failure handling SMS promotion feature * OCS failure handling time promotion feature

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/ocs-failure-handling-promotions/ocs-failure-handling-data-promotion-feature.adoc

:here: sentinel-components/promotions/ocs-failure-handling-promotions/ :idprefix: ocs-failure-handling-data-promotion-feature

:leveloffset: 1

= OCS Failure Handling Data Promotion Feature

== Description

[cols="1h,<" width="60"]

|Feature name |OcsFailureHandlingDataPromotionFeature |Applicable contexts |Diameter service |SAS Support | No |Prerequisite features |

Used in an OCS Failure case to grant units if available from an OcsFailureHandlingData bucket.

== Configuration

This feature is not configurable.

== Provisioning interfaces

This feature has no provisioning interfaces.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/ocs-failure-handling-promotions/ocs-failure-handling-sms-promotion-feature.adoc

:here: sentinel-components/promotions/ocs-failure-handling-promotions/ :idprefix: ocs-failure-handling-sms-promotion-feature

:leveloffset: 1

= OCS Failure Handling SMS Promotion Feature

== Description

[cols="1h,<" width="60"]

|Feature name |OcsFailureHandlingSmsPromotionFeature |Applicable contexts |Diameter service |SAS Support | No |Prerequisite features |

Used in an OCS failure case to grant units if available from an OcsFailureHandlingSms bucket.

== Configuration

This feature is not configurable.

== Provisioning interfaces

This feature has no provisioning interfaces.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/ocs-failure-handling-promotions/ocs-failure-handling-time-promotion-feature.adoc

:here: sentinel-components/promotions/ocs-failure-handling-promotions/ :idprefix: ocs-failure-handling-time-promotion-feature

:leveloffset: 1

= OCS Failure Handling Time Promotion Feature

== Description

[cols="1h,<" width="60"]

|Feature name |OcsFailureHandlingTimePromotionFeature |Applicable contexts |Diameter service |SAS Support | No |Prerequisite features |

Used in an OCS failure case to grant units if available from an OcsFailureHandlingTime bucket.

== Configuration

This feature is not configurable.

== Provisioning interfaces

This feature has no provisioning interfaces.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/promotion-buckets.adoc

:here: sentinel-components/promotions/ :idprefix: promotions-buckets

:leveloffset: 1

= Promotions Buckets

A promotion bucket is a counter of units available to a given subscriber.

Each bucket must have a unique name and can be configured within Sentinel to be of one of the following access types:

* External database * Cassandra * SLEE profiles * Sentinel session state * Unlimited.

Each promotion must state the name of the bucket to which units shall be charged if the promotion applies.

Multiple promotions can charge to the same bucket.

If the bucket is configured for ‘external database’ access, the promotion bucket units are held in an external database.

== Promotion units

Promotion units are generic and can be used to represent any unit type.

There is a one-to-one ratio between the value of a promotion unit and the value of the charging unit being deducted by a promotion. For example, if a promotion matches a request for 1024 Octets, then 1024 promotion units will be deducted.

Therefore, it is generally not sensible to match two different unit types in the same promotion, unless they have a one-to-one value.

== Provisioning interfaces

Promotion bucket configuration and data are provisioned using the web interface.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/promotions-commit-used-units-feature.adoc

:here: sentinel-components/promotions/ :idprefix: promotions-commit-used-units-feature

:leveloffset: 1

= Promotions Commit Used Units Feature

== Description

[cols="1h,a" width="60"]

|Feature name |PromotionsCommitUsedUnits |Applicable contexts | * SS7 service |SAS Support | No * Diameter Mediation Service |Prerequisite features | |Postrequisite features |ScriptedPromotions

PromotionsCommitUsedUnits handles all UsedServiceUnit requests for a set of promotions. The committing of UsedServiceUnits to promotion buckets is performed based on the analysis of session counters in session state. If the promotion script no longer applies when the used service units related to the promotion arrive, this feature will still handle the units.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/promotions-free-reservations-feature.adoc

:here: sentinel-components/promotions/ :idprefix: promotions-free-reservations-feature

:leveloffset: 1

= Promotions Free Reservations Feature

== Description

[cols="1h,a" width="55"]

|Feature name |PromotionsFreeReservations |Applicable contexts | * SS7 service |SAS Support | No * Diameter Mediation Service |Prerequisite features |ScriptedPromotions

PromotionsFreeReservations frees any promotion-related reservations that have not been freed before the end of the session. It is mandatory to include this as an end session feature if either Scripted Promotions Feature or a feature which extends BaseJavaPromotionFeature is in use.

Unused reservations are determined by examining the current state of the session counters stored in session state.

The feature must be installed in the end session execution point in both the SS7 and Diameter client services.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/scripted-promotions-feature/index.adoc

:here: sentinel-components/promotions/scripted-promotions-feature/ :idprefix: scripted-promotions-feature

:leveloffset: 1

= Scripted Promotions Feature :indexpage: :toc: macro :toclevels: 4 :toc-title: On this page…​

toc::[]

== Description

[cols="1h,a" width="55"]

|Feature name |ScriptedPromotions |Applicable contexts | * SS7 service |SAS Support | No * Diameter Mediation service * SIP service |Prerequisite features |PromotionsCommitUsedUnits |Postrequisite features |PromotionsFreeReservations

Using the ScriptedPromotions feature, new promotions can be created, enabled, disabled, or removed during normal Sentinel online operation.

The promotions are executed in the Diameter Mediation module which is used by all Sentinel client modules: Diameter Client and SS7 Client. Scripted Promotions are available for all session and call sessions, including Voice/Video/Data/Fax calls triggered by CAMEL, CAMEL callback calls, MO SMS, and Diameter sessions.

=== Session scenarios

The following scenarios are supported and enabled via scripted promotions:

* charge all units for a session from a single or multiple promotion, entirely suppressing interaction with the OCS * charge units from multiple MSCCs in a single CCR where they have different parameters (such as servicdid) to different promotions, to the OCS * serially interleave promotions and OCS requests related to a condition * charge units to a promotion on OCS failure * direct debit and refund units with promotions.

Scripted Promotion may apply:

* between promotions with wide validity dates * between subscription-specific validity dates * during certain times of day or on certain days * across a service plan for a set of subscribers * to certain session types only (such as SMS, Voice calls, GGSN sessions, and so on) * based on individual subscription * based on AVPs available in the CCRs (such as tarrifs, roaming indicators, serviceIds, rating groups, or location information) * based on type of units.

=== Promotions feature API

The Diameter Mediation module exposes a feature execution point DiameterMediationChargingControlFeatureEndpoint to provide ScriptedPromotions and other third-party developed promotions with the necessary controls over session behaviour. The feature endpoint API provides the following controls:

[cols="1,3" width="75"]

|Method |Description

|suppressOcsInteraction |request: suppress further interaction with the OCS |enableOcsInteraction |request: enable further interaction with the OCS |isOcsInteractionEnabled |check if ocs interaction is currently enabled |shutdownOCS |request: existing OCS connection shall be shutdown if one exists

ScriptedPromotions uses these controls to apply promotions where applicable to requests from the Diameter mediation clients.

=== Promotion selection

Promotion selection is performed using the following algorithm:

---- Get the list of promotions by selection key For each promotion in the list in order of ascending priority evaluate the conditional expression of the promotion to determine if it is applicable to the session Reserve applicable requested units from the promotion bucket Update the CCR and synthesize a CCA ----

Promotion selection is only relevant to the CreditControlRequests which have RequestServiceUnit AVPs. All UsedServiceUnit AVPs are handled without condition by PromotionsCommitUsedUnits. All outstanding promotion reservations on session end are freed by PromotionsFreeReservations.

== Scripted promotion scope

A scripted promotion has one of the following scopes:

* All subscribers (applies to all subscribers) * Subscribed (applies to subscribers who have subscribed to the promotion).

The scope is determined using the subscriberIsEligible function in Promotion Selection Expressions. If this function is present, the scope will be to subscribed subscriber only. If this function is absent, the promotion is scoped to all subscribers.

=== Configuration

A promotion bucket is referenced by SubscriberId and the bucket name stated by each promotion. A bucket contains the available and reserved units. The unit type may be: time (seconds), bytes, event counts, or some service-specific unit type. The unit type is not enforced by the bucket. It is the responsibility of the promotion to correctly select requested service unit AVPs with the correct unit type for the promotion.

The bucket unit record contains the following fields:

[cols="1,6"]

|Parameter |Description

|SubscriberId |Subscriber identifier |BucketName |Name of the bucket |AvailableUnits |Available units for this promotion |ReservedUnits |Any units which have been reserved during session charging but not committed as used units, or freed at session end

The subscriber also has a promotion configuration retrieved by the Subscriber Data Lookup Feature:

[cols="1,3"]

|Parameter |Description

|PromotionList |Used by the subscriberIsEligible promotion script function Promotion Selection Expressions |PromotionValidityStartDates |Used by the subscriberIsEligible promotion script function Promotion Selection Expressions |PromotionValidityEndDates |Used by the subscriberIsEligible promotion script function Promotion Selection Expressions

Each scripted promotion is configured in the PromotionsTable:

[cols="1,4"]

|Parameter |Description

|SelectionKey |Sentinel selection key the promotion is scoped to (for example, OpenCloud::::) |PromotionName |Promotion name (for example, AnytimeFreeData) |BucketName |Bucket name (for example, AnytimeFreeData) |PromotionPriority |Promotions selection priority |PromotionConditionSrc |See Promotion Selection Expressions (for example chargingUnitTypeOneOf(CCInputOctets,CCOutputOctets,CCTotalOctets)) |EncodedValidityEnd |Used by the promotionIsCurrent function to determine promotion-wide validity |EncodedValidityStart |Used by the promotionIsCurrent function to determine promotion-wide validity

PromotionBucketsConfigTable:

[cols="1,6"]

|Parameter |Description

|BucketName |The ID of the promotion bucket for which this configuration applies. |DataSource |profile,dbquery,cassandra,unlimited,sessionstate. Used when no dedicated access configuration can be found for a particular bucket name. Note: the profile is only used for testing or demo purposes.

PromotionsConfigTable:

[cols="1,3"]

|Parameter |Description

|DefaultDataSource |profile,dbquery,cassandra,unlimited,sessionstate. Used when no dedicated access configuration can be found for a particular bucket name. Note: the profile is only used for testing or demo purposes. |PartialGrantingThreshold |0 |PromotionApplicationMode |one_only (single option available) |UnitGrantingMode |partial, full_only. When set to partial, will grant units to the minimum set by the PartialGrantingThreshold parameter. When set to full_only, the units will only be granted if the full amount is available from the promotion bucket.

PromotionsDbQueryConfigProfileTable:

[cols="1,3" width="85"]

|Parameter |Description

|AddSQL |SQL statement for adding a bucket for a subscriber |DatabaseRequestTimeout |Database request timeout in milliseconds |DeleteSQL |SQL statement for deleting a bucket for a subscriber |istAllSQL |SQL statement for listing all buckets |LoadSQL |SQL statement for loading a bucket based on subscriber id and bucket name |UpdateSQL |SQL statement for updating a bucket based on subscriber id and bucket name

== Configuration profile naming

|Configuration profile table name |Description |Profile naming

|PromotionsTable |Configuration of scripted promotions |SentinelSelectionKey:priority_promotionname (for example, OpenCloud:::::0_AnytimeFreeData) |PromotionBucketsConfigTable |Configuration of promotion bucket properties (such as access type) |SentinelSelectionKey:BucketName (for example, OpenCloud::::AnytimeFreeData) |PromotionsConfigTable |Configuration of promotions behaviour |SentinelSelectionKey (for example, OpenCloud::::) |PromotionsDbQueryConfigProfileTable |DbQuery statement configuration |SentinelSelectionKey for example, OpenCloud::::)

=== Provisioning interfaces

Scripted promotions are provisioned using the web interface.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/index.adoc

:here: sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/ :idprefix: promotion-selection-expressions

:leveloffset: 1

= Promotion Selection Expressions :indexpage:

== Description

Promotions selection conditional expressions determine promotion applicability by analysing the set of Request Service Unit AVPs which are present in one or more MultipleServicesCreditControl AVPs.

== Promotion Conditional Expressions

Promotion Selection Expressions are Boolean expressions using the follow operators (in descending precedence):

+! (NOT), && (AND) and

(OR)+

Parenthesis () may be used in the expressions.

Comparison operators: > < == != >= ⇐

Types: Boolean, String, Integer

Access to session state: variables are prefixed with sessionstate. or ss.

Constants: string (“string”); boolean (`true

false

TRUE

FALSE`); integer (1, -1)

=== XPath expressions

XPath expressions on Diameter messages are used to select an AVP from the message for use in the expressions (see XPath Language Component):

---- ss.LatestClientRequest/MultipleServicesCreditControl\[ServiceID = 1\] ss.LatestClientRequest/MultipleServicesCreditControl\[ServiceID = 1\]/RequestedServiceUnit/CCInputOctets ----

=== Predicates and variables

[cols="3*a" options="header"]

|Function |Arguments |Description

|promotionIsCurrent |N/A |Uses the validity information in the promotion’s configuration in PromotionsTable

|subscriberIsEligible |N/A |Uses the validity information in the subscriber’s promotion configuration

|timeOfDayBetween |integer: start time, Integer: stop time (For example, timeOfDay(800, 1400) means inclusive hours between 0800 and 1400 |Returns true if current time of day is between the start and stop time. If the start time is > stop time, then timeOfDay will check between start time — 2400 and 0000 — stop

|todayOneOf |Any of “Mon”,“Tue”,“Wed”,“Thur”,“Fri”, “Sat”,“Sun” (for example, todayOneOf("Mon", "Fri")) |Returns true if current day of week is one of the listed days

|sessionstate.<varname>, ss.<varname> |N/A |In predicate context, returns true if not null, an empty array, an empty collection, an empty string or a Boolean with value of true, otherwise false. In expression context (that is, as argument to function or comparator) returns the actual value.

Note Boolean sessionstate fields always evaluate to true in predicate context unless they are null. To test for false, compare the returned object to false using ==

|chargingServiceIDOneOf |Comma-delimited list of serviceNames (see ServiceIDConfigTable Configuration) |returns true if the service name of the charging info is in the argument list

|chargingUnitTypeOneOf |Comma-delimited list of any of CCServiceSpecificUnits, CCMoney, CCInputOctets, CCOutputOctets, CCTotalOctets, CCTime |returns true if the charging unit type of the charging info is in the argument list

Functions may be added by using the SDK to provide extensions.

=== Example

---- subscriberIsEligible() && ss.ccr/Multiple-Service-Credit-Control[Service-Id = 1 and */CC-Input-Octets] && ss.isRoaming && ( timeOfDayBetween(800, 1000)

timeOfDayBetween(1800, 1900)) && todayOneOf("Mon","Fri") ----

=== Syntax

See Promotion Selection Expression DSL Grammar.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/promotion-selection-expression-dsl-grammar.adoc

:here: sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/ :idprefix: promotion-selection-expression-dsl-grammar

:leveloffset: 1

= Promotion Selection Expression DSL Grammar

The following grammar (in the ANLTR parser generator notation) defines the syntax of promotion selection expressions.

---- grammar SentinelPromotionScript;

promotionCondition : predicate EOF ;

predicate : andPred ('

' andPred)* ;

andPred : condition ('&&' condition)* ;

condition : '(' predicate ')'

'!' condition

comparison ;

comparison : expression (COMPARATOR expression)? ;

expression : ID ('.' ID)* '(' argumentList? ')'

id=ID ('.' ID)* (pathExpr)? //a variable is a function without args

LONG

STRING ;

argumentList : expression (',' expression )* ;

pathExpr : '/' relativePathExpr?

'//' relativePathExpr

relativePathExpr ;

relativePathExpr: stepExpr (( '/'

'//' ) stepExpr )* ;

stepExpr: ( '.'

abbrevForwardStep ) (xpathpredicate)? ;

abbrevForwardStep : attributeFlag = '@'? (stQName = qName

stNodeExpansion = '') ;

xpathpredicate : '[' orExpr ']' ;

orExpr : andExpr ('or' andExpr) ;

andExpr : comparisonexpr ('and' comparisonexpr)* ;

comparisonexpr: primaryExpr (COMPARATOR literal)?;

primaryExpr : pathExpr

'(' pathExpr ')'

LONG ;

literal : STRING

numericLiteral

varRef;

numericLiteral: LONG DECIMALLITERAL

DOUBLELITERAL;

qName: (ID ':' ID)

ID;

varRef: '$' nCName;

nCName: ID ('.' ID)*;

COMPARATOR : '=='

'<'

'>'

'!='

'⇐'

'>=';

ID : ('a'..'z'

'A'..'Z'

'_') ('a'..'z'

'A'..'Z'

'0'..'9'

'_')* ;

LONG : ('-')? '0'..'9'+ ;

DECIMALLITERAL : ('.' ('0'..'9')+)

(('0'..'9')+ '.' '0'..'9'*); DOUBLELITERAL : (('.' ('0'..'9')+)

'0'..'9')+ ('.' '0'..'9'*)? ('e'

'E') ('+'

'-')? ('0'..'9')+;

STRING : '"' ~('\\'

'"')* '"' ;

WS : ( ' '

'\t'

'\r'

'\n' ) ; ----

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/service-id-config-table-configuration.adoc

:here: sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/ :idprefix: service-id-config-table-configuration

:leveloffset: 1

= Service ID Config Table Configuration

The ServiceID configuration table provides a mapping between ServiceID integers in Diameter messages and the names of the services.

== Configuration

The ServiceIDConfigTable is scoped by selection key and has the following fields:

[cols="1,2" width="40"]

|Parameter |Description

|ServiceIDs |Array of integers |ServiceNames |Array of service name strings

=== Example profile:

[width="40"]

|ServiceIDs |ServiceNames

|100,101,200 |Facebook,Voicecall,Youtube

In this example:

* Facebook has service id 100. * Voicecall has service id 101. * Youtube has service id 200.

== Configuration profile naming

|Configuration Profile Table Name |Description |Profile Naming

|ServiceIDConfigTable |Selection of database implementation and rating group for the feature |SentinelSelectionKey (for example, OpenCloud::::)

== Provisioning interfaces

The service IDs are provisioned using the web interface (under Sentinel > Service Configuration > Diameter Mediation > Service IDs).

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/index.adoc

:here: sentinel-components/mappers/ :idprefix: mappers

:leveloffset: 1

= Mappers :indexpage: :sortorder: 5

Sentinel comes with many mappers that can be configured at various mapping points and scopes.

Mappers include:

==== * Sentinel diameter mappers * Sentinel diameter mediation mappers * Sentinel OCS driver mappers * Sentinel SIP mappers * Sentinel Registrar mappers * Sentinel SS7 mappers ====

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-diameter-mappers.adoc

:here: sentinel-components/mappers/ :idprefix: sentinel-diameter-mappers

:leveloffset: 1

= Sentinel Diameter Mappers :toc: macro :toclevels: 4 :toc-title: On this page…​

toc::[]

== SentinelCCAToRoClientCCA

com.opencloud.sentinel.mapper.impl.SentinelCCAToRoClientCCA

Mappings:

|Name |From |To

|SentinelCCAToRoClientCCA |org.jainslee.resources.diameter.ro.types.CreditControlAnswer |org.jainslee.resources.diameter.ro.types.CreditControlAnswer

== SentinelASRToRoClientASR

com.opencloud.sentinel.mapper.impl.SentinelASRToRoClientASR

Mappings:

|Name |From |To

|SentinelASRToRoClientASR |org.jainslee.resources.diameter.base.types.AbortSessionRequest |org.jainslee.resources.diameter.base.types.AbortSessionRequest

== SentinelRARToRoClientRAR

com.opencloud.sentinel.mapper.impl.SentinelRARToRoClientRAR

Mappings:

|Name |From |To

|SentinelRARToRoClientRAR |org.jainslee.resources.diameter.base.types.ReAuthRequest |org.jainslee.resources.diameter.base.types.ReAuthRequest

== RoClientRAAToSentinelRAA

com.opencloud.sentinel.mapper.impl.RoClientRAAToSentinelRAA

Mappings:

|Name |From |To

|RoClientRAAToSentinelRAA |org.jainslee.resources.diameter.base.types.ReAuthAnswer |org.jainslee.resources.diameter.base.types.ReAuthAnswer

== CCRToCDR

com.opencloud.sentinel.mapper.impl.CCRToCDR

Mappings:

|Name |From |To

|CCRToCDR |org.jainslee.resources.diameter.ro.types.CreditControlRequest |com.google.protobuf.Message

== RoClientCCRToSentinelCCR

com.opencloud.sentinel.mapper.impl.RoClientCCRToSentinelCCR

Mappings:

|Name |From |To

|RoClientCCRToSentinelCCR |org.jainslee.resources.diameter.ro.types.CreditControlRequest |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== RoClientASAToSentinelASA

com.opencloud.sentinel.mapper.impl.RoClientASAToSentinelASA

Mappings:

|Name |From |To

|RoClientASAToSentinelASA |org.jainslee.resources.diameter.base.types.AbortSessionAnswer |org.jainslee.resources.diameter.base.types.AbortSessionAnswer

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-diameter-mediation-mappers.adoc

:here: sentinel-components/mappers/ :idprefix: sentinel-diameter-mediation-mappers

:leveloffset: 1

= Sentinel Diameter Mediation Mappers

== SessionStateToSentinelCCRTerminate

com.opencloud.sentinel.mapper.impl.SessionStateToSentinelCCRTerminate

Mappings:

|Name |From |To

|SessionStateToSentinelCCRTerminate |com.opencloud.sentinel.common.SentinelDiameterMediationSessionState |org.jainslee.resources.diameter.ro.types.CreditControlRequest

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-ocs-driver-mappers.adoc

:here: sentinel-components/mappers/ :idprefix: sentinel-ocs-driver-mappers

:leveloffset: 1

= Sentinel OCS Driver Mappers :toc: macro :toclevels: 4 :toc-title: On this page…​

toc::[]

== RoOcsRARToSentinelRAR

com.opencloud.sentinel.mapper.impl.RoOcsRARToSentinelRAR

Mappings:

|Name |From |To

|RoOcsRARToSentinelRAR |org.jainslee.resources.diameter.base.types.ReAuthRequest |org.jainslee.resources.diameter.base.types.ReAuthRequest

== SentinelRAAToRoOcsRAA

com.opencloud.sentinel.mapper.impl.SentinelRAAToRoOcsRAA

Mappings:

|Name |From |To

|SentinelRAAToRoOcsRAA |org.jainslee.resources.diameter.base.types.ReAuthAnswer |org.jainslee.resources.diameter.base.types.ReAuthAnswer

== RoOcsCCAToSentinelCCA

com.opencloud.sentinel.mapper.impl.RoOcsCCAToSentinelCCA

Mappings:

|Name |From |To

|RoOcsCCAToSentinelCCA |org.jainslee.resources.diameter.ro.types.CreditControlAnswer |org.jainslee.resources.diameter.ro.types.CreditControlAnswer

== RoOcsASRToSentinelASR

com.opencloud.sentinel.mapper.impl.RoOcsASRToSentinelASR

Mappings:

|Name |From |To

|RoOcsASRToSentinelASR |org.jainslee.resources.diameter.base.types.AbortSessionRequest |org.jainslee.resources.diameter.base.types.AbortSessionRequest

== SentinelCCRToRoOcsCCR

com.opencloud.sentinel.mapper.impl.SentinelCCRToRoOcsCCR

Mappings:

|Name |From |To

|SentinelCCRToRoOcsCCR |org.jainslee.resources.diameter.ro.types.CreditControlRequest |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== SentinelASAToRoOcsASA

com.opencloud.sentinel.mapper.impl.SentinelASAToRoOcsASA

Mappings:

|Name |From |To

|SentinelASAToRoOcsASA |org.jainslee.resources.diameter.base.types.AbortSessionAnswer |org.jainslee.resources.diameter.base.types.AbortSessionAnswer

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-registrar-mappers.adoc

:here: sentinel-components/mappers/ :idprefix: sentinel-registrar-mappers

:leveloffset: 1

= Sentinel Registrar Mappers :toc: macro :toclevels: 4 :toc-title: On this page…​

toc::[]

== ReceivedRegisterRequestToNetworkOperatorLookupKey

com.opencloud.sentinel.registrar.mapper.impl.ReceivedRegisterRequestToNetworkOperatorLookupKey

[cols="1,1,2" options="header"]

|From …​ | …​ To | Description

| IncomingSipRequest | String | Returns the To address host as the lookup key.

== ReceivedRegisterRequestToSessionState

com.opencloud.sentinel.registrar.mapper.impl.ReceivedRegisterRequestToSessionState

[cols="1,1,2" options="header"]

|From …​ | …​ To | Description

| IncomingSipRequest | SentinelRegistrarSessionState | Extracts the first-party REGISTER request and response from the third-party REGISTER request message body, and stores them in session state.

== RegisterRequestAndResponseToUserIdMapper

com.opencloud.sentinel.registrar.mapper.impl.RegisterRequestAndResponseToUserIdMapper

[cols="1,1,2" options="header"]

|From …​ | …​ To | Description

| UserIdsSessionState | UserIdsSessionState | Extracts common identities from the first-party REGISTER request and response in session state, and stores them in session state fields. In particular the private-id, public-ids, Contacts, and any GRUU that are present. The RegistrarConfiguration is used to determine whether the private-id or the call-id is to be used as the primary key for the registrar data.

== SessionStateToRegisterCdrAvpBasedMapper

com.opencloud.sentinel.registrar.mapper.impl.SessionStateToRegisterCdrAvpBasedMapper

[cols="1,1,2" options="header"]

|From …​ | …​ To | Description

|SentinelRegistrarSessionState |com.google.protobuf.Message |Builds an audit CDR from fields in session state

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-sip-mappers.adoc

:here: sentinel-components/mappers/ :idprefix: sentinel-sip-mappers

:leveloffset: 1

= Sentinel SIP Mappers :toc: macro :toclevels: 4 :toc-title: On this page…​

Labels: pending_finishupdate

toc::[]

== HttpRequestToCallingPartySipRequest

com.opencloud.sentinel.mapper.impl.HttpRequestToCallingPartySipRequest

Mappings:

|Name |From |To

|HttpRequestToCallingPartySipRequest |com.opencloud.slee.resources.http.HttpRequest |org.jainslee.resources.sip.SipRequest

== HttpRequestToCalledPartySipRequest

com.opencloud.sentinel.mapper.impl.HttpRequestToCalledPartySipRequest

Mappings:

|Name |From |To

|HttpRequestToCalledPartySipRequest |com.opencloud.slee.resources.http.HttpRequest |org.jainslee.resources.sip.SipRequest

== ThirdPartyCallOutcomeToHttpResponse

com.opencloud.sentinel.mapper.impl.ThirdPartyCallOutcomeToHttpResponse

Mappings:

|Name |From |To

|ThirdPartyCallOutcomeToHttpResponse |om.opencloud.sentinel.common.SipThirdPartyCallOutcomes |com.opencloud.slee.resources.http.HttpResponse

== CCAtoSessionCounterList

com.opencloud.sentinel.mapper.impl.CCAtoSessionCounterListMapper

Mappings:

|Name |From |To

|CCAtoSessionCounterListMapper |org.jainslee.resources.diameter.ro.types.vcb0.CreditControlAnswer |java.util.List

== ChargingInstanceToCCR

com.opencloud.sentinel.mapper.impl.ChargingInstanceToCCR

Mappings:

|Name |From |To

|ChargingInstanceToCCR |com.opencloud.sentinel.charging.ChargingInstance |org.jainslee.resources.diameter.ro.types.vcb0.CreditControlRequest

== SdpDiffToSdpCcrDiffMapper

com.opencloud.sentinel.mapper.impl.SdpDiffToSdpCcrDiffMapper

Mappings:

|Name |From |To

|SdpDiffToSdpCcrDiffMapper |com.opencloud.sentinel.diff.sdp.SdpDiffModel |com.opencloud.sentinel.diff.sdp.SdpDiffModel

== SdpMatchModelToSdpCcrMatchModelMapper

com.opencloud.sentinel.mapper.impl.SdpMatchModelToSdpCcrMatchModelMapper

Mappings:

|Name |From |To

|SdpMatchModelToSdpCcrMatchModelMapper |com.opencloud.sentinel.diff.sdp.SdpMatchModel |com.opencloud.sentinel.diff.sdp.SdpMatchModel

== SessionStateToForcedOutgoingSipErrorResponse

com.opencloud.sentinel.mapper.impl.SessionStateToForcedOutgoingSipErrorResponse

Mappings:

|Name |From |To

|SessionStateToForcedOutgoingSipErrorResponse |org.jainslee.resources.sip.IncomingSipRequest |org.jainslee.resources.sip.OutgoingSipResponse

== SipRequestToCCR

com.opencloud.sentinel.mapper.impl.SipRequestToCCR

Mappings:

|Name |From |To

|SipRequestToCCR |org.jainslee.resources.sip.SipRequest |org.jainslee.resources.diameter.ro.types.vcb0.CreditControlRequest

== SipRequestToSessionCounterAddress

com.opencloud.sentinel.mapper.impl.SipRequestToSessionCounterAddress

Mappings:

|Name |From |To

|SipRequestToSessionCounterAddress |org.jainslee.resources.sip.SipRequest |com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-ss7-mappers.adoc

:here: sentinel-components/mappers/ :idprefix: sentinel-ss7-mappers

:leveloffset: 1

= Sentinel SS7 Mappers :toc: macro :toclevels: 4 :toc-title: On this page…​

This page describes the Sentinel SS7 mappers.

toc::[]

== CCAToReleaseCallArg

com.opencloud.sentinel.mapper.impl.CCAToReleaseCallArg

Mappings:

|Name |From |To

|CCAToReleaseCallArg |org.jainslee.resources.diameter.ro.types.CreditControlAnswer |com.opencloud.slee.resources.cgin.callcontrol.CCReleaseCallArg

== CorrelationDataToCAPInitialDP

com.opencloud.sentinel.mapper.impl.CorrelationDataToCAPInitialDP

Mappings:

|Name |From |To

|CorrelationDataToCAP1InitialDP |byte[] |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

== CAP3InitialDPSMSArgToCCR

com.opencloud.sentinel.mapper.impl.CAP3InitialDPSMSArgToCCR

Mappings:

|Name |From |To

|CAP3InitialDPSMSArgToCCR |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== CAP3EventReportSMSArgToCCR

com.opencloud.sentinel.mapper.impl.CAP3EventReportSMSArgToCCR

Mappings:

|Name |From |To

|CAP3EventReportSMSArgToCCR |com.opencloud.slee.resources.cgin.cap_v3.CAP3EventReportSMSArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== CAP3InitialDPArgToConnectArg

com.opencloud.sentinel.mapper.impl.CAP3InitialDPArgToConnectArg

Mappings:

|Name |From |To

|CAP3InitialDPArgToConnectArg |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPArg |com.opencloud.slee.resources.cgin.callcontrol.CCConnectArg

== CCSpecializedResourceReportArgToCCR

com.opencloud.sentinel.mapper.impl.CCSpecializedResourceReportArgToCCR

Mappings:

|Name |From |To

|CCSpecializedResourceReportArgToCCR |com.opencloud.slee.resources.cgin.callcontrol.CCSpecializedResourceReportArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== CAP3InitialDPSMSArgToCAP3ConnectSMSArg

com.opencloud.sentinel.mapper.impl.CAP3InitialDPSMSArgToCAP3ConnectSMSArg

Mappings:

|Name |From |To

|CAP3InitialDPSMSArgToCAP3ConnectSMSArg |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg |com.opencloud.slee.resources.cgin.cap_v3.CAP3ConnectSMSArg

== CAP2ApplyChargingReportToReauthCCR

com.opencloud.sentinel.mapper.impl.CAP2ApplyChargingReportToReauthCCR

Mappings:

|Name |From |To

|CAP2ApplyChargingReportToReauthCCR |com.opencloud.slee.resources.cgin.cap_v2.CAP2ApplyChargingReportArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== LegTypeToCS1CallInformationRequestArg

com.opencloud.sentinel.mapper.impl.LegTypeToCS1CallInformationRequestArg

Mappings:

|Name |From |To

|LegTypeToCS1CallInformationRequestArg |com.opencloud.slee.resources.in.datatypes.cc.LegType |com.opencloud.slee.resources.cgin.etsi_inap_cs1.CS1CallInformationRequestArg

== CAPInitialDPArgToCorrelationData

com.opencloud.sentinel.mapper.impl.CAPInitialDPArgToCorrelationData

Mappings:

|Name |From |To

|CAP1InitialDPArgToCorrelationData |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |byte[] |CAP2InitialDPArgToCorrelationData |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |byte[] |CAP3InitialDPArgToCorrelationData |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPArg |byte[] |CAP4InitialDPArgToCorrelationData |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitialDPArg |byte[]

== DialogOpenRequestEventToCdr

com.opencloud.sentinel.mapper.impl.DialogOpenRequestEventToCdr

Mappings:

|Name |From |To

|DialogOpenRequestEventToCdr |com.opencloud.slee.resources.cgin.DialogOpenRequestEvent |com.google.protobuf.Message

== ThirdPartyCallOutcomeToHttpResponse

com.opencloud.sentinel.mapper.impl.ThirdPartyCallOutcomeToHttpResponse

Mappings:

|Name |From |To

|ThirdPartyCallOutcomeToHttpResponse |com.opencloud.sentinel.common.SipThirdPartyCallOutcomes |com.opencloud.slee.resources.http.HttpResponse

== CCInitialDPArgToCCR

com.opencloud.sentinel.mapper.impl.CCInitialDPArgToCCR

Mappings:

|Name |From |To

|CCInitialDPArgToCCR |com.opencloud.slee.resources.cgin.callcontrolCCInitialDPArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

|CAP2InitialDPArgToCCR |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== LegTypeToCAP2CallInformationRequestArg

com.opencloud.sentinel.mapper.impl.LegTypeToCAP2CallInformationRequestArg

Mappings:

|Name |From |To

|LegTypeToCAP2CallInformationRequestArg |com.opencloud.slee.resources.in.datatypes.cc.LegType |com.opencloud.slee.resources.cgin.cap_v2.CAP2CallInformationRequestArg

== CallTypeToCCRequestReportBCSMEventArg

com.opencloud.sentinel.mapper.impl.CallTypeToCCRequestReportBCSMEventArg

Mappings:

|Name |From |To

|CallTypeToCCRequestReportBCSMEventArg |com.opencloud.sentinel.common.CallType |com.opencloud.slee.resources.cgin.callcontrol.CCRequestReportBCSMEventArg

== CCInitialDPArgToCAP4InitiateCallAttempt

com.opencloud.sentinel.mapper.impl.CCInitialDPArgToCAP4InitiateCallAttempt

Mappings:

|Name |From |To

|CCInitialDPArgToCAP4InitiateCallAttempt |com.opencloud.slee.resources.cgin.callcontrol.CCInitialDPArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

|CAP1InitialDPArgToCAP4InitiateCallAttempt |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

|CAP2InitialDPArgToCAP4InitiateCallAttempt |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

|CAP3InitialDPArgToCAP4InitiateCallAttempt |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

|CAP4InitialDPArgToCAP4InitiateCallAttempt |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitialDPArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

== CAP2InitialDPArgToConnectArg

com.opencloud.sentinel.mapper.impl.CAP2InitialDPArgToConnectArg

Mappings:

|Name |From |To

|CAP2InitialDPArgToConnectArg |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |com.opencloud.slee.resources.cgin.callcontrol.CCConnectArg

== SentinelErrorToReleaseCallArg

com.opencloud.sentinel.mapper.impl.SentinelErrorToReleaseCallArg

Mappings:

|Name |From |To

|SentinelErrorToReleaseCallArg |com.opencloud.sentinel.common.SentinelError |com.opencloud.slee.resources.cgin.callcontrol.CCReleaseCallArg

== SessionTypeToCAP3RequestReportSMSEventArg

com.opencloud.sentinel.mapper.impl.SessionTypeToCAP3RequestReportSMSEventArg

Mappings:

|Name |From |To

|SessionTypeToCAP3RequestReportSMSEventArg |com.opencloud.sentinel.common.SessionType |com.opencloud.slee.resources.cgin.cap_v3.CAP3RequestReportSMSEventArg

== HttpRequestToCAP2InitialDPArg

com.opencloud.sentinel.mapper.impl.HttpRequestToCAP2InitialDPArg

Mappings:

|Name |From |To

|HttpRequestToCAP2InitialDPArg |com.opencloud.slee.resources.http.HttpRequest |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg

== CCInitialDPArgToConnectArg

com.opencloud.sentinel.mapper.impl.CCInitialDPArgToConnectArg

Mappings:

|Name |From |To

|CCInitialDPArgToConnectArg |com.opencloud.slee.resources.cgin.callcontrol.CCInitialDPArg |com.opencloud.slee.resources.cgin.callcontrol.CCConnectArg

== CAP1InitialDPArgToConnectArg

com.opencloud.sentinel.mapper.impl.CAP1InitialDPArgToConnectArg

Mappings:

|Name |From |To

|CAP1InitialDPArgToConnectArg |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |com.opencloud.slee.resources.cgin.callcontrol.CCConnectArg

== CAP2ApplyChargingReportToCCR

com.opencloud.sentinel.mapper.impl.CAP2ApplyChargingReportToCC

Mappings:

|Name |From |To

|CAP2ApplyChargingReportToCCR |com.opencloud.slee.resources.cgin.cap_v2.CAP2ApplyChargingReportArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== AdditionalCallPartyArgToCAP4InitiateCallAttempt

com.opencloud.sentinel.mapper.impl.AdditionalCallPartyArgToCAP4InitiateCallAttempt

Mappings:

|Name |From |To

|AdditionalCallPartyArgToCAP4InitiateCallAttempt |com.opencloud.sentinel.mapper.types.AdditionalCallPartyArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

== CAP2CallInformationReportToCCR

com.opencloud.sentinel.mapper.impl.CAP2CallInformationReportToCCR

Mappings:

|Name |From |To

|CAP2CallInformationReportToCCR |com.opencloud.slee.resources.cgin.cap_v2.CAP2CallInformationReportArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== SessionStateCreditBufferToCAP2ApplyChargingArg

com.opencloud.sentinel.mapper.impl.SessionStateCreditBufferToCAP2ApplyChargingArg

Mappings:

|Name |From |To

|SessionStateCreditBufferToCCApplyChargingArg |com.opencloud.sentinel.common.SentinelSs7SessionState |com.opencloud.slee.resources.cgin.callcontrol.CCApplyChargingArg

|SessionStateCreditBufferToCAP2ApplyChargingArg |com.opencloud.sentinel.common.SentinelSs7SessionState |com.opencloud.slee.resources.cgin.cap_v2.CAP2ApplyChargingArg

== CAPInitialDPToCorrelationIdPoolAddress

com.opencloud.sentinel.mapper.impl.CAPInitialDPToCorrelationIdPoolAddress

Mappings:

|Name |From |To

|CAP1InitialDPToCorrelationIdPoolAddress |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |java.lang.String

|CAP2InitialDPToCorrelationIdPoolAddress |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |java.lang.String

|CAP4InitialDPToCorrelationIdPoolAddress |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitialDPArg |java.lang.String

== CAP3InitialDPSMSArgToCdr

com.opencloud.sentinel.mapper.impl.CAP3InitialDPSMSArgToCdr

Mappings:

|Name |From |To

|CAP3InitialDPSMSArgToCdr |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg |com.google.protobuf.Message

== CCAToCAP2ApplyChargingArg

com.opencloud.sentinel.mapper.impl.CCAToCAP2ApplyChargingArg

Mappings:

|Name |From |To

|CCAToCCApplyChargingArg |org.jainslee.resources.diameter.ro.types.CreditControlAnswer |com.opencloud.slee.resources.cgin.callcontrol.CCApplyChargingArg

|CCAToCAP2ApplyChargingArg |org.jainslee.resources.diameter.ro.types.CreditControlAnswer |com.opencloud.slee.resources.cgin.cap_v2.CAP2ApplyChargingArg

== CAP1InitialDPArgToCdr

com.opencloud.sentinel.mapper.impl.CAP1InitialDPArgToCdr

Mappings:

|Name |From |To

|CAP1InitialDPArgToCdr |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |com.google.protobuf.Message |CAP2InitialDPArgToCdr |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |com.google.protobuf.Message |CAP3InitialDPArgToCdr |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPArg |com.google.protobuf.Message |CAP4InitialDPArgToCdr |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitialDPArg |com.google.protobuf.Message

== HttpRequestToSS7CallCdr

com.opencloud.sentinel.mapper.impl.HttpRequestToSS7CallCdr

Mappings:

|Name |From |To

|HttpRequestForSs73rdPartyCallToCdr |com.opencloud.slee.resources.http.HttpRequest |com.google.protobuf.Message

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/address-lists.adoc

:here: sentinel-components/ :idprefix: include-address-lists

:leveloffset: 1

:doctitle: Address Lists :sortorder: 6 :page-id: include-address-lists

= Address Lists :indexpage:

:leveloffset: +1

= Address List Overview

== What is an address list?

An address list is a searchable collection of addresses. Each address in an address list may also have some associated data. You can use address lists for some of the features bundled with Sentinel, such as:

* special prefixes — Prefix and Suffix Analysis Feature does a longest prefix match against a dialled number to see if the dialled address includes one of the prefixes. * short-codes — The Short Code Feature does an exact match against a dialled number to see if the dialled number is a short-code. Each short-code in the address list has the fully qualified address the short-code represents. * global-title addresses — The SS7 Determine Network Operator Feature does a longest prefix match against the destination SCCP address to determine which network operator the new session is for.

Each address list has a unique name. The addresses in the address list are stored in SLEE profiles. Sentinel manages a cached digit tree for each address list. The digit tree provides fast exact, longest prefix, and longest suffix matching of addresses.

.addresses in an address list called “Prefixes”, mapped into a digit tree image::sentinel-components/features/sip-features/sip-user-features/addresslist.png[]

Addresses in an address list are sequences of: 0 …​ 9, a …​ f, A …​ F, #, , .

TIP: You provision address lists using the Sentinel Element Manager. See the Sentinel Administration Guide for details.

IMPORTANT: Address lists should only be managed with the Sentinel Element Manager or the RESTful HTTP provisioning interface. The SLEE profile tables, how they are named, and many of the fields are internal to Sentinel and the Element Manager.

= Profile Tables for Address Lists

Address lists are stored using SLEE profiles:

* Address list configuration profile — defines configuration properties of the address list (for example, should it be cached). * Address list entry profile  — the entries in the address list (and any associated data, if any)

[NOTE] ==== An address list is identified by two properties:

* *address list name — the name of the address list. For example, the PrefixAndSuffixAnalysis feature uses address lists called: ‘SpecialPrefixList’ and ‘SpecialSuffixList’. * schema name  — corresponds to the type of the address list. For example, the PrefixAndSuffixAnalysis feature address lists have the schema name ‘PrefixAndSuffixAnalysis’. Address lists that do not associate any data with an address list entry have the schema name ‘Sentinel’.

====

Sentinel adopts a simple naming convention for mapping an address list schema name to the SLEE profile tables required for address lists that use that schema.

* Address list configuration Table Name — <PlatformOperatorName>_<SchemaName>_AddressListConfigurationTable * Address list entry Table Name  — <PlatformOperatorName>_<SchemaName>_AddressListEntryTable

For example, the PrefixAndSuffixAnalysis feature uses address lists that are stored in these profile tables:

* <PlatformOperatorName>_PrefixAndSuffixAnalysis_AddressListConfigurationTable * <PlatformOperatorName>_PrefixAndSuffixAnalysis_AddressListEntryTable

Address lists that do not have any data associated with entries in the address list use a schema name of ‘Sentinel’ and are stored in the following SLEE profile tables:

* <PlatformOperatorName>_Sentinel_AddressListConfigurationTable * <PlatformOperatorName>_Sentinel_AddressListEntryTable

== Address List Configuration Profile

Each address list has a configuration profile with these properties:

[cols="1,1,3" width="90"]

|Parameter |Type |Description

|Description |String | |Name |String |The name of this address list |SchemaName |String |The name of the schema of this address list |PlatformOperator |String |…​ of the Selection key, for this address list to be used |NetworkOperator |String |…​ of the Selection key, for this address list to be used |SessionType |String |…​ of the Selection key, for this address list to be used |PlanId |String |…​ of the Selection key, for this address list to be used |SubscriptionId |String |…​ of the Selection key, for this address list to be used |DefaultSearchMode|Integer |One of: 0 — exact match, 1 — longest prefix match, 2 — longest suffix match |ShouldCache |Boolean |True, if the Sentinel core should maintain a cached version of the address list in memory |Version |Long |Sentinel core tracks the version for address lists that are cached in memory. If the version changes, then the Sentinel core re-builds the cached version of the address list. The version is incremented by the Sentinel Element Manager, once a set of updates to an address list (either by changing this configuration, or changing list entries) should be applied to any cached versions of the address list in memory.

== Address List Entry Profile Each Address List entry corresponds to a profile with these properties:

[cols="1,1,3" width="90"]

|Parameter |Type |Description

|Description |String | |Address |String |The address string — a sequence of characters matching: 0 …​ 9, a …​ f, A …​ F, #, *, . |listId |String |The list id is a string that identifies the address list this entry belongs to. It has the following form: <selectionkey>:<schemaName>:<listname>

NOTE: Address lists that have additional data will have additional properties for that data. See Using Address Lists in the Extending Sentinel with the SDK guide to understand how a feature uses an address list and how you can associate data with entries in an address list.

:leveloffset: -1

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/index.adoc

:here: provisioning/ :idprefix: provisioning

:leveloffset: 1

= Provisioning :indexpage: :sortorder: 4

== Using the Sentinel Element Manager

You provision Sentinel using the Sentinel Element Manager. The Sentinel Element Manager provides a web interface for provisioning Sentinel.

TIP: The Sentinel Element Manager is an extension of the Rhino Element Manager (REM). See Installing the Sentinel Express Provisioning Module to install the Sentinel provisioning module in REM. For general information on using Rhino Element Manager, see the Rhino Element Manager User Guide.

To provision Sentinel, see the procedures to:

==== * Configure the Sentinel REM Extension * Provision Sentinel using the Web Interface * Working with CDRs * Configure Auditing of Provisioning Operations * Configure and use the Sentinel XCAP API ====

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-configuration/index.adoc

:here: provisioning/provisioning-configuration/ :idprefix: provisioning-configuration

:leveloffset: 1

= Provisioning Configuration :indexpage: :sortorder: 1

You set configuration options for the Sentinel provisioning application using a properties file. On startup, the Sentinel provisioning server tries to read this file:

${REM_HOME}/sentinel-provisioning-config.properties

By default, this file does not exist, and Sentinel uses default options. To configure provisioning options:

. create this file . add the property definitions you want to customize.

You can also configure Sentinel EM to provision data in an external database.

== Provisioning configuration options

==== You can configure these Sentinel provisioning options:

* sentinel.<featurename>.default-page-size * sentinel.homezone.configuration.cache.timeout * sentinel.homezone.sql.cache.timeout * sentinel.subscriberdata.configuration.cache.timeout * sentinel.subscriberdata.fields.cache.timeout * sentinel.subscriberdata.sql.cache.timeout * sentinel.promotions.configuration.cache.timeout * sentinel.promotions.sql.cache.timeout * sentinel.core.configuration.cache.timeout ====

=== sentinel.<featurename>.default-page-size

[cols="1h,4a" width="80"]

|Description |The default page size used when listing entries in this resource collection. |Java type |int |Default value |10 |Example |sentinel.promotions.default-page-size=50

=== sentinel.homezone.configuration.cache.timeout

[cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for HomeZone configuration data used by the provisioning services. The HomeZone zones provisioning services will cache the configured lookup type (profile, dbquery) for a particular Sentinel selection key value for this amount of time. |Java type |long |Default value |60000 (1 minute) |Example |sentinel.homezone.configuration.cache.timeout=10000

=== sentinel.homezone.sql.cache.timeout

[cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for HomeZone SQL configuration data used by the provisioning services. The HomeZone zones provisioning services will cache the configured SQL statements for a particular Sentinel selection key value for this amount of time (only applicable if zones are being stored in an external database). |Java type |long |Default value |60000 (1 minute) |Example |sentinel.homezone.sql.cache.timeout=10000

=== sentinel.subscriberdata.configuration.cache.timeout

[cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for Subscriber Data configuration data used by the provisioning services. The Subscriber Data provisioning services will cache the lookup type (profile, dbquery, cassandra) for a particular Sentinel selection key value for this amount of time. |Java type |long |Default value |60000 (1 minute) |Example |sentinel.subscriberdata.configuration.cache.timeout=10000

=== sentinel.subscriberdata.fields.cache.timeout

[cols="1h,4a" width="80"]

|Description |Description The cache timeout (in milliseconds) to use for Subscriber Data fields configuration data used by the provisioning services. The Subscriber Data provisioning services will cache the configured fields for a particular Sentinel selection key value for this amount of time. |Java type |long |Default value |60000 (1 minute) |Example |sentinel.subscriberdata.fields.cache.timeout=10000

=== sentinel.subscriberdata.sql.cache.timeout

[cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for Subscriber Data SQL configuration data used by the provisioning services. The Subscriber Data provisioning services will cache the configured SQL statements for a particular Sentinel selection key value for this amount of time (only applicable if records are being stored in an external database). | Java type |long | Default value |60000 (1 minute) | Example |sentinel.subscriberdata.sql.cache.timeout=10000

=== sentinel.promotions.configuration.cache.timeout

[cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for Promotions configuration data used by the provisioning services. The Promotion bucket provisioning services will cache the configured lookup type (profile, dbquery, cassandra) for a particular Sentinel selection key value for this amount of time. |Java type |long |Default value |60000 (1 minute) |Example |sentinel.promotions.configuration.cache.timeout=10000

=== sentinel.promotions.sql.cache.timeout

[cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for Promotions SQL configuration data used by the provisioning services. The Promotion bucket provisioning services will cache the configured SQL statements for a particular Sentinel selection key value for this amount of time (only applicable if bucket data is being stored in an external database). |Java type |long |Default value |60000 (1 minute) |Example |sentinel.promotions.sql.cache.timeout=10000

=== sentinel.core.configuration.cache.timeout

[cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for Sentinel configuration data used by the XCAP API. |Java type |long |Default value |6000 (1 minute) |Example |sentinel.promotions.sql.cache.timeout=10000

== Provisioning data in an external database

If any of the Sentinel data (such as subscriber data records, home zone zones, or promotion buckets) is stored in an external database, Sentinel EM will need to be configured to connect to it directly.

See:

* Provisioning data in Cassandra * Provisioning data in TimesTen

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-configuration/provisioning-data-in-cassandra.adoc

:here: provisioning/provisioning-configuration/ :idprefix: provisioning-data-in-cassandra

:leveloffset: 1

= Provisioning Data in Cassandra :sortorder: 1

== Configuring provisioning lookup types and connections

Below are instructions for configuring Cassandra lookup types and the connection to the Cassandra database.

=== Configuring Cassandra provisioning lookup types

Sentinel comes with two Cassandra-based provisioning service implementations: for subscriber data and promotion buckets.

==== Subscriber data

To use the Cassandra-based provisioning service implementation for subscriber data, in the provisioning GUI:

[cols="1h,19a" width="95"]

|1 |Select Sentinel ⇒ Feature Configuration from the menu. |2 |Select Subscriber Data Lookup from the Feature dropdown. |3 |Click the Lookup Config tab. |4 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the subscriber data records stored in Cassandra.

  • If all subscriber data records are stored in Cassandra, then select (none) for all the scope options.

  • If no configuration exists at this level, click Add New. |5 |Change the Lookup type option to cassandra, and click Save.

==== Promotion buckets

To use the Cassandra-based provisioning service implementation as the default option for promotion buckets, in the provisioning GUI:

[cols="1h,15a" width="95"]

|1 |Select Sentinel ⇒ Promotion Configuration from the menu. |2 |Click the Config tab. |3 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the promotion bucket data stored in Cassandra.

  • If all promotion bucket data is stored in Cassandra, then select (none) for all the scope options.

  • If no configuration exists at this level, click Add New. |4 |Change the Default data source option to cassandra, and click Save.

To use the Cassandra-based provisioning service implementation only for specific promotion buckets, in the provisioning GUI:

[cols="1h,12a" width="95"]

|1 |Select Sentinel ⇒ Promotion Configuration from the menu. |2 |Click the Bucket Config tab. |3 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the scope the promotion bucket configuration data is stored at. |4 |Select one of the existing bucket configurations from the list, or click Add New to create a new one. |5 |Change the Data source option to cassandra, and click Save.

==== Configuring the Cassandra connection

If using any Cassandra-based provisioning service implementations, the provisioning server must be told how to connect to it.

[cols="1h,12a" width="95"]

|1 |Open a browser, and connect to the REM server where you have installed the Sentinel REM extension. |2 |Go to the Management section, and connect to the appropriate Rhino instance. |3 |Select Sentinel ⇒ Cassandra from the menu.

sentinel cassandra menu item

|4 |Click the Edit button. |5 |Fill in all the fields with the Cassandra connection information, and click Save.

sentinel cassandra configuration editing

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-configuration/provisioning-data-in-timesten.adoc

:here: provisioning/provisioning-configuration/ :idprefix: provisioning-data-in-timesten

:leveloffset: 1

= Provisioning Data in TimesTen :sortorder: 2

== Configuring JDBC provisioning lookup types and connections

Below are instructions for configuring JDBC provisioning lookup types and the connection to the TimesTen database.

=== Configuring JDBC provisioning lookup types

Sentinel comes with three JDBC-based provisioning service implementations: for subscriber data, promotion buckets, and home zones.

==== Subscriber data

To use the JDBC-based provisioning service implementation for subscriber data, in the provisioning GUI:

[cols="1h,19a" width="95"]

|1 |Select Sentinel ⇒ Feature Configuration from the menu. |2 |Select Subscriber Data Lookup from the Feature dropdown. |3 |Click the Lookup Config tab. |4 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the subscriber data records stored in TimesTen.

  • If all subscriber data records are in TimesTen, then select (none) for all the scope options.

  • If no configuration exists at this level, click Add New. |5 |Change the Lookup type option to dbQuery, and click Save.

=== Promotion buckets

To use the JDBC-based provisioning service implementation as the default option for promotion buckets, in the provisioning GUI:

[cols="1h,19a" width="95"]

|1 |Select Sentinel ⇒ Promotion Configuration from the menu. |2 |Click the Config tab. |3 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the promotion bucket data stored in TimesTen.

  • If all promotion bucket data is in TimesTen, then select (none) for all the scope options.

  • If no configuration exists at this level, click Add New. |4 |Change the Default data source option to dbquery, and click Save.

To use the JDBC-based provisioning service implementation only for specific promotion buckets, in the provisioning GUI:

[cols="1h,19a" width="95"]

|1 |Select Sentinel ⇒ Promotion Configuration from the menu. |2 |Click the Bucket Config tab. |3 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the scope the promotion bucket configuration data is stored at. |4 |Select one of the existing bucket configurations from the list, or click Add New to create a new one. |5 |Change the Data source option to dbquery, and click Save.

=== Home zones

To use the JDBC-based provisioning service implementation for home zones, in the provisioning GUI:

[cols="1h,19a" width="95"]

|1 |Select Sentinel ⇒ Feature Configuration from the menu. |2 |Select Home Zone from the Feature dropdown. |3 |Click the Config tab. |4 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the home zone zones stored in TimesTen.

  • If all home zone zones are in TimesTen, then select (none) for all the scope options.

  • If no configuration exists at this level, click Add New. |5 |Change the Zone lookup type option to dbQuery, and click Save.

=== Configuring TimesTen JDBC connection (using Tomcat server)

If using any JDBC-based provisioning service implementations, you’ll need to configure JNDI entries in your servlet container:

[cols="1h,19a" width="95"]

|1 |Install the TimesTen native client on the machine where from REM will be run. |2 |Copy ttjdbc6.jar from <timesten_instance_home>/lib/ to ${CATALINA_HOME}/lib/. |3 |Edit (or create) ${CATALINA_HOME}/bin/setenv.sh and add some custom environment settings:

# Specify the path to the lib directory of the local TimesTen client install
LD_LIBRARY_PATH=/opt/TimesTen/tt1121/lib
export LD_LIBRARY_PATH

# (Solaris 64bit only)
# If running on Solaris 64bit, specify the -d64 flag to run Tomcat using the 64bit JVM
# Otherwise, Tomcat won't be able to load the 64bit TimesTen libraries
#CATALINA_OPTS="-d64"

|4 |Edit ${CATALINA_HOME}/conf/server.xml, and add a data source definition in the GlobalNamingResources section (replacing username, password, and the connection URL with whatever applies for your TimesTen setup):

<!-- ... -->
  <GlobalNamingResources>
    <!-- ... -->
    <Resource name="SentinelDataSource" auth="Container"
              type="javax.sql.DataSource" driverClassName="com.timesten.jdbc.TimesTenDriver"
              url="jdbc:timesten:client:sentinelCS"
              username="username" password="password" maxActive="50" maxIdle="30"
              maxWait="-1"/>
  </GlobalNamingResources>
  <!-- ... -->

|5 |Edit (or create) ${CATALINA_HOME}/conf/Catalina/localhost/rem.xml, and add resource links for whichever services you need to connect to TimesTen:

<Context>
  <!-- For provisioning Subscriber Data records in TimesTen -->
  <ResourceLink name="jdbc/subscriberdata"
                global="SentinelDataSource"
                type="javax.sql.DataSource"/>

  <!-- For provisioning Promotion Buckets in TimesTen -->
  <ResourceLink name="jdbc/promotions"
                global="SentinelDataSource"
                type="javax.sql.DataSource"/>

  <!-- For provisioning HomeZone Zones in TimesTen -->
  <ResourceLink name="jdbc/homezone"
                global="SentinelDataSource"
                type="javax.sql.DataSource"/>
</Context>

|6 |Start/restart Tomcat.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/index.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: provisioning-web-interface

:leveloffset: 1

= Provisioning Web Interface :indexpage: :sortorder: 2

== Accessing the provisioning web interface

[NOTE] ==== Using Rhino Element Manager

The provisioning web interface appears as an extension inside the Rhino Element Manager (REM) web application. For general information on using REM, see the Rhino Element Manager User Guide.

To use the Sentinel provisioning web interface you will, at minimum, need to configure a Rhino instance in REM. ====

To access the Sentinel provisioning interface in REM:

[cols="1h,20a"]

|1 |Open a browser, and enter the URL of the REM server where the Sentinel REM extension has been installed (for example, http://localhost:8080/rem). |2 |Enter your REM login credentials (the default account credentials are emadm / password). |3 |Select Manage a Rhino Element. |4 |Connect to the Rhino instance where Sentinel is installed. |5 |Select one of the options from the Sentinel menu.

sentinel menu items

For help using each of the Sentinel management panels, see:

==== * Managing session plans * Managing Cassandra * Managing feature execution scripts * Managing subscriber data * Configuring features, services, Sentinel core, and promotions * Managing mappers * Managing plans, session types, and subscriptions * Managing normalization * Managing promotions * Managing correlation resource adaptor entities * Managing XCAP host mappings ====

TIP: For inline help using the provisioning web interface management pages, select one of the pages from the menu, and then click the help icon in the upper-right of the management screen.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-session-plans.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: managing-session-plans

:leveloffset: 1

= Managing Session Plans :sortorder: 1

== Associating feature execution scripts with points in the session

Use this management page to associate feature execution scripts with points in the session:

[cols="1h,20a"]

|1 |Choose a session plan from the dropdown list.

300

Click image to enlarge

The diagram for that session plan displays.

400

Click image to enlarge

|2 |Use the selection key widget at the top to scope the association to a particular Network, Session Type, Plan ID, or Subscription ID.

300

Click image to enlarge

|3 |Click a box in the session plan diagram to view the associated feature execution script (for the chosen selection key).

400

Click image to enlarge

Tip If there is no script associated at that point for the given selection key then the right panel will be blank.
Note When viewing a point with an existing script association, you can click open script in editor to jump to the feature execution script management page with that script open for editing.

|4 |To set or change the script associated with a particular point and selection key:

  • Click select different script.

    A list of feature execution scripts displays.

    400

    Click image to enlarge

  • Click a script to display its content.

  • Click Select to associate the selected script with that point and selection key.

|5 |To remove a script association:

  • Click remove 16px 5.

    A prompt asks you to confirm the removal.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-cassandra.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: managing-cassandra

:leveloffset: 1

= Managing Cassandra :sortorder: 2

TIP: The following options are only required if using an Apache Cassandra database for storing any Sentinel data.

== Configuration properties for Cassandra

The configuration options when using Cassandra should match the configuration properties of the hector-ra resource adaptor entity. For example:

image::sentinel-components/features/sip-features/sip-user-features/sentinel-em-cassandra-config.png[300, 300, link="images/sentinel-components/features/sip-features/sip-user-features/sentinel-em-cassandra-config.png"]

Click image to enlarge

[NOTE] ==== The basic connection details (hosts and keyspace) should be identical to those configured on the hector-ra entity.

The remaining options can be configured identically as well, or they may be different depending on your requirements.

Read the Hector and Cassandra documentation for more information. ====

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-feature-execution-scripts.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: managing-feature-execution-scripts

:leveloffset: 1

= Managing Feature Execution Scripts :sortorder: 3

== Changing, adding, and deleting feature execution scripts

To manage feature execution scripts:

[cols="1h,20a"]

|1 |Select a script from the list to view and edit it.

400

Click image to enlarge

|2 |You can make changes directly in the text editor, or click Switch to tree editor to edit the script as a condition tree.

400

Click image to enlarge

Note

In tree editor mode, when you highlight a statement, icons display to move it up or down, or delete it:

tree icons

You can also use Alt+j or Alt+k to move a statement up or down, and Alt+Del to delete it.
Tip You can switch back and forth between the text editor and tree editor, and changes in either will be persisted back and forth (as long as they are valid). |3 |To add a new script:

  • Click Add New.

    An Add New Feature Execution Script dialog box displays.

400

Click image to enlarge

  • Enter the New script name.

  • Write the script using the text editor or tree editor.

  • Click Save. |4 |* To delete the selected script, click Delete Script.

    A prompt asks you to confirm the deletion.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-subscriber-data.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: managing-subscriber-data

:leveloffset: 1

= Managing Subscriber Data :sortorder: 4

== Scoping, loading, editing, adding, and deleting subscriber data

To manage subscriber data:

[cols="1h,20a"]

|1 |Subscriber data can be scoped to network operator or session type using the selection widget at the top.

350

Click image to enlarge

|2 |To load a particular subscriber data record, enter the subscriber’s MISISDN and click Load.

The subscriber data record displays (if one can be found).

400

Click image to enlarge

|3 |To edit a subscriber data record:

  • Click Edit.

    The subscriber data record becomes editable.

  • Make your changes, and click Save.

|4 |To add a new subscriber data record:

  • Click Add New.

    Blank subscriber data fields display.

  • Enter all details, and click Save.

|5 |To delete the selected subscriber data record:

  • Click Delete.

    A prompt asks you to confirm the deletion.

  • Click OK to delete the subscriber data record.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/configuring-features-services-sentinel-core-promotions.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: configuring-features-services-sentinel-core-and-promotions

:leveloffset: 1

= Configuring Features, Services, Sentinel Core and Promotions :sortorder: 6

You can use the configuration management pages (Feature Configuration, Service Configuration, Sentinel Core Configuration, and Promotion Configuration) to view, edit, add, and delete configuration data.

[cols="1h,20a"]

|1 |Choose a feature from the dropdown list.

300

Click image to enlarge

Tabs display for the configuration types available for that feature.

450

Click image to enlarge

|2 |Use the selection key widget at the top to scope the association to a particular Network, Session Type, Plan ID, or Subscription ID.

300

Click image to enlarge

|3 |Click a tab for the type of configuration (in the example, Announcements Config, Resource Config, and so on).

Configured entries display.

450

Click image to enlarge

To view or edit the details of an existing entry:

  • Click an entry in the list at left.

  • Enter the details at right.

Tip

  • Click a blue question mark icon to display help for a particular field:

tooltip

  • Click Save.

|4 |To add a new entry:

  • Click Add New.

    Blank fields display.

  • Enter details, and click Save. |5 |To delete a selection:

  • Click Delete.

    A prompt asks you to confirm deleting.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-mappers.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: managing-mappers

:leveloffset: 1

= Managing Mappers :sortorder: 7

== Configuring mappings

You can use this management page to view, add, and delete mappers and mapping sets.

[cols="1s,3a"]

|To…​ |Do this:

|View mappings

|* Select one of the Mapper Sets at left.

+ Configured Mappings display at right.

300

Click image to enlarge

|Add a mapping

|* Click Add (in the Mappings pane).

+ Fields pop up for you to add mapping details.

add mapping

  • Enter the Mapping Name and, optionally, the Execution Point, Session Type, and Plan ID for the mapping.

  • Click Add (to save and add another mapping) or Add and Close (to save and finish adding mappings).

|Delete mappings

|* Click the checkboxes to select mappings you want to delete.

  • Click Delete (in the Mappings pane).

    A prompt displays for you to confirm deleting the selected mappings.

|Add a mapper set

|* Select a platform operator from the Mapper Sets list.

  • Click Add (in the Mapper Sets pane).

    A popup prompts you to select a Network Operator.

add mapping set

  • Select the network operator (or none to create a platform-level mapper set).

  • Click Add.

|Delete a mapper set

|* Click to select the mapper set you want to delete.

  • Click Delete (in the Mapper Sets pane).

    A prompt displays for you to confirm deleting the selected mapper set.

|Publish a mapper set

|* Click to select the set you want to publish.

  • Click Publish (in the Mapper Sets pane).

    The next time Sentinel accesses this mapper set it will pick up any mapping changes you have made.

Important Before any mapping changes can take effect, Sentinel must be notified by publishing the mapping sets. (If Rhino is restarted, Sentinel will also pick up any changes.)

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-plans-session-types-and-subscriptions.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: managing-plans-session-types-and-subscriptions

:leveloffset: 1

= Managing Plans, Session Types and Subscriptions :sortorder: 8

== Scoping configuration data as part of the selection key

You can use these management pages to view, add, edit, and delete plans, session types, and subscriptions — all of which let you scope Sentinel configuration data as part of the Sentinel configuration key.

[cols="1h,20a"]

|1 |Select a network operator to view a list of plans, session types, or subscriptions configured for them; and select a particular plan, session type, or subscription to view its description.

400

Click image to enlarge

|2 |To add a plan, session type, or subscription for the selected operator:

  • Click Add New.

    Blank Name and Description fields display.

  • Enter a Name and Description for the plan, session type, or subscription.

  • Click Save.

|3 |To delete the selected plan, session type, or subscription:

  • Click Delete.

    A prompt asks you to confirm deleting.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-normalization.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: managing-normalization

:leveloffset: 1

= Managing Normalization :sortorder: 9

== Scoping and configuring normalization

You can use this management page to add, edit, or delete normalization data.

[cols="1h,20a"]

|1 |* Scope normalization data to the Network, Session Type, Plan ID, or Subscription ID, using the selection widget at the top.

300

Click image to enlarge

If no normalization configuration exists at the selected level, an Add New button displays.

300

Click image to enlarge

(Otherwise, the existing normalization configuration displays.)

|2 |To add normalization data:

  • Click Add New.

    Normalization data entry fields display.

450

Click image to enlarge

  • Enter details, and click Save.

|3 |To edit normalization data:

  • Make your changes and click Save.

|4 |To delete normalization data:

  • Click Delete.

    A prompt asks you to confirm the deletion.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-promotions.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: managing-promotions

:leveloffset: 1

= Managing Promotions :toc: macro :toclevels: 4 :toc-title: On this page…​ :sortorder: 10

toc::[]

== What are promotion tables and buckets?

Promotion tables configure active promotions, the conditions that apply, and the order in which to execute them.

Promotion buckets hold a user’s available and reserved units for a specific promotion.

== Configuring promotions

=== Scoping a promotion configuration

Promotion configurations can be scoped to the Network, Session Type, Plan ID, or Subscription ID, using the selection widget at the top.

image::sentinel-components/features/sip-features/sip-user-features/selection-widget.png[300, 300, link="images/sentinel-components/features/sip-features/sip-user-features/selection-widget.png"]

Click image to enlarge

=== Adding, editing, and deleting a promotion configuration

To manage promotion configurations:

[cols="1h,19a" width="95"]

|1 |* Click the Config tab.

+ If no promotion configuration exists at the selected level, an Add New button displays.

+ 300

+ Click image to enlarge

+ (Otherwise, the existing promotion configuration displays.)

+ 450

+ Click image to enlarge

|2 |To add a promotion configuration:

  • Click Add New.

    Promotion configuration entry fields display.

  • Enter details.

  • Click Save.

|3 |To edit a promotion configuration:

  • Make your changes.

  • Click Save.

|4 |To delete a promotion configuration:

  • Click Delete.

    A prompt asks you to confirm the deletion.

=== Editing, adding, and deleting promotion bucket configurations

To manage promotion bucket configurations:

[cols="1h,20a"]

|1 |* Click the Bucket Config tab.

+ A list of bucket configurations displays.

|2 |To edit a promotion bucket configuration:

  • Click to select it.

    The bucket name and data source display.

    400

    Click image to enlarge

  • Select the new data source.

  • Click Save.

|3 |To add a new promotion bucket configuration:

  • Click Add New.

    Blank Bucket name and Data source fields display.

  • Enter the new name, select a data source.

  • Click Save.

|4 |To delete the selected promotion bucket configurations:

  • Click Delete.

    A prompt asks you to confirm the deletion.

=== Editing, adding, and deleting SQL configurations

To manage SQL configurations for promotions:

[cols="1h,19a" width="95"]

|1 |* Click the SQL Config tab.

+ If there is no SQL configuration, an Add New button displays; otherwise existing SQL configuration data displays.

+ 400

+ Click image to enlarge

|2 |To add an SQL configuration:

  • Click Add New.

  • Blank entry fields display.

  • Enter details.

  • Click Save.

|3 |To edit an SQL configuration:

  • Enter details.

  • Click Save.

|4 |To delete the selected SQL configuration:

  • Click Delete.

    A prompt asks you to confirm the deletion.

=== Editing, adding, and deleting promotion tables

To manage promotion tables:

[cols="1h,20a"]

|1 |* Click the Promotion Tables tab.

+ A list of promotion tables displays.

+ 400

+ Click image to enlarge

|2 |To add a promotion table:

  • Click Add.

    A new promotion table displays at the top of the list.

    new promotion

|3 |To edit a promotion table:

  • Click a field to make it editable.

    edit promotion

  • Make your changes.

  • Click Save.

|4 |To delete a promotion table:

  • Click delete.

    A prompt asks you to confirm the deletion.

=== Loading, editing, adding, and deleting promotion buckets

To manage promotion buckets:

[cols="1h,20a"]

|1 |* Click the Promotion Buckets tab.

|2 |To load a promotion bucket:

  • Enter the SubscriberId and BucketName.

  • Click Load.

    That promotion bucket displays.

    300

    Click image to enlarge

|3 |To edit the loaded promotion bucket:

  • Click Edit.

    That bucket’s details become editable.

  • Make your changes, and click Save.

|4 |To delete the loaded promotion bucket:

  • Click Delete.

    A prompt asks you to confirm the deletion.

|5 |To add a new promotion bucket:

  • Click Add New.

    Fields display for you to enter details for the new promotion bucket.

    300

    Click image to enlarge

  • Enter the SubscriberId, BucketName, and other details.

  • Click Save.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-correlation-resource-adaptor-entities.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: managing-correlation-resource-adaptor-entities

:leveloffset: 1

= Managing Correlation Resource Adaptor Entities :sortorder: 11

== Configuring Correlation Resource Adaptor Entities

NOTE: For general information on the Correlation RA and its use in Sentinel, please see Correlation Resource Adaptor.

To configure correlation resource adaptor entities:

[cols="1h,20a"]

|1 |* Select an RA Entity from the drop-down list.

+ Resource adaptor entity correlation details display.

+ 400

+ Click image to enlarge

  • Enter correlation details, and click Save.

Tip You can configure and manage resource adaptor entities by clicking on the links to the right of the RA Entity dropdown list.

|2 |* Click the ID Pools tab.

+ Corellation ID pools display.

|3 |* Click an ID pool to display its details.

+ ID pool correlation details display.

+ 450

+ Click image to enlarge

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-xcap-host-mappings.adoc

:here: provisioning/provisioning-web-interface/ :idprefix: managing-xcap-host-mappings

:leveloffset: 1

= Managing XCAP Host Mappings :sortorder: 12

== Changing, adding, and deleting XCAP host mappings

To manage XCAP host mappings:

[cols="1,3a" width="80"]

|To…​ |Do this:

|View and edit an XCAP host mapping |* Select from the XCAP Host Mappings list.

+ Mapping details display.

+ 450

+ Click image to enlarge

  • Make any changes.

  • Click Save.

|Add a new XCAP host mapping

|* Click Add New.

+ An empty XCAP host mapping displays.

+ 200

+ Click image to enlarge

  • Enter details.

  • Click Save.

| Delete the selected XCAP host mapping.

|* Click Delete Mapping.

+ A prompt asks you to confirm the deletion.

  • Click OK.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-auditing.adoc

:here: provisioning/ :idprefix: provisioning-auditing

:leveloffset: 1

= Provisioning Auditing :sortorder: 5

The Sentinel provisioning system audits every write operation (create, update, and delete) that goes through it.

By default, the audit messages are written to the main REM or Apache Tomcat log.

To write the audit messages out to a separate, CSV-formatted file, add the following settings to the REM or Tomcat log4j2.properties file.

---- logger.audit.name=sentinel.audit logger.audit.level=INFO logger.audit.additivity=false logger.audit.appenderRef.audit.ref=AUDIT

appender.AUDIT.type = RollingFile appender.AUDIT.name = AUDIT appender.AUDIT.fileName = ${rem.home}/sentinel-audit.log appender.AUDIT.layout.type = PatternLayout appender.AUDIT.layout.Pattern = "%d{yyyy-MM-dd HH:mm:ss,SSS}", "%c{1}", %m%n appender.AUDIT.maxFileSize = 10MB appender.AUDIT.maxBackupIndex=10 ----

If you wish to disable the audit messages completely then add the following settings to the REM or Tomcat log4j.properties file.

---- logger.audit.level=NONE ----

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/xcap-api.adoc

:here: provisioning/ :idprefix: using-the-xcap-api

:leveloffset: 1

= Using the XCAP API :sortorder: 6

The Sentinel REM extension provides a very basic XCAP API. More extensive XCAP server functionality is available in the Sentinel VoLTE product, but custom XCAP server functionality can be added fairly easily with the Sentinel SDK.

[TIP] ==== Using Rhino Element Manager

To use the Sentinel XCAP API, you will (at minimum) need to configure a Rhino instance using the Rhino Element Manager (REM). For general information on using REM, please see the Rhino Element Manager User Guide. ====

Below are details on:

==== * Managing XCAP host mappings * Accessing the XCAP API * Adding XCAP services ====

== Managing XCAP host mappings

XCAP host mappings control which Rhino instance, REM user account are used when handling an XCAP request.

For managing XCAP host mappings using the provisioning web interface, see Managing XCAP host mappings.

== Accessing the XCAP API

To access the XCAP API:

[cols="1h,20a"]

|1 |Ensure the Sentinel REM extension is installed in REM. |2 |Start REM. |3 |The base XCAP URI is http://localhost:8080/rem/sentinel/xcap (replace localhost with some other hostname if REM is not being run locally).

The only resource available in the XCAP server provided with Sentinel is the mandatory xcap-caps index at http://localhost:8080/rem/sentinel/xcap/xcap-caps/index.

Note Access is not restricted as it is assumed XCAP requests have passed through a separate XCAP authentication proxy (AP) first.

Requests are filtered though, so only requests using a hostname that matches a valid XCAP host mapping configuration in REM will be accepted.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-alarms.adoc

:here: :idprefix: sentinel-alarms

:leveloffset: 1

= Sentinel Alarms :sortorder: 5

== Alarms raised by Sentinel

[cols="1*a"]

|

[cols="1*a"]

|

[cols="1*a"]

|

NOTE: Alarms may also be raised by the other components used by Sentinel (such as SIS, DB Query RA, and CDR RA).

== Threshold alarms

Sentinel produces a variety of statistics that can be used to configure threshold alarms in Rhino

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/index.adoc

:here: charging-information/ :idprefix: charging-information

:leveloffset: 1

= Charging Information :indexpage:

Charging Information describes the format and content of CDR files, and the information present in Diameter Ro.

== Topics

* CDR Formats — describes the formats used for CDRs * Working with CDRs — describes tooling to extract the content of CDRs * Ro Interface AVPs — describes the population of AVPs on the Ro interface * Charging Content AVPs — describes the populated AVPs for both online and offline charging * Interim CDRs — describes Interim CDRs for offline charging * Sizing AVP CDRs — describes sizing requirements when using AVP CDRs

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/cdr-formats/index.adoc

:here: charging-information/cdr-formats/ :idprefix: cdr-formats

:leveloffset: 1

= CDR Formats :indexpage:

Sentinel supports two CDR formats "out of the box". These are the AVP CDR format, and the legacy format.

Note that Sentinel can be configured to use a user provided CDR format, or even no CDRs.

== AVP CDRs

An AVP CDR is an OpenCloud defined CDR that contains AVPs. This type of CDR is consistent with the approaches used in Diameter Ro and Diameter Rf interfaces. An AVP CDR contains AVPs that are standardised (e.g. 3GPP and IETF), or non-standardised (e.g. product specific or project specific).

AVP CDRs can almost be considered an "on-disk" form of the content contained in the Rf interface.

AVP CDRs are used by default in the Sentinel SIP service. The Sentinel SIP service can be configured to use the legacy format.

== Legacy CDRs

A legacy CDR is an OpenCloud defined CDR that is used in the Sentinel product set prior to (and during) the introduction of AVP CDRs. The product continues support for this format so that customers who use this format do not need migrate.

Legacy CDRs remain in use by the Sentinel SS7 and Sentinel Diameter services.

== Topics

* AVP CDR Format — describes the formats used for AVP CDRs * Legacy CDR Format — describes the format used for Legacy CDRs

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/cdr-formats/avp-cdr-format.adoc

:here: charging-information/cdr-formats/ :idprefix: avp-cdr-format

:leveloffset: 1

= AVP CDR Format

AVP CDRs have logical content, and an on-disk format.

== Logical content

Each CDR inside a CDR file has logical content. We use a BNF syntax to describe this logical content.

---- CDR ::= [ Subscription-Id ] [ IMS-Information ] [ User-Equipment-Info ] *[ Multiple-Services-Credit-Control ] [ OC-Call-Type ] [ OC-Service-Type ] [ OC-Charging-Result ] *[ OC-OCS-Session-Id ] [ OC-OCS-Session-Termination-Cause ] [ OC-Sentinel-Error ] *[ OC-Charging-Instance ] [ OC-Event-Id ] [ OC-Call-Id ] [ OC-End-Session-Cause ] [ OC-Session-Start-Time ] [ OC-Session-Established-Time ] [ OC-Session-End-Time ] [ OC-OCS-Destination-Realm ] [ OC-Sentinel-Selection-Key ] *[ OC-Play-Announcement-Id ] *[ AVP ] ----

Logically this means that an individual CDR has optional content. It may have zero or one Subscription-Id AVP, zero or one IMS-Information AVP, and so-on. It may have zero or more OC-Play-Announcement-Id AVPs, and zero or more OC-OCS-Session-Id AVPs, and so-on.

A CDR inside the CDR file is not an AVP. It is a protobuf record, and as such may contain additional "root" AVPs. So, for example an application may use the format, but add a LCS-Information AVP, or custom AVP.

You could consider each CDR to be roughly equivalent to the Service-Information AVP, yet more flexible/extensible regarding its content. This is because the Service-Information AVP is essentially closed for extension by non-3GPP groups.

To view the population of AVPs in use, refer to Charging Content AVPs

== On disk format

AVP CDRs are written using Google protocol buffers (protobuf).

An AVP CDR file has a protobuf schema. This schema allows any AVP to be written to a CDR.

---- syntax = "proto2"; package com.opencloud.cdrformat;

message AvpCdr {

repeated AVP avps = 1;

message AVP { required bytes avpData = 1; // The Diameter binary encoded AVP data required string interfaceName = 2; // The interface which the AVP is being written out as, e.g "Rf", "Ro" required string specRevision = 3; // E.g. "vcb0" optional string avpName = 4; }

} ----

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/cdr-formats/legacy-cdr-format.adoc

:here: charging-information/cdr-formats/ :idprefix: legacy-cdr-format

:leveloffset: 1

= Legacy CDR Format :toc: macro :toclevels: 4 :toc-title: On this page…​

The Legacy CDR format has an on-disk format defined using Google protocol buffers (aka protobuf).

There is a common "types definition" schema file that is used by multiple Sentinel Services for their CDRs. These types are called "base types". Each Sentinel Service then defines its own CDRs using these types and defining its own types.

toc::[]

== Base types

The base types are used in CDRs for Sentinel SS7, Sentinel Diameter Mediation.

---- package com.opencloud.sentinel.cdr;

message CdrSessionCounters { repeated CdrSessionCounterAccess counters = 1; }

message CdrSessionCounterAccess { required string subscriberId = 1; required string bucketName = 2;

optional int64 cumulativeRequestedUnits = 3; optional int64 cumulativeGrantedUnits = 4; optional int64 cumulativeSentUsedUnits = 5; optional int64 cumulativeCommittedUsedUnits = 6; optional int64 cumulativeRequestedRefundUnits = 7; optional int64 cumulativeGrantedRefundUnits = 8;

repeated CdrSessionSubCounterAccess subCounters = 9; }

message CdrSessionSubCounterAccess { required string subCounterId = 1;

optional int64 cumulativeRequestedUnits = 3; optional int64 cumulativeGrantedUnits = 4; optional int64 cumulativeSentUsedUnits = 5; optional int64 cumulativeCommittedUsedUnits = 6; optional int64 cumulativeRequestedRefundUnits = 7; optional int64 cumulativeGrantedRefundUnits = 8;

repeated CdrSessionSubCounterAccess subCounters = 9; }

message Time { required int64 milliseconds_since_epoch = 1; required sint32 zoneoffset_minutes = 2; }

enum SentinelError { None = 1; OcsTimeout = 2; OcsCommunicationFailure = 3; SentinelOverload = 4; ProtocolError = 5; InternalError = 6; MappingError = 7; OtherError = 8; }

----

== Sentinel SS7 Service CDR format

The Sentinel SS7 service defines two CDR formats, one for CAP calls, and the other for CAP3 SMS.

=== CAP Calls

CAP call use the following format for its CDR files (out of the box).

---- package com.opencloud.sentinel.cdr;

import "com/opencloud/sentinel/cdr/base-cdr-types.proto";

message Ss7CallCdr {

optional string subscriber = 1; optional int32 initiatingDialogId = 2 [default = -1]; optional Time eventInitiated = 3; optional Time sessionInitiated = 4; optional Time sessionEstablished = 5; optional Time sessionEnded = 6; optional CallType callType = 7; optional string callingPartyNumber = 8; optional string calledPartyNumber = 9; optional string mscNumber = 10; optional int32 serviceKey = 11 [default = -1]; optional ConnectCause connectCause = 12; optional int32 releaseCause = 13; optional sint32 chargingResult = 14 [default = -1]; optional int64 cumulativeReported = 15; optional CdrSessionCounters sessionCounters = 21; repeated int32 ocsLatencySamples = 23 [packed=true]; repeated int32 announcementIDs = 25; optional int64 callReferenceNumber = 26; optional sint32 bearerService = 27 [default = -1]; optional sint32 teleService = 28 [default = -1]; optional ServiceType serviceType = 29 [default = Unknown]; optional SentinelError sentinelError = 30 [default = None];

optional string sentinelSelectionKey = 31;

repeated string ocsSessionIDs = 32;

repeated CallInformationReport callInformationReports = 33;

optional bool creditHasBeenReauthorized = 34; optional int32 ocsSessionTerminationCause = 35;

extensions 50 to max;

enum CallType { MOC = 1; MOC_3RDPTY = 2; MTC = 3; MFC = 4; MOSMS = 5; MTSMS = 6; GPRS = 7; ACCOUNT_INQUIRY = 8; EMERGENCY_CALL = 9; }

enum ServiceType { Unknown = 1; Voice = 2; Data = 3; Fax = 4; Video = 5; }

enum ConnectCause { UnknownCause = 1; APartyAbandoned = 2; NoAnswer = 4; UserBusy = 5; RouteSelectFailure = 6; Answer = 7; Abort = 8; Error = 9; }

message CallInformationReport { optional int32 legId = 1; optional int32 callAttemptElapsedTime = 2; optional int32 callConnectedElapsedTime = 3; optional Time callStopTime = 4; optional int32 releaseCause = 5; } } ----

=== CAP3 SMS

CAP3 SMS support ses the following format for its CDR files (out of the box).

---- package com.opencloud.sentinel.cdr;

import "com/opencloud/sentinel/cdr/base-cdr-types.proto";

message Ss7SmsCdr {

optional string subscriber = 1; optional int32 initiatingDialogId = 2 [default = -1]; optional Time eventInitiated = 3; optional Time sessionInitiated = 4; optional Time sessionEstablished = 5; optional Time sessionEnded = 6; optional SmsType callType = 7; optional string callingPartyNumber = 8; optional string calledPartyNumber = 9; optional string mscNumber = 10; optional int32 serviceKey = 11 [default = -1]; optional int32 releaseCause = 13; optional sint32 chargingResult = 14 [default = -1]; optional int64 cumulativeReported = 15; optional CdrSessionCounters sessionCounters = 21; repeated int32 ocsLatencySamples = 23 [packed=true]; optional int64 smsReferenceNumber = 26; optional SentinelError sentinelError = 30 [default = None];

optional string sentinelSelectionKey = 31;

repeated string ocsSessionIDs = 32;

optional int32 ocsSessionTerminationCause = 35;

extensions 50 to max;

enum SmsType { MOSMS = 1; MTSMS = 2; }

} ----

== Sentinel Diameter Mediation Service CDR format

The Sentinel Diameter Mediation service defines a CDR format.

---- package com.opencloud.sentinel.cdr;

import "com/opencloud/sentinel/cdr/base-cdr-types.proto";

message DiameterChargingCdr {

optional string subscriber = 1; optional int64 initiatingRequestId = 2 [default = -1]; optional Time eventInitiated = 3; optional Time sessionInitiated = 4; optional Time sessionEnded = 5; optional CdrSessionCounters sessionCounters = 6;

repeated int32 ocsLatencySamples = 19 [packed=true]; optional string clientSessionId = 20; repeated string ocsSessionIDs = 21;

optional string sentinelSelectionKey = 22;

extensions 50 to max;

} ----

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/charging-content-avps/index.adoc

:here: charging-information/charging-content-avps/ :idprefix: charging-content-avps

:leveloffset: 1

= Charging Content AVPs :indexpage: :toc: macro :toclevels: 4 :toc-title: On this page…​

The population of AVPs for Sentinel SIP is described on this page. A definition of the AVPs used for the Sentinel Express product is provided on Sentinel AVP definitions.

toc::[]

== Detecting Online Charging

The OC-Charging-Result AVP in a CDR indicates whether online (Diameter Ro) charging was used for a session. This may be used to determine if further action is needed when processing CDRs offline.

* An OC-Charging-Result value of -1 means that online charging was not used for the session. * Otherwise the value is set to the Diameter Result-Code AVP value.

== Populated AVPs in the Multiple-Services-Credit-Control AVP

The Multiple-Services-Credit-Control AVP is of type grouped, and is defined in RFC 4006. Section 7.1.4 of 3GPP TS 32.299 defines it with additional 3GPP specific parameters and states some IETF parameters are not used in the 3GPP.

[cols="2,3,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | Requested-Service-Unit | IETF RFC 4006 | No | Yes | No | Used in the CCR. The CDR represents this information in the OC-Session-Counter AVP | Used-Service-Unit | IETF RFC 4006 and 3GPP TS 32.299 | No | Yes | No | Used in the CCR according to Populated AVPs in the Used-Service-Unit AVP. The CDR represents this information in the OC-Session-Counter AVP. | Service-Identifier | IETF RFC 4006 | Yes | Yes | Yes | For Mobile Originating, Mobile Terminating, Mobile Forwarded, and Network Initiated attempts, this AVP is configurable in the "Determine Charging" feature. For Immediate Event Charging the AVP has the value 50. | Rating-Group | IETF RFC 4006 and 3GPP TS 32.299 v12.11.0 section 7.1.10 | No | Yes | No | This AVP is configurable in the "Determine Charging" feature. | Reporting-Reason | 3GPP TS 32.299 v12.11.0 section 7.2.175 | No | Yes | No | | Trigger | 3GPP TS 32.299 v12.11.0 section 7.2.235 | No | No | No | | PS-Furnish-Charging-Information | 3GPP TS 32.299 v12.11.0 section 7.2.157 | No | No | No | | Refund-Information | 3GPP TS 32.299 v12.11.0 section 7.2.171 | No | No | No | | AF-Correlation-Information | 3GPP TS 32.299 v12.11.0 section 7.2.11 | No | No | No | | Envelope | 3GPP TS 32.299 v12.11.0 section 7.2.59 | No | No | No | | Envelope-Reporting | 3GPP TS 32.299 v12.11.0 section 7.2.61 | No | No | No | | Time-Quota-Mechanism | 3GPP TS 32.299 v12.11.0 section 7.2.228 | No | No | No | | Service-Specific-Info | 3GPP TS 32.299 v12.11.0 section 7.2.195 | No | Yes | No | This AVP is configurable in the "Determine Charging" feature. | QoS-Information | 3GPP TS 29.212 | No | No | No |

The BNF syntax for this AVP in 32.299 v12.11.0 is as follows:

---- <Multiple-Services-Credit-Control> ::= < AVP Header: 456 >

[ Granted-Service-Unit ] // not used in CCR [ Requested-Service-Unit ] * [ Used-Service-Unit ] [ Tariff-Change-Usage ] // not used in 3GPP * [ Service-Identifier ] [ Rating-Group ] * [ G-S-U-Pool-Reference ] // not used in CCR [ Validity-Time ] // not used in CCR [ Result-Code ] // not used in CCR [ Final-Unit-Indication ] // not used in CCR [ Time-Quota-Threshold ] // not used in CCR [ Volume-Quota-Threshold ] // not used in CCR [ Unit-Quota-Threshold ] // not used in CCR [ Quota-Holding-Time ] // not used in CCR [ Quota-Consumption-Time ] // not used in CCR * [ Reporting-Reason ] [ Trigger ] [ PS-Furnish-Charging-Information ] [ Refund-Information ] * [ AF-Correlation-Information] * [ Envelope ] [ Envelope-Reporting ] [ Time-Quota-Mechanism ] * [ Service-Specific-Info ] [ QoS-Information ] * [ AVP ] // not used in 3GPP ----

=== Populated AVPs in the Used-Service-Unit AVP

The Used-Service-Unit AVP is defined in IETF RFC 4006, and then its BNF is modified slightly in 3GPP TS 32.299 section 7.1.9.

[cols="2,3,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | Reporting-Reason | 3GPP TS 32.299 v12.11.0 section 7.2.175 | No | No | No | | Tariff-Change-Usage | IETF RFC 4006 | No | No | No | | CC-Time | IETF RFC 4006 | No | Yes | No | Used by default as the unit type for SIP Sessions | CC-Money | IETF RFC 4006 | No | No typically | No | Not used out-of-the-box for Sentinel SIP | CC-Total-Octets | IETF RFC 4006 | No | Not typically | No | Not used out-of-the-box for Sentinel SIP | CC-Input-Octets | IETF RFC 4006 | No | Not typically | No | Not used out-of-the-box for Sentinel SIP | CC-Output-Octets | IETF RFC 4006 | No | Not typically | No |Not used out-of-the-box for Sentinel SIP | CC-Service-Specific-Units | IETF RFC 4006 | Not typically | No | Is used in Sentinel IP-SM-GW

The 3GPP definition (in v12.11.0) is

---- <Used-Service-Unit> ::= < AVP Header: 446 > [ Reporting-Reason ] [ Tariff-Change-Usage ] [ CC-Time ] [ CC-Money ] // not used in 3GPP [ CC-Total-Octets ] [ CC-Input-Octets ] [ CC-Output-Octets ] [ CC-Service-Specific-Units ] *[ Event-Charging-TimeStamp ] *[ AVP ] // not used in 3GPP ----

== Populated AVPs in the Service-Information AVP

The Service-Information AVP is defined in 3GPP TS 32.299 v12.11.0. It is a grouped AVP. This table lists the AVPs grouped within Service-Information and how the product populates them.

[cols="2,3,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | SMS-Information | 32.299 v12.11.0 section 7.2.211 | Yes | Yes | Yes | The Sentinel IP-SM-GW product populates this AVP | MMTel-Information | 32.299 v12.11.0 section 7.2.111 | Yes | Yes | Yes | The Sentinel VoLTE product populates this AVP | Subscription-Id | IETF RFC 4006 | Yes | No | Yes | 3GPP TS 32.299 v12.11.0 states that it should be set on the Rf interface, not the Ro interface (see section 7.2.149) | AoC-Information | 32.299 v12.11.0 section 7.2.15 | No | No | No | Sentinel does not implement the advice of charge service out-of-the-box | PS-Information | 32.299 v12.11.0 section 7.2.158 | No | No | Yes | PS-Information AVP contains EPC layer information. It is only added in ACRs as a means of sending the IMEI in the User-Equipment-Information AVP. | IMS-Information | 32.299 v12.11.0 section 7.2.77 | Yes | Yes | Yes | See the IMS-Information table for further details | MMS-Information | 32.299 v12.11.0 section 7.2.110 | No | No | No | Sentinel does not implement any MMS node roles out-of-the-box | LCS-Information | 32.299 v12.11.0 section 7.2.89 | No | No | No | | PoC-Information | 32.299 v12.11.0 section 7.2.144 | No | No | No | Sentinel does not implement the PoC service out-of-the-box | MBMS-Information | 32.299 v12.11.0 section 7.2.99 | No | No | No | Sentinel does not implement the MBMS service out-of-the-box | SMS-Information | 32.299 v12.11.0 section 7.2.211 | No | No | No | Sentinel does not implement the SMS service out-of-the-box | VCS-Information | 32.299 v12.11.0 section 7.2.242A | No | No | No | | MMTel-Information | 32.299 v12.11.0 section 7.2.111 | Yes | Yes | Yes | | ProSe-Information | 32.299 v12.11.0 section 7.2.154I | No | No | No | | Service-Generic-Information | 32.299 v12.11.0 section 7.2.191 | No | No | No | | IM-Information | 32.299 v12.11.0 section 7.2.69 | No | No | No | Sentinel does not implement IM services out-of-the-box | DCD-Information | 32.299 v12.11.0 section 7.2.50 | No | No | No |

The BNF for the AVP is defined in section 7.2.149. It is as follows:

---- Service-Information :: = < AVP Header: 873>

* [ Subscription-Id ] [ AoC-Information ] [ PS-Information ] [ IMS-Information ] [ MMS-Information ] [ LCS-Information ] [ PoC-Information ] [ MBMS-Information ] [ SMS-Information ] [ VCS-Information ] [ MMTel-Information ] [ ProSe-Information ] [ Service-Generic-Information ] [ IM-Information ] [ DCD-Information ] ----

== Populated AVPs in the PS-Information AVP

The PS-Information AVP is defined in 3GPP TS 32.299 v12.11.0. It is a grouped AVP. This table lists the AVPs grouped within PS-Information and how the product populates them.

[cols="2,3,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | User-Equipment-Info | IETF RFC 4006 | No | No | Yes | The IMEI is used rather than the IMEISV, and the User-Equipment-Type AVP is set to IMEISV. For CCRs and CDRs this AVP is present as a top level AVP.

The BNF for the AVP is defined in section 7.2.158. It is as follows:

---- PS-Information :: = < AVP Header: 874>

[ 3GPP-Charging-Id ] [ PDN-Connection-Charging-ID ] [ Node-Id ] [ 3GPP-PDP-Type ] * [ PDP-Address ] [ PDP-Address-Prefix-Length ] [ Dynamic-Address-Flag ] [ Dynamic-Address-Flag-Extension ] [ QoS-Information ] * [ SGSN-Address ] * [ GGSN-Address ] * [ TDF-IP-Address ] * [ SGW-Address ] * [ ePDG-Address ] [ CG-Address ] [ Serving-Node-Type ] [ SGW-Change ] [ 3GPP-IMSI-MCC-MNC ] [ IMSI-Unauthenticated-Flag ] [ 3GPP-GGSN-MCC-MNC ] [ 3GPP-NSAPI ] [ Called-Station-Id ] [ 3GPP-Session-Stop-Indicator ] [ 3GPP-Selection-Mode ] [ 3GPP-Charging-Characteristics ] [ Charging-Characteristics-Selection-Mode ] [ 3GPP-SGSN-MCC-MNC ] [ 3GPP-MS-TimeZone ] [ Charging-Rule-Base-Name ] [ ADC-Rule-Base-Name ] [ 3GPP-User-Location-Info ] [ User-Location-Info-Time ] [ User-CSG-Information ] [ Presence-Reporting-Area-Information ] [ 3GPP2-BSID ] [ TWAN-User-Location-Info ] [ 3GPP-RAT-Type ] [ PS-Furnish-Charging-Information ] [ PDP-Context-Type ] [ Offline-Charging ] * [ Traffic-Data-Volumes ] * [ Service-Data-Container ] [ User-Equipment-Info ] [ Terminal-Information ] [ Start-Time ] [ Stop-Time ] [ Change-Condition ] [ Diagnostics ] [ Low-Priority-Indicator ] [ MME-Number-for-MT-SMS ] [ MME-Name ] [ MME-Realm ] [ Logical-Access-ID ] [ Physical-Access-ID ] [ Fixed-User-Location-Info ] [ CN-Operator-Selection-Entity ] ----

=== Populated AVPs in the IMS-Information AVP

The IMS-Information AVP is defined in 3GPP TS 32.299 v12.11.0. It is a grouped AVP. This table lists the AVPs grouped within IMS-Information and how the product populates them.

[cols="2,3,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | Event-Type | 32.299 v12.11.0 section 7.2.65 | Yes | Yes | Yes | | Role-Of-Node | 32.299 v12.11.0 section 7.2.177 | Yes | Yes | Yes | Sessions with sescase of orig and orig_cdiv are in ORIGINATING_ROLE | Node-Functionality | 32.299 v12.11.0 section 7.2.113 | Yes | Yes | Yes | Set to value 6 as AS | User-Session-Id | 32.299 v12.11.0 section 7.2.242 | Yes | Yes | Yes | Set to the Call-Id for the initial request | Outgoing-Session-Id | 32.299 v12.11.0 section 7.2.128A | No | No | No | | Session-Priority | 29.229 | Yes | Yes | Yes | Set to value 2 | Calling-Party-Address | 32.299 v12.11.0 section 7.2.33 | Yes | Yes | Yes | | Called-Party-Address | 32.299 v12.11.0 section 7.2.32 | Yes | Yes | Yes | | Called-Asserted-Identity | 32.299 v12.11.0 section 7.2.31 | Yes | Yes | Yes | | Number-Portability-Routing-Information | 32.299 v12.11.0 section 7.2.120 | No | No | No | | Carrier-Select-Routing-Information | 32.299 v12.11.0 section 7.2.34 | No | No | No | | Alternate-Charged-Party-Address | 32.299 v12.11.0 section 7.2.12 | No | No | No | | Requested-Party-Address | 32.299 v12.11.0 section 7.2.176 | Yes | Yes | Yes | This field is only included if different from the Called-Party-Address | Associated-URI | 32.299 v12.11.0 section 7.2.26 | No | No | No | | Application-Server-Information | 32.299 v12.11.0 section 7.2.24 | No | No | No | | Inter-Operator-Identifier | 32.299 v12.11.0 section 7.2.80 | Yes | Yes | Yes | | Transit-IOI-List | 32.299 v12.11.0 section 7.2.233B | No | No | No | | IMS-Charging-Identifier | 32.299 v12.11.0 section 7.2.75 | Yes | Yes | Yes | | SDP-Session-Description | 32.299 v12.11.0 section 7.2.184 | Yes | Yes | Yes | | SDP-Media-Component | 32.299 v12.11.0 section 7.2.180 | Yes | Yes | Yes | | Served-Party-IP-Address | 32.299 v12.11.0 section 7.2.187 | No | No | No | | Server-Capabilities | 29.229 | No | No | No | | Trunk-Group-ID | 32.299 v12.11.0 section 7.2.237 | No | No | No | | Bearer-Service | 32.299 v12.11.0 section 7.2.30 | No | No | No | | Service-Id | 32.299 v12.11.0 section 7.2.190 | No | No | No | | Service-Specific-Info | 32.299 v12.11.0 section 7.2.195 | No | No | No | | Message-Body | 32.299 v12.11.0 section 7.2.103 | No | No | No | | Cause-Code | 32.299 v12.11.0 section 7.2.35 | Yes | Yes | Yes | | Reason-Header |32.299 v12.11.0 section 7.2.164A | No |No | No | | Access-Network-Information | 32.299 v12.11.0 section 7.2.1 | Yes | Yes | Yes | The first value in the SIP P-Access-Network-Info header is included as the value for this AVP | Early-Media-Description | 32.299 v12.11.0 section 7.2.58 | Yes | Yes | Yes | The most recent Early Media offer/answer is included | IMS-Communication-Service-Identifier | 32.299 v12.11.0 section 7.2.76 | Yes | Yes | Yes | | IMS-Application-Reference-Identifier | 32.299 v12.11.0 section 7.2.74A | No | No | No | | Online-Charging-Flag | 32.299 v12.11.0 section 7.2.122 | No | No | No | | Real-Time-Tariff-Information | 32.299 v12.11.0 section 7.2.164 | No | No | No | | Account-Expiration | 32.299 v12.11.0 section 7.2.2 | No | No | No | | Initial-IMS-Charging-Identifier | 32.299 v12.11.0 section 7.2.79A | No | No | No | | NNI-Information | 32.299 v12.11.0 section 7.2.112A | No | No | No | | From-Address | 32.299 v12.11.0 section 7.2.67A | No | No | No | | IMS-Emergency-Indicator | 32.299 v12.11.0 section 7.2.76A | No | No | No | | IMS-Visited-Network-Identifier | 32.299 v12.11.0 section 7.2.77A | No | No | No | | Access-Transfer-Information | 32.299 v12.11.0 section 7.2.1A | No | No | No | | Related-IMS-Charging-Identifier | 32.299 v12.11.0 section 7.2.171B | No | No | No | | Related-IMS-Charging-Identifier-Node | 32.299 v12.11.0 section 7.2.171C | No | No | No | | Route-Header-Received | 32.299 v12.11.0 section 7.2.177A | No | No | No | | Route-Header-Transmitted | 32.299 v12.11.0 section 7.2.177B | No | No | No | | Instance-Id | 32.299 v12.11.0 section 7.2.70A | No | No | No | | TAD-Identifier | 32.299 v12.11.0 section 7.2.219A | No | No | No |

The BNF syntax for the IMS-Information AVP according to 3GPP TS 32.299 v12.11.0 is as follows

---- IMS-Information :: = < AVP Header: 876> [ Event-Type ] [ Role-Of-Node ] { Node-Functionality } [ User-Session-Id ] [ Outgoing-Session-Id ] [ Session-Priority ] * [ Calling-Party-Address ] [ Called-Party-Address ] * [ Called-Asserted-Identity ] [ Number-Portability-Routing-Information ] [ Carrier-Select-Routing-Information ] [ Alternate-Charged-Party-Address ] * [ Requested-Party-Address ] * [ Associated-URI ] [ Time-Stamps ] * [ Application-Server-Information ] * [ Inter-Operator-Identifier ] * [ Transit-IOI-List ] [ IMS-Charging-Identifier ] * [ SDP-Session-Description ] * [ SDP-Media-Component ] [ Served-Party-IP-Address ] [ Server-Capabilities ] [ Trunk-Group-ID ] [ Bearer-Service ] [ Service-Id ] * [ Service-Specific-Info ] * [ Message-Body ] [ Cause-Code ] * [ Reason-Header ] * [ Access-Network-Information ] * [ Early-Media-Description ] [ IMS-Communication-Service-Identifier ] [ IMS-Application-Reference-Identifier ] [ Online-Charging-Flag ] [ Real-Time-Tariff-Information ] [ Account-Expiration ] [ Initial-IMS-Charging-Identifier ] * [ NNI-Information ] [ From-Address ] [ IMS-Emergency-Indicator ] [ IMS-Visited-Network-Identifier ] * [ Access-Transfer-Information ] [ Related-IMS-Charging-Identifier ] [ Related-IMS-Charging-Identifier-Node ] [ Route-Header-Received ] [ Route-Header-Transmitted ] [ Instance-Id ] [TAD-Identifier] ----

== Populated OpenCloud AVPs

The population of OpenCloud AVPs is described here. The definition of OpenCloud AVPs is provided in Sentinel AVP definitions.

[cols="1,2,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | OC-Sentinel-Selection-Key | OC-Sentinel-Selection-Key | Yes | No | Yes | n/a | OC-Play-Announcement-Id | OC-Play-Announcement-Id | Yes | No | Yes | n/a | OC-Call-Type | OC-Call-Type | Yes | No | Yes | Role-Of-Node AVP has similar meaning on the Ro interface | OC-Service-Type | OC-Service-Type | Yes | No | Yes | n/a | OC-Charging-Result | OC-Charging-Result | Yes | No | Yes | | OC-OCS-Session-Id | OC-OCS-Session-Id | Yes | No | Yes | This is the session ID in Ro | OC-OCS-Session-Termination-Cause | OC-OCS-Session-Termination-Cause | Yes | No | Yes | | OC-OCS-Destination-Realm | OC-OCS-Destination-Realm | Yes | No | Yes | | OC-Sentinel-Error | OC-Sentinel-Error | Yes | No | Yes | | OC-Charging-Instance | OC-Charging-Instance | Yes | No | Yes | | OC-Event-Id | OC-Event-Id | Yes | No | Yes | | OC-Call-Id | OC-Call-Id | Yes | No | Yes | The Ro Session Id optional part includes the SIP Call ID | OC-End-Session-Cause | OC-End-Session-Cause | Yes | No | Yes | | OC-Start-Time | OC-Start-Time | Yes | No | Yes | | OC-End-Time | OC-End-Time | Yes | No | Yes | | OC-Session-Start-Time | OC-Session-Start-Time | Yes | No | Yes | | OC-Session-Established-Time | OC-Session-Established-Time | Yes | No | Yes | Included if an INVITE session is answered | OC-Session-End-Time | OC-Session-End-Time | Yes | No | Yes | | OC-Session-Counter | OC-Session-Counter | Yes | No | Yes | | OC-Interim-CDR-Trigger | OC-Interim-CDR-Trigger | Yes | No | Yes | | OC-Access-Network-MCC-MNC | OC-Access-Network-MCC-MNC| Yes | Yes | Yes | | OC-Visited-Network-MCC-MNC | OC-Visited-Network-MCC-MNC | Yes | Yes | Yes | | OC-IMSI-MCC-MNC | OC-IMSI-MCC-MNC | Yes | Yes | Yes | | OC-Session-Failover-Detected | OC-Session-Failover-Detected | Yes | Yes | Yes |

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/charging-content-avps/sentinel-avp-definitions.adoc

:here: charging-information/charging-content-avps/ :idprefix: sentinel-avp-definitions

:leveloffset: 1

= Sentinel AVP Definitions :toc: macro :toclevels: 4 :toc-title: On this page…​

The following AVPs are OpenCloud defined AVPs used in the Sentinel Express product. All OpenCloud defined AVPs have a diameter vendor ID of 19808.

toc::[]

== OpenCloud defined AVPs

=== OC-Sentinel-Selection-Key

The OC-Sentinel-Selection-Key AVP (AVP code 1001) is of type UTF8String and contains the Sentinel Selection Key for the session.

No Parent AVP.

=== OC-Play-Announcement-Id

The OC-Play-Announcement-Id AVP (AVP code 1002) is of type Integer32 and contains the ID of an announcement used during the session.

No Parent AVP.

=== OC-Call-Type

The OC-Call-Type AVP (AVP code 1003) is of type Enumerated and specifies the type of trigger for the session.

It can be one of the following:

* MOC = 1, the trigger was Originating * MOC_3RDPTY = 2, the trigger was a non-SIP third party call setup request (e.g. via HTTP) * MTC = 3, the trigger was Terminating * MFC = 4, the trigger was Forwarding * EMERGENCY_CALL = 9, the trigger was classified as emergency

No Parent AVP.

=== OC-Service-Type

The OC-Service-Type AVP (AVP code 1004) is of type Enumerated and specifies the initiating message for the session.

It can be one of the following:

* UNKNOWN = 1, the initiating reason is unknown * SipCall = 2, the session was initiated due to receipt of SIP INVITE * Subscription = 3, the session was initiated due to receipt of SIP SUBSCRIBE * Message = 5, the session was initiated due to receipt of SIP MESSAGE

No Parent AVP.

=== OC-Charging-Result

The OC-Charging-Result AVP (AVP code 1006) is of type Integer32. It contains the value of the Diameter CCA result-code AVP. In case there was no Ro session, it will have the value of -1.

No Parent AVP.

=== OC-OCS-Session-Id

The OC-OCS-Session-Id AVP (AVP code 1008) is of type UTF8String. It indicates a Session Id used to communicate with the OCS during the session.

No Parent AVP.

=== OC-OCS-Session-Termination-Cause

The OC-OCS-Session-Termination-Cause AVP (AVP code 1009) is of type Integer32. It communicates the reason that the OCS (or mediation layer) terminated the Ro session. It can be one of the following:

* NORMAL_SESSION_COMPLETION = 0, the session terminated normally. * ERROR_CCA = 1, the session was terminated due to a CCA error response. * CREDIT_LIMIT_REACHED = 2, the session was terminated due to Credit-Limit-Reached. * OCS_ABORT = 3, the session was terminated due to an ASR received from the OCS. * TCC_EXPIRED = 4, the session was terminated due to the Sentinel Tcc timer expiring. * CREDIT_CONTROL_FAILURE = 5, the session was terminated due to a failure generating CCR. * CLIENT_ABORT = 6, the session terminated due to a client request, typically as a result of an abnormal event.

No Parent AVP.

=== OC-OCS-Destination-Realm

The OC-OCS-Destination-Realm AVP (AVP code 1067) is of type UTF8String. It indicates the Diameter realm of the OCS used during the session.

No Parent AVP.

=== OC-Sentinel-Error

The OC-Sentinel-Error AVP (AVP code 1010) is of type Enumerated.

It can be one of the following:

* None = 1 * OcsTimeout = 2 * OcsCommunicationFailure = 3 * SentinelOverload = 4 * ProtocolError = 5 * InternalError = 6 * MappingError = 7 * OtherError = 8

If there is a Credit Control Answer, and it has an Experimental Result Code, and that has an OpenCloud vendor ID, then this AVP is filled.

No Parent AVP.

=== OC-Charging-Instance

The OC-Charging-Instance AVP (AVP code 1011) is of type Grouped. An OC-Charging-Instance AVP represents an online charging instance used during the session.

---- OC-Charging-Instance ::= < AVP Header: 1011 > [ OC-Charging-Instance-Name ] *[ OC-Session-Counter ] ----

No Parent AVP.

=== OC-Charging-Instance-Name

The OC-Charging-Instance-Name AVP (AVP code 1012) is of type UTF8String. It represents the name of an OC-Charging-Instance.

Parent AVP: OC-Charging-Instance

=== OC-Session-Counter

The OC-Session-Counter AVP (AVP code 1013) is of type Grouped. It represents a Session Counter used during the session.

Parent AVP: OC-Charging-Instance

---- OC-Session-Counter ::= < AVP Header: 1013 > *[ OC-Session-Counter-Address ] [ OC-Cumulative-Committed-Used ] [ OC-Cumulative-Granted ] [ OC-Cumulative-Granted-Refund ] [ OC-Cumulative-Requested ] [ OC-Cumulative-Requested-Refund ] [ OC-Cumulative-Sent-Used ] [ OC-Cumulative-Suspended-Duration ] [ OC-Reported-Used ] [ OC-End-Time ] [ OC-Pending-Requested ] [ OC-Start-Time ] ----

=== OC-Session-Counter-Address

The OC-Session-Counter-Address AVP (AVP code 1014) is of type Grouped. It represents a Session Counter address field, as documented in Session counter structure.

---- OC-Session-Counter-Address ::= < AVP Header: 1014 >

[ OC-Session-Counter-Address-Key ] [ OC-Session-Counter-Address-Value ] ---- Parent AVP: OC-Session-Counter

=== OC-Session-Counter-Address-Key

The OC-Session-Counter-Address-Key AVP (AVP code 1015) is of type UTF8String.

Parent AVP: OC-Session-Counter-Address

=== OC-Session-Counter-Address-Value

The OC-Session-Counter-Address-Value AVP (AVP code 1016) is of type UTF8String.

Parent AVP: OC-Session-Counter-Address

=== OC-Cumulative-Committed-Used

The OC-Cumulative-Committed-Used AVP (AVP code 1017) is of type Integer64.

It contains the value of the cumulativeCommittedUsed unit counter documented in Session counter structure.

Parent AVP: OC-Session-Counter

=== OC-Cumulative-Granted

The OC-Cumulative-Granted AVP (AVP code 1018) is of type Integer64.

It contains the value of the cumulativeGranted unit counter documented in Session counter structure.

Parent AVP: OC-Session-Counter

=== OC-Cumulative-Granted-Refund

The OC-Cumulative-Granted-Refund AVP (AVP code 1019) is of type Integer64.

It contains the value of the cumulatedGrantedRefund unit counter documented in Session counter structure.

Parent AVP: OC-Session-Counter

=== OC-Cumulative-Requested

The OC-Cumulative-Request AVP (AVP code 1020) is of type Integer64.

It contains the value of the cumulatedRequested unit counter documented in Session counter structure.

Parent AVP: OC-Session-Counter === OC-Cumulative-Requested-Refund

The OC-Cumulative-Requested-Refund AVP (AVP code 1021) is of type Integer64.

It contains the value of the cumulativeRequestedRefund unit counter documented in Session counter structure.

Parent AVP: OC-Session-Counter

=== OC-Cumulative-Sent-Used

The OC-Cumulative-Sent-Used AVP (AVP code 1022) is of type Integer64. It contains the cumulative used units sent to the OCS for the Session Counter.

It contains the value of the cumulativeSentUsed unit counter documented in Session counter structure.

Parent AVP: OC-Session-Counter

=== OC-Cumulative-Suspended-Duration

The OC-Cumulative-Suspended-Duration AVP (AVP code 1023) is of type Integer64.

It contains the value of the cumulativeSuspendedDuration field documented in Session counter structure.

Parent AVP: OC-Session-Counter

=== OC-Reported-Used

The OC-Reported-Used AVP (AVP code 1024) is of type Integer64.

It contains the value of the reportedUsed field documented in Session counter structure.

Parent AVP: OC-Session-Counter

=== OC-Pending-Requested

The OC-Pending-Requested AVP (AVP code 1025) is of type Integer64.

It contains the value of the pendingRequested unit counter documented in Session counter structure.

Parent AVP: OC-Session-Counter

=== OC-Start-Time

The OC-Start-Time AVP (AVP code 1026) is of type Time.

It contains the value of the startTime field documented in Session counter structure.

Parent AVP: OC-Session-Counter

=== OC-End-Time

The OC-End-Time AVP (AVP code 1027) is of type Time.

It contains the value of the endTime field documented in Session counter structure.

Parent AVP: OC-Session-Counter

=== OC-Event-Id

The OC-Event-Id AVP (AVP code 1028) is of type UTF8String.

If the initial request for the Session was a SIP SUBSCRIBE or SIP NOTIFY request, this is set to the value of the Event: header in the initial request.

If the initial request for the Session was a SIP REFER request, this is set to the CSeq of the REFER request.

No parent AVP.

=== OC-Call-Id

The OC-Call-Id AVP (AVP code 1029) is of type UTF8String. This is set to the Call-ID of the initial SIP request for the Session.

No parent AVP.

=== OC-End-Session-Cause

The OC-End-Session-Cause AVP (AVP code 1036) is of type Integer32. This is set to indicate the reason a service or feature ended the session.

If the LegManager.endSession instruction is called with a cause value, the AVP value is set to the cause value.

Otherwise, if the session state field endSessionCause is set, the AVP value is set to the session state value.

No parent AVP.

=== OC-Interim-CDR-Trigger

The OC-Interim-CDR-Trigger AVP (AVP code 1037) is a repeated AVP of type Grouped and appears only in interim CDRs. Each occurrence indicates a reason and a supplementary reason for writing an Interim CDR and the leg for which the reasons apply.

---- OC-Interim-CDR-Trigger ::= < AVP Header: 1037 >

[ OC-Interim-CDR-Reason ] [ OC-Interim-CDR-Supplementary-Reason] [ OC-Interim-CDR-Leg ]

----

No parent AVP.

=== OC-Interim-CDR-Reason

The OC-Interim-CDR-Reason AVP (AVP code 1038) is of type UTF8String.

Parent AVP: OC-Interim-CDR-Trigger

=== OC-Interim-CDR-Leg

The OC-Interim-CDR-Leg AVP (AVP code 1039) is of type UTF8String.

Parent AVP: OC-Interim-CDR-Trigger

=== OC-Session-Start-Time

The OC-Session-Start-Time AVP (AVP code 1040) is of type Time.

It contains the time that the session’s Initial Request was processed.

No parent AVP.

=== OC-Session-Established-Time

The OC-Session-Established-Time AVP (AVP code 1041) is of type Time.

It contains the time that the session was answered, that is the ACK to the 2xx-INVITE was processed.

No parent AVP.

=== OC-Session-End-Time

The OC-Session-End-Time AVP (AVP code 1042) is of type Time.

It contains the time that the session was ended.

No parent AVP.

=== OC-Interim-CDR-Supplementary-Reason

The OC-Interim-CDR-Supplementary-Reason AVP (AVP code 1043) is of type UTF8String.

Parent AVP: OC-Interim-CDR-Trigger

=== OC-Third-Party-Register-Response-Code

The OC-Third-Party-Register-Response-Code AVP (AVP code 1050) is of type Integer32. The value is 200 when the register request is successful otherwise it will have SIP Rejection response code.

No parent AVP.

=== OC-1st-Party-Register-Request

The OC-1st-Party-Register-Request AVP (AVP code 1051) is of type UTF8String. It will have value as "<not set>" if the third-party REGISTER request was rejected very early, otherwise the value will be the 1st party register request.

No parent AVP.

=== OC-1st-Party-Register-Response

The OC-1st-Party-Register-Response AVP (AVP code 1052) is of type UTF8String. It will have value as "<not set>" if the third-party REGISTER request was rejected very early, otherwise the value will be the 1st party register response.

No parent AVP.

=== OC-Private-Identity

The OC-Private-Identity AVP (AVP code 1053) is of type UTF8String. It is the private id from Auth Header.

No parent AVP.

=== OC-Public-Identity

The OC-Public-Identity AVP (AVP code 1054) is of type UTF8String.

No parent AVP.

=== OC-Public-GRUU

The OC-Public-GRUU AVP (AVP code 1055) is of type UTF8String.

No parent AVP.

=== OC-Temp-GRUU

The OC-Temp-GRUU AVP (AVP code 1056) is of type UTF8String.

No parent AVP.

=== OC-CMSISDN

The OC-CMSISDN AVP (AVP code 1057) is of type UTF8String.

No parent AVP.

=== OC-Contact-Header

The OC-Contact-Header AVP (AVP code 1059) is of type UTF8String.

No parent AVP.

=== OC-Age-Of-Information

The OC-Age-Of-Information AVP (AVP code 1060) is of type Integer64. The time in milliseconds of the source information. The value depends on which of the grouped AVP’s contains the OC-Age-Of-Information.

Parent AVP: OC-IMSI-MCC-MNC bOC-Access-Network-MCC-MNC OC-Visited-Network-MCC-MNC

== Overview

Interim CDRs are a CDR format used for recording CDRs at multiple points during the lifetime of a session. This format has several benefits over the once-per-session CDRs written by the session-based CDR features:

. Improved failure characteristics. Interim CDRs are recording more frequently during a session, so any system failures will result in less records being lost. . Interop with offline charging systems. This format is designed to reflect the message content requirements for interaction with offline charging systems via the Rf interface. . More accurate. This format records changes in specific AVPs (e.g. SIP SDP AVPs) during the lifecycle of a session allowing changes in media state to be more accurately tracked.

== Interim CDR content

Interim CDRs are written as a collection of AVPs conforming to the definitions listed in Sentinel AVP definitions. In addition to the standard AVPs, Interim CDRs contain additional AVPs to facilitate interpretation and correlation of their content.

These additions are summarized in the following table:

[cols="2,3,2" options="header"]

| AVP | Description | Specification | Accounting-Record-Type | Lifecycle enum indicating when the record was written. See below table. | RFC 6733 | Accounting-Record-Number | Unique-per-session number starting at 0 indicating how many records have been written for this session. | RFC 6733 | OC-Interim-CDR-Reason | Contains the leg the Interim CDR relates to, and the reason it was written. | Sentinel AVP definitions

The Accounting-Record-Type AVP can have the following enumerated values:

[cols="2,2" options="header"]

| Accounting-Record-Type | When written…​ | START_RECORD | When a session is established (answered). | INTERIM_RECORD | Mid-session, either in response to SDP changes or based on timer events (both configurable). | STOP_RECORD | When a session finishes. | EVENT_RECORD | When the last Interim CDR written is also the first one written, e.g. for recording of one-off SMS events.

== Interim CDR Correlation

If the IMS Charging Identifier (ICID) is present during network interactions it will be included in all Interim CDRs produced for a session.

When Running List CDRs, ICIDs present in a CDR file can be listed with --list-icids, or filtered with a specific ICID using --filter-by-icid.

== Related features

////

* README README README *

Maintenance note: This entire section is overridden downstream in sentinel-volte-documentation. If you make updates here, also make them downstream!

////

For configuring when Interim CDRs are written, refer to the Sip Interim Cdr feature documentation.

Other features can inform the Sip Interim Cdr feature of important session state changes by writing values to the control fields defined by the SipInterimCdrSessionState session state interface.

The features which affect the behaviour of the Sip Interim Cdr features are:

[cols="2,3" options="header"]

| Feature | Behaviour | Determine Chargeable Leg Feature | Determines which leg to charge then records it to the LegForCdrs session state field. | SDP Monitor Feature | Detects when SDPs have changed and sets the WriteCdrOnSDPChange session state field. This instructs the Interim CDR feature to (if configured) write an interim CDR when SDPs have changed.

== Controlling when Interim CDRs are written

The Interim CDR feature writes CDRs at specific points during a session. There are several mechanisms to control when interim CDRs are written including feature configuration and session state control fields, as described in the feature documentation.

== Example call flow

Below is an annotated call flow indicating where Interim CDRs are written during a typical SIP Mobile Originating session.

image::generated/mo-with-ocs-interim-cdrs.png[]

== Extending CDR content

////

* README README README *

Maintenance note: This entire section is overridden downstream in sentinel-volte-documentation. If you make updates here, also make them downstream!

////

To customise the content included in Interim CDRs, refer to Customising CDRs from the SDK documentation.

//// @startuml mo-with-ocs-interim-cdrs.png

skinparam monochrome true hide footbox autonumber "[0]" title Originating case, Served user is A - 60 second InterimTimerPeriod

participant Alice as A participant "Sentinel VoLTE" as V participant OCS as O participant Bob as B

note over A The call is not a preconditions call Configuration says interim CDRs should be written for * sdp negotiations * timer driven end note

A→ V : INVITE with SDP offer

note over V Online charging enabled CCR Early-Media-Description-AVP shall include offer end note V → O : CCR-I V ← O : CCA-I success

note over V The CCA grants say 3 mins of time so that we do not see CCR-U during this call end note V → B : INVITE V ← B : 183 with SDP answer A ← V : 183 with SDP answer

V ← B : 200 OK A ← V : 200 OK A → V : ACK note over V Write a CDR Type = start Reason = call answered SDP session description AVPs and SDP media component AVPs shall reflect SDP answer Accounting-Record-Number= 0 end note V → B: ACK note over V 2.5 minute long call end note V → V: Timer expired note over V Write a CDR after 60 seconds Type = interim Reason = InterimCdrTimer fired SDP session description AVPs and SDP media component AVPs shall reflect SDP Answer Accounting-Record-Number = 1 end note V → V: Timer expired note over V Write a CDR after 60 more seconds Type = interim Reason = InterimCdrTimer fired SDP session description AVPs and SDP media component AVPs shall reflect SDP Answer Accounting-Record-Number = 2 end note A → V : BYE

V → O: CCR-T V ← O: CCA-T

note over V In CCR-T SDP session description AVPs and SDP media component AVPs shall reflect SDP Answer end note

note over V Write CDR Type = Final Reason = "leg end" SDP session description AVPs and SDP media component AVPs shall reflect SDP Answer Accounting-Record-Number = 3 end note V → B : BYE V ← B : 200 OK A ← V : 200 OK

@enduml

////

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/rf-interface-avps/index.adoc

:here: charging-information/rf-interface-avps/ :idprefix: rf-interface-avps

:leveloffset: 1

= Rf Interface AVPs :indexpage:

The AVPs used by Sentinel SIP in the Accounting request are described.

== Sentinel SIP population of Accounting Request

The Accounting Request message is defined according to IETF RFC 6733, and the diameter Rf interface is defined in 3GPP TS 32.299. Sentinel products use the definition in 3GPP TS 32.299 v12.11.0 for ACR.

This table indicates the top-level AVPs inside a ACR request and how the Sentinel SIP service populates them.

[cols="1,2,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in ACR | Comments | Service-Context-Id | IETF RFC 4006 and refined by 3GPP TS 32.299 v12.11.0 section 7.1.12 | Yes | Yes | By default set to the value session@opencloud.com. For Sentinel SIP, the value is overridden to 12.32260@3gpp.org. This includes the Release, service-context and domain. The value is overridden by the Accept SIP Feature and SIP Third Party HTTP Trigger Feature. | User-Name | IETF RFC 6733 | Yes | Yes | Not set in Sentinel Express | Session-Id | IETF RFC 6733 | Yes | Yes | The Session-Id optional part is set to the Call-ID of the initial request for the Session | Origin-Host | IETF RFC 6733 | No | Yes | Resource Adaptor entity configuration defines the value to be used for this AVP | Origin-Realm | IETF RFC 6733 | No | Yes | Resource Adaptor entity configuration defines the value to be used for this AVP | Destination-Realm | IETF RFC 6733 | No | Yes | This is set in Sentinel configuration, when selecting a CDF to use for the Session | Accounting-Record-Type | IETF RFC 6733 | Yes | Yes | | Accounting-Record-Number | IETF RFC 6733 | Yes | Yes | | Acct-Application-Id | IETF RFC 6733 | No | Yes |Set to the value 4L | Vendor-Specific-Application-Id | IETF RFC 6733 | No | No | in volte documentation | User-Name | IETF RFC 6733 | Yes | Yes | This contains the Private Id from registration data | Destination-Host | IETF RFC 6733 | No | No | | Accounting-Sub-Session-Id | IETF RFC 6733 | No | No | | Acct-Session-Id | IETF RFC 6733 | No | No | | Acct-Multi-Session-Id | IETF RFC 6733 | No | No | | Acct-Interim-Interval | IETF RFC 6733 | Yes | Yes | | Accounting-Realtime-Required | IETF RFC 6733 | No | No | | Origin-State-Id | IETF RFC 6733 | No | No | | Event-Timestamp | IETF RFC 6733 | No | Yes | | Proxy-Info | IETF RFC 6733 | No | No | | Route-Record | IETF RFC 6733 | No | No | in volte documentation | Service-Context-Id | IETF RFC 4006 | Yes | Yes | | Service-Information | 3GPP TS 32.299 | No | Yes | Refer to Populated AVPs in the Service-Information AVP

The BNF for the ACR message according to 32.299 v12.11.0 section 6.2.2 is

---- <ACR> ::= < Diameter Header: 271, REQ, PXY > < Session-Id > { Origin-Host } { Origin-Realm } { Destination-Realm } { Accounting-Record-Type } { Accounting-Record-Number } [ Acct-Application-Id ] [ Vendor-Specific-Application-Id ] // not used in 3GPP [ User-Name ] [ Destination-Host ] [ Accounting-Sub-Session-Id ] // not used in 3GPP [ Acct-Session-Id ] // not used in 3GPP [ Acct-Multi-Session-Id ] // not used in 3GPP [ Acct-Interim-Interval ] [ Accounting-Realtime-Required ] // not used in 3GPP [ Origin-State-Id ] [ Event-Timestamp ] * [ Proxy-Info ] * [ Route-Record ] [ Service-Context-Id ] [ Service-Information ] * [ AVP ] ----

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/ro-interface-avps/index.adoc

:here: charging-information/ro-interface-avps/ :idprefix: ro-interface-avps

:leveloffset: 1

= Ro Interface AVPs :indexpage:

The AVPs used by Sentinel SIP in the credit control request are described.

== Sentinel SIP population of Credit Control Request

The Credit Control Request message is defined according to IETF RFC 4006, and some AVPs are removed and not used according to 3GPP TS 32.299. Sentinel products use the definition in 3GPP TS 32.299 v12.11.0 for CCR.

This table indicates the top-level AVPs inside a CCR request and how the Sentinel SIP service populates them.

[cols="1,2,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Comments | Service-Context-Id | IETF RFC 4006 and refined by 3GPP TS 32.299 v12.11.0 section 7.1.12 | Yes | Yes | By default set to the value session@opencloud.com. For Sentinel SIP, the value is overridden to 12.32260@3gpp.org. This includes the Release, service-context and domain. The value is overridden by the Accept SIP Feature and SIP Third Party HTTP Trigger Feature. | User-Name | IETF RFC 4006 | Yes | Yes | Not set in Sentinel Express | Session-Id | IETF RFC 4006 | Yes | Yes | The Session-Id optional part is set to the Call-ID of the initial request for the Session | Origin-Host | IETF RFC 4006 | No | Yes | Resource Adaptor entity configuration defines the value to be used for this AVP | Origin-Realm | IETF RFC 4006 | No | Yes | Resource Adaptor entity configuration defines the value to be used for this AVP | Destination-Realm | IETF RFC 4006 | No | Yes | This is set in Sentinel configuration, when selecting an OCS to use for the Session | Auth-Application-Id | IETF RFC 4006 | No | Yes |Set to the value 4L in volte documentation | Service-Context-Id | IETF RFC 4006 | Yes | Yes | | CC-Request-Type | IETF RFC 4006 | No | Yes | | CC-Request-Number | IETF RFC 4006 | No | Yes | | Destination-Host | IETF RFC 4006 | No | No | | Origin-State-Id | IETF RFC 4006 | No | No | | Event-Timestamp | IETF RFC 4006 | No | Yes | | Subscription-Id | IETF RFC 4006 | Yes | Yes | Set to the Served User, either as a SIP URI or Tel URI. This is populated via the SIP Subscriber Determination Feature. | Termination-Cause | IETF RFC 3588 | No | No | | Requested-Action | IETF RFC 4006 | No | Yes | | AoC-Request-Type | IETF RFC 4006 | No | No | | Multiple-Services-Indicator | IETF RFC 4006 | No | Yes | Set to 1 multiple services supported | Multiple-Services-Credit-Control | IETF RFC 4006 | Yes | Yes | In the case of AVP CDRs, if Ro charging is used then MSCC AVPs from the most recent CCA are written to the CDR. In the case of Ro charging the CCR’s MSCC AVP includes Populated AVPs in the Multiple-Services-Credit-Control AVP | CC-Correlation-Id | IETF RFC 4006 | No | No | | User-Equipment-Info | IETF RFC 4006 | Yes |Yes | The IMEI is used rather than the IMEISV, and the User-Equipment-Type AVP is set to IMEISV. | Proxy-Info | IETF RFC 4006 | No | No | | Route-Record | IETF RFC 4006 | No | No | | Service-Information | 3GPP TS 32.299 | No | Yes | Refer to Populated AVPs in the Service-Information AVP in volte documentation | User-Name | IETF RFC 6733 | Yes | Yes | This contains the Private Id from registration data

The BNF for the CCR message according to 32.299 v12.11.0 section 6.4.2 is

---- <CCR> ::= < Diameter Header: 272, REQ, PXY >

< Session-Id > { Origin-Host } { Origin-Realm } { Destination-Realm } { Auth-Application-Id } { Service-Context-Id } { CC-Request-Type } { CC-Request-Number } [ Destination-Host ] [ User-Name ] [ CC-Sub-Session-Id ] // not used in 3GPP [ Acct-Multi-Session-Id ] // not used in 3GPP [ Origin-State-Id ] [ Event-Timestamp ] *[ Subscription-Id ] [ Service-Identifier ] // not used in 3GPP [ Termination-Cause ] [ Requested-Service-Unit ] // not used in 3GPP [ Requested-Action ] *[ Used-Service-Unit ] // not used in 3GPP [ AoC-Request-Type ] [ Multiple-Services-Indicator ] *[ Multiple-Services-Credit-Control ] *[ Service-Parameter-Info ] // not used in 3GPP [ CC-Correlation-Id ] [ User-Equipment-Info ] *[ Proxy-Info ] *[ Route-Record ] [ Service-Information ] *[ AVP ] ----

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/sizing-avp-cdrs/index.adoc

:here: charging-information/sizing-avp-cdrs/ :idprefix: sizing-avp-cdrs

:leveloffset: 1

= Sizing AVP CDRs :indexpage: :toc: macro :toclevels: 4 :toc-title: On this page…​

This section documents the storage requirements for AVP CDRs.

toc::[]

== Binary CDR log structure

Each CDR log file can be broken down into the following parts:

* Protobuf overhead - a small amount of type information about contained records. * A header section - a small amount of data written by the CDR RA including version, host, and timestamp information. * Zero or more AVP CDRs - these records will vary in individual size, and usually form the majority of a CDR log. * A footer - this is empty for Sentinel products.

== Sizing analysis

The combined size of the header, footer, and protobuf overhead is normally trivial (<1KB) compared to the size of each finished CDR log file.

Individual CDR records will vary in size based on dynamic content such as hostnames, Sentinel selection key names, SDP content, and other similarly variable character data. As such, it is not possible to provide exact sizing for a given system without examining the CDR logs written while under a test load, but some approximations can be made.

A basic CDR record containing the information normally written by Sentinel will be on the order of 2000-3000 bytes. With this in mind, the following sections provide rough estimates regarding how much storage would be required for specific scenarios.

If Sentinel is configured to write Session CDRs (i.e. not writing Interim CDRs), then each session will write a single CDR on the order of 2000-3000 bytes.

== Interim CDR Sizing

This section documents the storage requirements for the AVP CDRs written by the CDR RA when Sentinel is configured to output Interim CDRs.

=== B2BUA CDR Sizing

This scenario involves writing CDRs for a single leg of a two party call.

Assuming a Start and End CDR are always written for the call, and assuming an average CDR size of 2500 bytes, each call will require a minimum of 5000 bytes. In addition, the Interim CDR feature can be configured to write CDRs periodically as a call progresses, or in response to SDP changes. Each of these events will produce additional records.

Taking these additional timer driven and SDP driven records into account, a rough approximation of the CDR storage requirements can be made with a formula such as:

2500 * Sessions Per Second * (2 + (Average SDP Driven CDRs Per Session) + (Average Timer Driven Interim CDRs Per Session))

It isn’t possible to use average call length when calculating storage requirements for timer driven CDRs as the number of timer driven CDRs written per call is sensitive to actual rather than average call length.

With the guideline above, we can perform approximations based on an example scenario:

* No SDP changes outside of initial call setup. * 95% of calls last under the default Interim CDR timer threshold (5 minutes by default). * 5% of calls last for 59 minutes and trigger numerous timer driven Interim CDRs during that period. With a 5 minute interim CDR timer, this will mean 11 timer driven interim CDRs. * The overall system is running at 100 session per second.

Using the above, we can assume that the average number of interim timer CDRs per call is 0.05 * 11, or 0.55 per session. This results in an estimated storage requirement per second of:

2500 * 100 * (2 + 0 + 0.55) = 637500 bytes / second

or 2189MB / hour

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/working-with-cdrs/index.adoc

:here: charging-information/working-with-cdrs/ :idprefix: working-with-cdrs

:leveloffset: 1

= Working with CDRs :indexpage:

NOTE: Sentinel writes binary CDRs using the CDR RA. Refer to CDR Resource Adaptor section of this guide for more information about Sentinel and the CDR RA.

== List CDRs

The Sentinel SDK contains a List CDRs tool, which can be used to print Sentinel’s binary CDRs files to a human readable format.

The CDR files contain binary encoded Diameter AVPs files in addition to a header and footer. The List CDRs tool decodes the binary CDR file and all the Diameter AVPs which is contains, printing them to the console.

It also supports printing the older 'legacy' CDR format which is not based on AVPs, as used by Sentinel version 2.4.x and earlier.

How to use it in a nutshell:

- Install the SDK normally using the SDK installer script, which will automatically install list-cdrs at sentinel-express-sdk/tools/list-cdrs - Run sentinel-express-sdk/tools/list-cdrs/list-cdrs.sh CDRFILE1 [CDRFILE2]…​

This guide covers the installation options and customisation options available for List CDRs.

== Topics

* Installing List CDRs — describes how to install the List CDRs tool * Obtaining CDRs — describes how to obtain CDRs used as input to the List CDRs tool * Running List CDRs — describes how to run the List CDRs tool * Extension AVPs — describes how to configure extension AVPs in the List CDRs tool

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/working-with-cdrs/installing-list-cdrs.adoc

:here: charging-information/working-with-cdrs/ :idprefix: installing-list-cdrs

:leveloffset: 1

= Installing List CDRs :sortorder: 1

== Installing the List CDRs tools using the SDK installer

If you install the SDK using the sentinel-express-sdk/build/bin/installer script, then the installer will automatically install the list-cdrs tool at /home/testuser/sentinel-express-sdk/list-cdrs/.

[role="small",subs="attributes,verbatim"] …​. $ ./build/bin/installer […​]

Creating deployment module deploy-volte …​ done. […​]

Configuration changes written. […​]

Installing List CDRs tool …​ done. […​] …​.

== Installing List CDRs from the SDK using Ant

To install the List CDRs tool using the Ant script instead, use the install-list-cdrs Ant build target under the sentinel-express-sdk/tools directory:

[role="small",subs="attributes,verbatim"] …​. $ cd /home/testuser/sentinel-express-sdk/tools $ ant install-list-cdrs Buildfile: /home/testuser/sentinel-express-sdk/tools/build.xml

init-build-extensions:

[…​]

install-list-cdrs: [echo] [echo] Retrieving List CDRs…​ [ivy:resolve] downloading repositories/opencloud-offline-mirror/com.opencloud.rhino.sentinel-core/sentinel-list-cdrs/4.1/sentinel-list-cdrs/4.1.0/sentinel-list-cdrs-package-4.1.0.zip …​ [ivy:resolve] …​.. (8971kB) [ivy:resolve] .. (0kB) [ivy:resolve] [SUCCESSFUL ] opencloud#sentinel-list-cdrs#sentinel-core/4.1;4.1.0!sentinel-list-cdrs-package.zip (1143ms) [echo] [echo] List CDRs retrieved. [echo] [echo] Installing List CDRs …​ [echo] [unzip] Expanding: /home/testuser/sentinel-express-sdk/tools/target/sentinel-list-cdrs-package.zip into /home/testuser/sentinel-express-sdk/tools [echo] [echo] [echo] List CDRs installed. [echo] To print CDR files, use the script at list-cdrs/list-cdrs.sh [echo] Usage: list-cdrs CDRFILE [CDRFILE]…​ [echo]

BUILD SUCCESSFUL Total time: 14 seconds …​.

NOTE: See Setting up Ant in the Sentinel Express SDK guide.

== Installing List CDRs Standalone

The above two approaches are automated ways of installing the List CDRs package (sentinel-list-cdrs-package.zip) into a particular location: sentinel-express-sdk/tools/list-cdrs/.

Both the above methods place a List CDRs installer archive at sentinel-express-sdk/tools/target/sentinel-list-cdrs-package.zip.

This sentinel-list-cdrs-package.zip archive can be moved to and unzipped into another location outside of the SDK and used as a standalone tool.

To install the List CDRs package as a standalone tool, simply unzip the sentinel-list-cdrs-package.zip archive to your chosen destination directory.

The mechanisms for invoking and configuration the List CDRs tools are the same as when running the tool inside the SDK. Simply substitute /home/testuser/sentinel-express-sdk/tools/list-cdrs with /your/chosen/directory/list-cdrs.

== Uninstalling List CDRs

If you want to uninstall the List CDRs tool, use the uninstall-list-cdrs Ant target under the sentinel-express-sdk/tools directory:

[role="small",subs="attributes,verbatim"] …​. $ cd /home/testuser/sentinel-express-sdk/tools $ ant uninstall-list-cdrs Buildfile: /home/testuser/sentinel-express-sdk/tools/build.xml

uninstall-list-cdrs: [echo] Uninstalling (deleting) the list-cdrs install from: /home/testuser/sentinel-express-sdk/tools/list-cdrs/ [delete] Deleting directory /home/testuser/sentinel-express-sdk/tools/list-cdrs

BUILD SUCCESSFUL Total time: 0 seconds …​.

Alternatively, just delete the list-cdrs directory: [role="small",subs="attributes,verbatim"] …​. $ rm -rf sentinel-express-sdk/tools/list-cdrs/ …​.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/working-with-cdrs/obtaining-cdrs.adoc

:here: charging-information/working-with-cdrs/ :idprefix: obtaining-cdrs

:leveloffset: 1

= Obtaining CDRs :sortorder: 2

== Obtaining CDR files

The List CDRs tool is designed to read completed binary CDR files generated by Sentinel.

Sentinel uses the CDR RA to write CDR files in a binary format. It typically writes these CDR files to the cdr directory inside the Rhino installation, and writes these binary CDR files using names such as cdr_101_1468259745367.log.

The List CDRs tool can read these completed binary CDR files either in their raw binary format (e.g. cdr_101_1468259745367.log), or in gzip compressed format (e.g. cdr_101_1468259745367.log.gz).

NOTE: Before a CDR file is completed, Sentinel may write a partial CDR file to disk, e.g. cdr_101_cdr-stream_28929467492591509.tmp. When a partially written CDR is ready to be rolled over, the CDR RA converts it to a completed binary CDR file, e.g. cdr_101_1468259745367.log. The List CDRs tool cannot read partially written CDR files. It can only read complete CDR files.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/working-with-cdrs/running-list-cdrs.adoc

:here: charging-information/working-with-cdrs/ :idprefix: running-list-cdrs

:leveloffset: 1

= Running List CDRs :sortorder: 3

To invoke the List CDRs tool, run the list-cdrs.sh script under the sentinel-express-sdk/tools/list-cdrs directory. Pass one or more file paths as arguments, each being a path to a completed binary CDR file generated by Sentinel.

NOTE: If the sentinel-express-sdk/tools parent directory does not contain a list-cdrs directory, then the List CDRs tool needs to be installed. The Installing List CDRs page describes how to install the List CDRs tool.

Calling the script with no arguments shows the expected syntax: [role="small",subs="attributes,verbatim"] …​. $ ./tools/list-cdrs/list-cdrs.sh Usage: list-cdrs.sh [--no-header] [--no-footer] [--no-protocol] [--ignore-error] [--output-file OUTPUTFILE] [--size-limit BYTES] [--cdr-filter FIELD=REGEX] CDRFILE [CDRFILE]…​

--no-header - Disable printing of CDR headers. --no-footer - Disable printing of CDR footers. --no-protocol - Disable printing of protocol and spec revisions in top level AVPs, e.g. "(Ro,vcb0)". --ignore-error - Continue processing CDRs files when encountering recoverable errors. --list-icids - List all unique IMS Charging Identifiers in the given CDR file(s), in order of first appearance. --filter-by-icid ICID - Print CDR message body only when CDR contains the given IMS Charging Identifier. ICID can be listed by "--list-icids" option. --output-file OUTPUTFILE - Append CDR output to OUTPUTFILE rather than to the console. --size-limit BYTES - CDR record size limit. Minimum and default value is 67108864 (64MB). Increase if encountering "Protocol message was too large" exception. --cdr-filter FIELD=REGEX - Print CDR message body only when the given FIELD matches the given regular expression. FIELD can be a field name, an AVP name, or an AVP path like "/IMS-Information/User-Session-Id". CDRFILE - A completed binary CDR file as produced by Sentinel. Both the new AVP based format (Sentinel 2.5 and later) and the older format (Sentinel 2.4 and earlier) are supported. CDR files can optionally be in gzip format, using a '.gz' suffix. Partially written CDR files (ending in ".tmp") are not supported. …​.

An example invocation, showing how to print a CDR file:

[role="small",subs="attributes,verbatim"] …​. $ ./tools/list-cdrs/list-cdrs.sh /path/to/cdr_101_1467865845057.log 2016-07-07T16:30:36.554+1200 Header { ra_name=CDR Generation, ra_vendor=OpenCloud, ra_version=2.3, ra_release=2.3.0.0-M1, ra_build=20160706024526, ra_revision=cdr-ra/2.3.0@d55f6a1, description=CDR session, rhino_node=101, ra_entity=cdr, hostname=mortadella } 2016-07-07T16:30:36.600+1200 AvpCdr { avps=[ Subscription-Id(Ro,vcb0)[ Subscription-Id-Type[2], Subscription-Id-Data[tel:34600000002] ], IMS-Information(Ro,vcb0)[ Role-Of-Node[ORIGINATING_ROLE(0)], Node-Functionality[AS(6)], User-Session-Id[08tE5q0fRdQRrus7F4FWqg], Session-Priority[PRIORITY_2(2)], Calling-Party-Address[tel:34600000002], Called-Party-Address[tel:34600000001], Time-Stamps[ SIP-Request-Timestamp[1467865834000], SIP-Response-Timestamp[1467865834000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 1000 1000 IN IP4 127.0.0.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0], Cause-Code[0], Early-Media-Description[ SDP-TimeStamps[ SDP-Offer-Timestamp[1467865834000], SDP-Answer-Timestamp[1467865834000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 1000 1000 IN IP4 127.0.0.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0] ] ], Service-Context-Id(Ro,vcb0)[12.32274@3gpp.org], OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:sipcall:mmtel-orig:], OC-Call-Type(Ext,Ext)[MOC(1)], OC-Service-Type(Ext,Ext)[SipCall(2)], OC-Charging-Result(Ext,Ext)[2001], OC-OCS-Session-Id(Ext,Ext)[diameterclient;diameterro-0;1529370976;0;08tE5q0fRdQRrus7F4FWqg], Session-Id(Ro,vcb0)[diameterclient;diameterro-0;1529370976;0;08tE5q0fRdQRrus7F4FWqg], OC-OCS-Session-Termination-Cause(Ext,Ext)[0], OC-Sentinel-Error(Ext,Ext)[None(1)], OC-Charging-Instance(Ext,Ext)[ OC-Charging-Instance-Name[scur_charging_instance], OC-Session-Counter[ OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Subscriber-Id], OC-Session-Counter-Address-Value[tel:34600000002] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Service-Id], OC-Session-Counter-Address-Value[1] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Cc-Unit-Type], OC-Session-Counter-Address-Value[Cc-Time] ], OC-Cumulative-Committed-Used[1000], OC-Cumulative-Granted[60000], OC-Cumulative-Granted-Refund[0], OC-Cumulative-Requested[60000], OC-Cumulative-Requested-Refund[0], OC-Cumulative-Sent-Used[1000], OC-Cumulative-Suspended-Duration[0], OC-Reported-Used[0], OC-Pending-Requested[0], OC-Start-Time[1467865834000], OC-End-Time[1467865836000] ] ], OC-Call-Id(Ext,Ext)[08tE5q0fRdQRrus7F4FWqg], MMTel-Information(Ro,vcb0)[ Supplementary-Service[ Service-Type[2] ], Subscriber-Role[ORIGINATING(0)] ] ] } 2016-07-07T16:30:38.937+1200 AvpCdr { avps=[ Subscription-Id(Ro,vcb0)[ Subscription-Id-Type[2], Subscription-Id-Data[tel:34600000002] ], IMS-Information(Ro,vcb0)[ Role-Of-Node[ORIGINATING_ROLE(0)], Node-Functionality[AS(6)], User-Session-Id[cXD7xzRmA1w4iWBzT9XMdQ], Session-Priority[PRIORITY_2(2)], Calling-Party-Address[tel:34600000002], Called-Party-Address[tel:34600000003], Time-Stamps[ SIP-Request-Timestamp[1467865837000], SIP-Response-Timestamp[1467865837000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 1000 1000 IN IP4 127.0.0.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0], Cause-Code[0], Early-Media-Description[ SDP-TimeStamps[ SDP-Offer-Timestamp[1467865837000], SDP-Answer-Timestamp[1467865837000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 1000 1000 IN IP4 127.0.0.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0] ] ], Service-Context-Id(Ro,vcb0)[12.32274@3gpp.org], OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:sipcall:mmtel-orig:], OC-Call-Type(Ext,Ext)[MOC(1)], OC-Service-Type(Ext,Ext)[SipCall(2)], OC-Charging-Result(Ext,Ext)[2001], OC-OCS-Session-Id(Ext,Ext)[diameterclient;diameterro-0;1529370976;2;cXD7xzRmA1w4iWBzT9XMdQ], Session-Id(Ro,vcb0)[diameterclient;diameterro-0;1529370976;2;cXD7xzRmA1w4iWBzT9XMdQ], OC-OCS-Session-Termination-Cause(Ext,Ext)[0], OC-Sentinel-Error(Ext,Ext)[None(1)], OC-Charging-Instance(Ext,Ext)[ OC-Charging-Instance-Name[scur_charging_instance], OC-Session-Counter[ OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Subscriber-Id], OC-Session-Counter-Address-Value[tel:34600000002] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Service-Id], OC-Session-Counter-Address-Value[1] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Cc-Unit-Type], OC-Session-Counter-Address-Value[Cc-Time] ], OC-Cumulative-Committed-Used[1000], OC-Cumulative-Granted[60000], OC-Cumulative-Granted-Refund[0], OC-Cumulative-Requested[60000], OC-Cumulative-Requested-Refund[0], OC-Cumulative-Sent-Used[1000], OC-Cumulative-Suspended-Duration[0], OC-Reported-Used[0], OC-Pending-Requested[0], OC-Start-Time[1467865837000], OC-End-Time[1467865838000] ] ], OC-Call-Id(Ext,Ext)[cXD7xzRmA1w4iWBzT9XMdQ], MMTel-Information(Ro,vcb0)[ Supplementary-Service[ Service-Type[2] ], Subscriber-Role[ORIGINATING(0)] ] ] } 2016-07-07T16:30:43.991+1200 AvpCdr { avps=[ Subscription-Id(Ro,vcb0)[ Subscription-Id-Type[2], Subscription-Id-Data[tel:34600000002] ], IMS-Information(Ro,vcb0)[ Role-Of-Node[TERMINATING_ROLE(1)], Node-Functionality[AS(6)], User-Session-Id[AhzD75RR1S7WP1_BN88Ajg], Session-Priority[PRIORITY_2(2)], Calling-Party-Address[tel:34600000002], Called-Party-Address[sip:conf-factory@localhost:5280], Requested-Party-Address[sip:conf-factory@localhost:5060], Time-Stamps[ SIP-Request-Timestamp[1467865835000], SIP-Response-Timestamp[1467865835000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 2000 1000 IN IP4 10.4.1.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0], Cause-Code[0], Early-Media-Description[ SDP-TimeStamps[ SDP-Offer-Timestamp[1467865838000], SDP-Answer-Timestamp[1467865838000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 2000 1000 IN IP4 10.4.1.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0] ] ], Service-Context-Id(Ro,vcb0)[12.32274@3gpp.org], OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:sipcall:mmtel-conf:], OC-Call-Type(Ext,Ext)[MTC(3)], OC-Service-Type(Ext,Ext)[SipCall(2)], OC-Charging-Result(Ext,Ext)[2001], OC-OCS-Session-Id(Ext,Ext)[diameterclient;diameterro-0;1529370976;1;daJvi_dNie_W_v-fzDOflg], Session-Id(Ro,vcb0)[diameterclient;diameterro-0;1529370976;1;daJvi_dNie_W_v-fzDOflg], OC-OCS-Session-Termination-Cause(Ext,Ext)[0], OC-Sentinel-Error(Ext,Ext)[None(1)], OC-Charging-Instance(Ext,Ext)[ OC-Charging-Instance-Name[scur_charging_instance], OC-Session-Counter[ OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Subscriber-Id], OC-Session-Counter-Address-Value[tel:34600000002] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Service-Id], OC-Session-Counter-Address-Value[3] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Cc-Unit-Type], OC-Session-Counter-Address-Value[Cc-Time] ], OC-Cumulative-Committed-Used[8000], OC-Cumulative-Granted[63000], OC-Cumulative-Granted-Refund[0], OC-Cumulative-Requested[180000], OC-Cumulative-Requested-Refund[0], OC-Cumulative-Sent-Used[8000], OC-Cumulative-Suspended-Duration[0], OC-Reported-Used[0], OC-Pending-Requested[0], OC-Start-Time[1467865835000], OC-End-Time[1467865843000] ] ], OC-Call-Id(Ext,Ext)[daJvi_dNie_W_v-fzDOflg], MMTel-Information(Ro,vcb0)[ Supplementary-Service[ Service-Type[10], Associated-Party-Address[tel:34600000002], Service-Id[mmtelconf101MpAdqRMBdip0aIpqObY1hQ], Change-Time[1467865843000] ], Subscriber-Role[TERMINATING(1)] ] ] } 2016-07-07T16:30:45.057+1200 Footer {} …​.

== Logging output

The List CDRs tool writes its main output to the console, but it can be configured to write some extra debugging to a log file.

It uses the log4j logging library, and its log4j configuration file is located at sentinel-express-sdk/list-cdrs/log4j.properties.

By default, it will log to sentinel-express-sdk/tools/list-cdrs/logs/list-cdrs.log. It logs very little when using the default configuration — the log file will typically be empty unless configured for debug logging.

To enable debug logging, change the log level on the last line of the log4j.properties file to DEBUG:

[role="small",subs="attributes,verbatim"] …​. log4j.logger.sentinel.cdr=DEBUG …​.

:leveloffset!:

:ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/sentinel/sentinel-documentation/release-4.1.x/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/working-with-cdrs/extension-avps.adoc

:here: charging-information/working-with-cdrs/ :idprefix: extension-avps

:leveloffset: 1

= Extension AVPs :sortorder: 4

== Built-in AVPs and extension AVPs

The binary CDR format contains Diameter AVPs encoded in binary form, and the List CDRs tool decodes these binary AVPs before printing them in a human readable format.

The tool has built-in knowledge of AVPs which are defined in Diameter protocols such as Rf and Ro.

It can also be customized with knowledge of user defined extension AVPs, by providing definitions of those AVPs in YAML files.

The List CDRs tool looks in the list-cdrs/extension-avps directory for YAML based files which define these extension AVPs.

A default installation of the List CDRs tool contains a DiameterExtension-AVP.yaml file inside this directory, which defines OpenCloud’s extension AVPs. This means that by default, the List CDRs tool recognizes all the AVPs in the CDR files produced by Sentinel.

== Known AVPs vs Undefined AVPs

When encountering an AVP which it does not recognize, the List CDRs tool treats it as an Undefined AVP. Because the tool can’t see which type of AVP it is (e.g. UTF8String or Integer32), it prints the raw binary content of the AVP in hexadecimal format.

This is how the List CDRs tool will print an extension AVP that it doesn’t recognize: [role="small",subs="attributes,verbatim"] …​. Undefined-AVP[code=1029,vendor=19808,hex=64 61 4a 76 69 5f 64 4e 69 65 5f 57 5f 76 2d 66 7a 44 4f 66 6c 67,ascii=daJvi_dNie_W_v-fzDOflg], …​.

This is how the List CDRs tool prints that same extension AVP, when that AVP is configured as an extension AVP (see below):

[role="small",subs="attributes,verbatim"] …​. OC-Call-Id[daJvi_dNie_W_v-fzDOflg], …​.

== Built-in extension AVPs

This is an excerpt from the default extension AVP configuration file at
list-cdrs/extension-avps/DiameterExtension-AVP.yaml, showing the first two extension AVPs:

[role="small",subs="attributes,verbatim"] …​. $ cat extension-avps/DiameterExtension-AVP.yaml !profiles DiameterExtension-AVP: id: name: 'Diameter Extension AVP' vendor: 'OpenCloud' version: '2.7' imports: null profiles: ? '' : AvpCode: 0 AvpName: null AvpType: null MandatoryRule: 1 ProtectedRule: 1 VendorId: 0 OC-Sentinel-Selection-Key: AvpCode: 1001 AvpName: OC-Sentinel-Selection-Key AvpType: UTF8String MandatoryRule: 1 ProtectedRule: 1 VendorId: 19808 OC-Play-Announcement-Id: AvpCode: 1002 AvpName: OC-Play-Announcement-Id AvpType: Integer32 MandatoryRule: 1 ProtectedRule: 1 VendorId: 19808 […​] …​.

== Customisation of extension AVPs

To configure your own custom AVP, add a new file with the same opening structure as extension-avps/DiameterExtension-AVP.yaml, but with your own extensions.

NOTE: Be sure to use your own Vendor ID, which we’ll assume to be 19404 below for the sake of example.

An example configuration file:

[role="small",subs="attributes,verbatim"] …​. $ cat extension-avps/ACME-DiameterExtension-AVP.yaml !profiles DiameterExtension-AVP: id: name: 'Diameter Extension AVP' vendor: 'OpenCloud' version: '2.7' imports: null profiles: ? '' : AvpCode: 0 AvpName: null AvpType: null MandatoryRule: 1 ProtectedRule: 1 VendorId: 0 ACME-My-First-Custom-Code: AvpCode: 1000 AvpName: ACME-My-First-Custom-Code AvpType: UTF8String MandatoryRule: 1 ProtectedRule: 1 VendorId: 19404 ACME-My-Second-Custom-Code: AvpCode: 1000 AvpName: ACME-My-Second-Custom-Code AvpType: UTF8String MandatoryRule: 1 ProtectedRule: 1 VendorId: 19404 […​] …​.

After you have created such a file you will also have to add the AVP names to the Charging profile in the DiameterExtensions profile table, which lives in the file extension-avps/DiameterExtensions.yaml. The profile consists of an array that lists all of the desired AVPs in the format <profile table name>/<profile name>. So for the two AVPs from the example above you would have to add these two lines to the Charging profile:

…​. - DiameterExtension-AVP/ACME-My-First-Custom-Code - DiameterExtension-AVP/ACME-My-Second-Custom-Code …​.

Note that the profile to use for the supported extension AVP list is configured with the ExtensionAvpSet property of the Diameter RA. See Configuring Extension AVPs for the full documentation of these profile tables.

The required fields for each AVP:

AvpCode:: The code of the AVP. If using your own vendor code, then this AVP code is within your own namespace. AvpName:: The name of the AVP. AvpType:: The type of the AVP. See the available AVP types below. MandatoryRule:: The "M" bit or Mandatory bit. Indicates whether support of the AVP is mandatory on the receiving end. Valid values are: * 0 - MUST * 1 - MAY * 2 - MUSTNOT ProtectedRule:: The "P" bit, indicating the need for encryption. Valid values are: * 0 - MUST * 1 - MAY * 2 - MUSTNOT VendorId:: The Vendor ID of the company which has defined this AVP.

The available AVP types:: * OctetString * Integer32 * Integer64 * Unsigned32 * Unsigned64 * Float32 * Float64 * Grouped * Address * Time * UTF8String * DiameterIdentity * DiameterURI * Enumerated * IPFilterRule * QoSFilterRule * Undefined

:leveloffset!:
1. Noldus, Rogier (2006), "CAMEL: Intelligent Networks for the GSM, GPRS and UMTS Network", John Wiley & Sons, Ltd
2. Noldus, Rogier (2006), "CAMEL: Intelligent Networks for the GSM, GPRS and UMTS Network", John Wiley & Sons, Ltd