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 go to https://repo.opencloud.com/artifactory/opencloud-sentinel-express-2.7.0/opencloud/sentinel-pack/2.7.0/sentinel-express-sdk/ and choose the version with the highest release number.

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.

Warning You will need OpenCloud-supplied credentials to download the package.

Get required software

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

Software Download Link Documentation Link

Java JDK 7

http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html

Apache Tomcat 7.0.39 or greater

http://tomcat.apache.org

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

Rhino 2.4.0 SDK from Artifactory

Rhino Documentation

Rhino Element Manager 1.4.0

REM Download Page

REM Documentation

Sentinel Express SDK including out of the box installer

Sentinel Express SDK, from Artifactory

Sentinel Express SDK

(Optional) Cassandra Database, version 2.0.17 or later version from the 2.0.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 v2.4 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 2.4 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 MaxPermGen size should be increased from its default, to at least 384MB. To do this in Rhino 2.4, modify the flags -XX:MaxPermSize= and -XX:PermSize= 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

OpenCloud product dependencies

Sentinel Express is built on top of other OpenCloud products. The 2.7.0.x series depends on the following series:

Product Series

Rhino

2.5.0.x

REM

1.5.0.4 or later

SIP

2.4.1.x

CGIN

1.5.4.x

SIS

2.5.4.x

Diameter

3.1.0.x

CDR-RA

2.3.0.x

HTTP-RA

2.2.0.x

DB-Query-RA

1.4.0.x

FSM Tool

1.1.0.x

CQL-RA

1.1.0.1

Rf Control RA

1.0.0.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:

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

Taking the SDK offline

The user is prompted as to whether or not they want to take the SDK offline.

You can optionally take the SDK offline by creating a local repository. This will take several minutes depending on connection speed, but will make subsequent retrievals much faster and remove the need for an internet connection.
Do you want to take the SDK offline? y/[N] >

If the user presses the Enter key then the default of N is applied by the installer. This means that the SDK remains online, and will connect to the OpenCloud repositories on an as-needs basis. Answering yes will create a local Ivy repository that includes all of the remote artifacts required to build the SDK.

The user is then presented with progress information related to the downloading of artifacts necessary to take the SDK offline. This process can take more than 30 minutes.

4

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.

5

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.

6

Creation of a deployment module

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

7

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.

8

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

9

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.

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. 1.5.2.8 and 2.5.2.7)

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 install.log is created in this directory. If there is a previous install.log file, that it is moved to install_[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 1.5.0 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; minimum supported version is 7.0.39

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

Below are the procedures to:

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/

Customize plugin logging

1

Unzip log4j.properties from rem.war:

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

2

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

log4j.rootLogger=INFO, FILE, CONSOLE

log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=%d{ABSOLUTE} %-5p <%t> [%c] %m%n

log4j.appender.FILE=org.apache.log4j.FileAppender
log4j.appender.FILE.File=${rem.home}/rem.log
log4j.appender.FILE.layout=org.apache.log4j.PatternLayout
log4j.appender.FILE.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p <%t> [%c] %m%n

log4j.logger.rem=INFO
log4j.logger.openjpa=INFO
log4j.logger.org.apache.wink=INFO

# Uncomment for subscriberdata cache eviction logging
#log4j.logger.rem.server.sentinel.subscriberdata.cache=TRACE

log4j.logger.sentinel.audit=INFO, AUDIT
log4j.additivity.sentinel.audit=false

log4j.appender.AUDIT=org.apache.log4j.FileAppender
log4j.appender.AUDIT.File=${rem.home}/sentinel-audit.log
log4j.appender.AUDIT.layout=org.apache.log4j.PatternLayout
log4j.appender.AUDIT.layout.ConversionPattern="%d{yyyy-MM-dd HH:mm:ss,SSS}", "%c{1}", %m%n

3

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

zip ../webapps/rem.war WEB-INF/classes/log4j.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

Be aware that the Sentinel Express machine API uses HTTP BASIC authentication. This passes the username and password with every request.

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

Set up SSL

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

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 or the Sentinel Sentinel Provisioning REST API.

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 Sentinel Sentinel Core REST API or 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. It 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)

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.

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 Sentinel machine provisioning API.

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 Sentinel machine provisioning API.

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 Sentinel machine provisioning API.

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.

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 Sentinel machine provisioning API.

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

Integer

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

Integer

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]

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 Sentinel machine provisioning API — see Activity Test REST API.

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 Sentinel machine provisioning API.

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

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 Sentinel machine provisioning API — see Sentinel Registrar Cassandra Subscriber Data Store REST API.

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

Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API — see Sentinel Registrar REST API.

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 Sentinel machine provisioning API — see SIP Service Configuration REST API.

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

HomeCountryCodeIDs

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

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.

MCC

Indicates the Mobile Country Code for a network or platform operator as defined by the Sentinel selection key.

MNCs

Indicates the Mobile Network Codes list with same Mobile Country Code.

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 Sentinel machine provisioning API — see SIP Service Configuration REST API.

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 Sentinel machine provisioning API — see SIP Session Control REST API.

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 Sentinel machine provisioning API — see SIP Third Party Call REST API.

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 Sentinel machine provisioning API — see Call Information Report REST API.

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 Sentinel machine provisioning API — see SS7 Relay Dialog ConfigurationProfile REST API.

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 Sentinel machine provisioning API — see SS7 Call Configuration REST API.

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 Sentinel machine provisioning API — see SS7 Diameter Configuration REST API.

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 Sentinel machine provisioning API — see SS7 Session Control REST API.

Sentinel for USSD

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

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 re-origination

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

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 Resource Adaptor

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.

Below are procedures for [configuration], [monitoring], and [using].

Configuring a Correlation RA entity

A Correlation RA entity configuration consists of:

The following diagram shows the Reorigination Correlation RA entity.

correlation ra
Tip The Correlation resource adaptor supports live re-configuration, so the administrator may update the configuration properties of a Correlation resource adaptor entity that has already been created.

Correlation RA configuration properties

The Correlation RA configuration properties are:

Name

Type

Description

ConfigProfileTable

String

The SLEE profile table with an RA configuration profile for this RA entity.

ConfigProfile

String

The SLEE profile in the ConfigProfileTable with configuration for this RA entity.

CorrelationIdPoolProfileTable

String

The SLEE profile table with correlation ID pool definitions for this Correlation RA entity.

For example, the Reorigination Correlation RA entity has the following configuration:

[Rhino@localhost (#9)] listraentityconfigproperties reorigination-correlation-ra
Configuration properties for resource adaptor entity reorigination-correlation-ra:
 ConfigProfile (java.lang.String): ReoriginationCorrelationConfigProfile
 ConfigProfileTable (java.lang.String): CorrelationConfigTable
 CorrelationIdPoolTable (java.lang.String): ReoriginationCorrelationIdPools

Correlation RA entity configuration profile

The Correlation RA configuration profile has the following attributes:

Name

Type

Description

RequestTimeout

Int

The maximum time (measured in ms) the Correlation RA will spend trying to allocate a correlation ID.

CorrelationIDExpiryTimerPeriod

Int

The maximum time (measured in ms) that an active correlation ID is considered to be still valid.

NumberOfThreadPool

Int

How many threads the Correlation RA entity should use.

For example, the Reorigination Correlation RA entity has the following configuration:

[Rhino@localhost (#8)] listprofileattributes CorrelationConfigTable ReoriginationCorrelationConfigProfile
CorrelationIDExpiryTimerPeriod=55000
NumberOfThreadPool=5
RequestTimeout=5000

Correlation RA entity ID pools configuration

Each Correlation RA entity has one or more correlation ID pools.

  • a default ID pool (optional)

  • a set of named ID pools. Each named ID pool is identified by a set of prefixes for choosing/selecting the ID pool. From the Correlation RA standpoint, the prefixes can be any address string. The client to the RA provides an address that the RA uses via a longestPrefix match address list search to select the pool to use.

Each correlation ID pool is defined in a SLEE profile in an ID pools profile table. There is one correlation ID pools table per Correlation RA entity.

Tip The correlation resource adaptor entity will raise an alarm if there are no correlation ID pools configured, or if there are configuration errors with the correlation ID pools.

addressPrefixes

An array of address prefixes that corresponds to this pool. The default pool has an empty addressPrefixes array.

nodeIds

An array of node IDs for which this pool has correlation IDs.

isPreconfiguredCorrelationIdSetUsed

If true, configure this ID pool with a pre-configured set of correlation IDs, else derive the correlation IDs.

preconfiguredCorrelationIdSet

The preconfigured set of correlation IDs per node (delimited with ‘:’).

minCorrelationIDInCluster

The minimum correlation ID value used in the cluster. 0 to maxCorrelationIDInCluster

maxCorrelationIDInCluster

The maximum correlation ID value used in the cluster. 0 to (10^18-1)

correlationIDNumberOfDigits

The number of digits the correlation ID should have. Minimum of number of digits in maxCorrelationIDInCluster to 18 maximum.

correlationIDRangePerNode

The number of correlation IDs that can be used for each node in the cluster.

There are two possible configuration options for correlation ID pools.

A prescribed set of IDs for each node

Defines the prescribed correlation IDs for each node in the following way:

  • NodeIds[0] — PreconfiguredCorrelationIdSet[0] which is a ‘:’ separated string containing all the correlation IDs for NodeIds[0]

  • NodeIds[1] — PreconfiguredCorrelationIdSet[1] which is a ‘:’ separated string containing all the correlation IDs for NodeIds[1]

  • etc.

A range of correlation IDs (min, max) for each node

Defines the range of values used in each node in conjunction with the NodeIds attribute in the following way:

  • The node whose identifier is NodeIds[i] has a range of values of CorrelationIDRangePerNode[i]

  • Each cluster has a range of CorrelationIDs defined by: [MinCorrelationIDInCluster, MaxCorrelationIDInCluster]

These values are allocated to the different cluster nodes in the following way:

  • NodeIds[0] — [MinCorrelationIDInCluster …​ MinCorrelationIDInCluster + CorrelationIDRangePerNode[0]]

  • NodeIds[1] — [MinCorrelationIDInCluster + CorrelationIDRangePerNode[0] + 1 …​ MinCorrelationIDInCluster + +CorrelationIDRangePerNode[0] + 1 + CorrelationIDRangePerNode[1]]

  • etc.

The maximum number of correlation IDs defined in the range is 1,000,000.

Provisioning Interfaces

The Correlation RA configuration and ID pools are provisioned using the Sentinel REST API or web interface.

Monitoring Correlation RA entity statistics

Each Correlation RA entity collects the following statistics that may be monitored via the Rhino statistics client.

Counters

Name Description

correlationGets

Count of correlation IDs which have been requested via findCorrelationEntry()

localGets

Count of correlation queries which returned immediately (synchronous delivery) as the local RA had the data available.

remoteGets

Count of correlation queries which did not return immediately (asynchronous delivery) as the local RA did not have the data available.

remoteDelivery

Count of correlation queries which required delivering data to another correlation RA instance.

unknown

Count of correlation queries which could not be remotely delivered as the destination RA for a correlation ID was unknown.

Caution The count correlationGets should equal the sum of localGets + remoteGets.

These statistics can use used to create threshold-based alarms.

Using the Correlation RA

A feature uses the Correlation RA by invoking methods on the provider interface.

  • To store data for correlation, a feature calls either the getNewCorrelationID(byte[] correlationData) or the getNewCorrelationID(String associatedAddress, byte[] correlationData) method on the CorrelationProvider. These methods will store the correlation data locally, and return an identifier String (the correlation ID) which can later be used to access the data from elsewhere. This operation will flag the returned ID as ‘in use’ until it is freed (on query) or expires (on timeout).

  • To query the correlation data (for example, from another session) a feature calls the getCorrelationData(String correlationId) method on the CorrelationProvider. This returns a CorrelationResult which will either contain the requested data (if it is available locally), or a flag indicating that the data is not available locally.

  • If the data is available locally then it can be immediately access via the [synchronous] API call CorrelationResult.getCorrelationData()

  • If the data is only available for asynchronous delivery, CorrelationResult.isAvailableAsynchronously() will be true, and CorrelationResult.getCorrelationData() will return null. See the following section for how to handle [asynchronous] result delivery.

CorrelationProvider interface:

public interface CorrelationProvider {

    /**
     * Creates an activity used for async requests.
     *
     * @return
     * @throws StartActivityException
     */
    public CorrelationActivity createActivity() throws StartActivityException;

    /**
     * This returns immediately and will return a CorrelationResult. This will either contain the correlation data if this is available on
     * this node or else will contain a flag that says this is only available on another node. In the later case you should then call an
     * async request to get the data.
     *
     * @param correlationId the Correlation ID
     * @return the CorrelationResult
     * @throws UnknownCorrelationIdException if the correlation id is not known in this pool
     * @throws NoDataFoundException if there is no data found for the correlation id specified
     * @throws CorrelationIDExpiredException if the correlation id has expired
     */
    public CorrelationResult getCorrelationData(String correlationId) throws UnknownCorrelationIdException, NoDataFoundException, CorrelationIDExpiredException;

    /**
     * This will return the CorrelationResult. This method will block and only return when the CorrelationResult is available. If the data is only
     * available on a remote node this may take some time to return. This should only be used if synchronous behavior is required.
     *
     * @param correlationId
     * @return
     * @throws CorrelationRequestException
     */
    public CorrelationResult getCorrelationDataSynchronously(String correlationId) throws CorrelationRequestException;

    /**
     * Request a new Correlation ID from the default pool
     *
     * @param correlationData data to be correlated
     * @return a new Correlation ID with a correlation name that is not being used in any other session
     * @throws NoAvailableEntries if there is any problem accessing data
     */
    public String getNewCorrelationID(byte[] correlationData) throws NoAvailableEntriesException;

    /**
     * Request a new Correlation ID String from a correlation id pool associated with an address.
     *
     * @param associatedAddress an address that the correlation RA will use to select a pool from which to return a correlation id
     * @param correlationData data to be correlated
     * @return a new Correlation ID String with a correlation name that is not being used in any other session
     * @throws NoAvailableEntries if there is any problem accessing data
     */
    public String getNewCorrelationID(String associatedAddress, byte[] correlationData) throws NoAvailableEntriesException;

    /**
     * Determine if an id is a correlation id we know about
     * @param possibleCorrelationId an id we wish to check to see if it is a correlation id
     * @return true iff this id is a correlation id we know about
     */
    public boolean isValidCorrelationId(String possibleCorrelationId);
}

CorrelationResult interface:

public interface CorrelationResult {
    /**
     * Contains correlation data associated with the requested correlation ID or null if the
     * data is only available asynchronously.
     *
     * @return
     */
    public byte[] getCorrelationData();

    /**
     * String containing requested correlation ID.
     *
     * @return the String containing the Correlation ID
     */
    public String getCorrelationId();

    /**
     * If the correlation data is not available locally but is available via an asynchronous call.
     *
     * An asynchronous call can be made by creating a CorrelationActivity with the provider and then making
     * the asynchronous call on the CorrelationActivity.
     *
     * @return
     */
    public boolean isAvailableAsynchronously();
}

CorrelationActivity interface:

public interface CorrelationActivity {

    /**
     * Request the correlation data associated with the specified Correlation ID.
     *
     * The result will be fired as a {@link CorrelationResultEvent}
     * event on this activity.  Failed queries will be fired as a {@link CorrelationFailureEvent}.
     *
     * @param correlationId The Correlation ID
     */
    public void requestCorrelationData(String correlationId);

}

Handling synchronous results

Synchronous queries occur when the RA which is queried is also storing the queried information. In these circumstances, the data is included in the returned CorrelationResult from a query. The following example demonstrates how to handle synchronous return results:

private void syncRequest(byte [] correlationData) {
    //
    // Store some data against a new correlation ID.
    //
    String correlationId;
    try {
        correlationId = corrProvider.getNewCorrelationID(correlationData);
    } catch (NoAvailableEntriesException e) {
        // ... handle exception ...
        return;
    }

    // ... do work until correlation data is required again.

    // In practice, the following will usually be done in another transaction which only knows the correlation ID.
    // It is done inline here for the sake of simplicity.

    //
    // Query the saved correlation data.
    //
    try {
        CorrelationResult result = corrProvider.getCorrelationData(correlationId);
        byte [] corrData = result.getCorrelationData();
        if (corrData != null) {
           // Do something with data
        } else {
           if (result.isAvailableAsynchronously()) {
             // ... Here we could optionally proceed with an asynchronous correlation data query. See following example.
           }
        }
    } catch (UnknownCorrelationIdException e) {
        // ... handle exception ...
        return;
    } catch (NoDataFoundException e) {
        // ... handle exception ...
        return;
    } catch (CorrelationIDExpiredException e) {
        // ... handle exception ...
        return;
    }
}

Handling asynchronous results

Asynchronous result handling is required when the correlated data for the requested ID is only available from a non-local Correlation RA (that is, on a different Rhino node). After the correlation data is requested, the result is returned in a CorrelationEvent which is delivered to the service. This CorrelationEvents must be explicitly handled with a SLEE event handler.

Requesting correlation data asynchronously is done as follows:

  • Create a new correlation activity using CorrelationProvider.createActivity()

  • Get an ActivityContextInterface object for the activity.

  • Attach the SBB local object to the ACI.

  • Send the request using the requestCorrelationData(String) method on the activity.

  • Handle the result in an event handler for the com.opencloud.slee.resources.correlation.CorrelationResultEvent event.

  • Handle failures in an event handler for the com.opencloud.slee.resources.correlation.CorrelationFailureEvent event.

The follow example demonstrates the handling an asynchronous correlation query:

private void asyncRequest(String correlationId) {
    try {
        CorrelationActivity corrActivity = corrProvider.createActivity();
        ActivityContextInterface corrAci = corrACIFactory.getActivityContextInterface(corrActivity);
        corrAci.attach(getSbbLocalObject());
        corrActivity.requestCorrelationData(correlationId);
    }
    catch (StartActivityException e) {
        // ... handle exception ...
    }
}

public void onCorrelationResult(CorrelationResultEvent result, ActivityContextInterface aci) {
    aci.detach(getSbbLocalObject());
    byte [] corrData = result.getCorrelationData()
    // ... do something with the data ...
}

public void onCorrelationFailure(CorrelationFailureEvent failure, ActivityContextInterface aci) {
    aci.detach(getSbbLocalObject());
    // ... handle failure ...
}

Javadoc API

Javadoc for the Correlation RA is available here: Sentinel Correlation RA API 1.0.

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

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.

Alternatively, the Diameter version spoken to the OCS can be set during installation.

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.0.1//EN" "http://www.opencloud.com/dtd/diameter-peer-table-1.0.1.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>
        <tcp-no-delay>true</tcp-no-delay>
    </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.0//EN"
                    "http://www.opencloud.com/dtd/diameter-realm-table-1.0.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>
                      </application-route>
                    </realm>

                    <default-route>
                      <peer-ref>
                        <hostname>diameterserver</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 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 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…​

many networks

querying network elements and sending notifications

CAMEL networks

SIP

SIP networks

Diameter networks

processing USSD triggers

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

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

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:

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 Sentinel HTTP Determine Network Operator REST API or web interface.

OcsParameterConfiguration Feature

Description

Feature name

OcsParameterConfiguration

Applicable contexts

SS7 Service, SIP Service, Diameter Service

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 Features REST API or web interface.

Platform Operator is Network Operator Feature

Description

Feature name

PlatformOperatorIsNetworkOperator

Applicable contexts

All Services

Prerequisite Features

None

Updates the Sentinel selection key so that the network operator is the same as the configured platform operator. It is used in the single-tenancy case. This feature is an initial trigger feature which can be used as an alternative to any of the Determine Network Operator features. The implication of using this feature is that the platform will not support multi-tenancy configuration.

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

The advantage of this is that in a single-tenancy scenario no work needs to be done to determine the network operator, but config data can still be scoped with a granularity finer than the network operator level.

Note This feature should be used in the single-tenancy case.

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

Prerequisite Features

None

Two functions will be supported initially:

  • Prefix and exact match of the subscriber number based on Black/White 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 Features REST API or 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

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. For example, different network operators will have different subscriber record fields. If a relational database is shared by multiple operators these different sets of subscribers will need to be provisioned in separate tables.

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 Sentinel Subscriber Data REST API or 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

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

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 Sentinel Features REST API or web interface.

Determine ATI Lookup Number Feature

Description

Feature name

DetermineATILookupNumber

Applicable contexts

SS7 service

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 Sentinel Features REST API or web interface.

Determine MNP Lookup Number Feature

Description

Feature name

DetermineMNPLookupNumber

Applicable contexts

SS7 service

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 Sentinel Features REST API or web interface.

Determine SRI Lookup Number Feature

Description

Feature name

DetermineSRILookupNumber

Applicable contexts

SS7 service

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 Sentinel Features REST API or 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

  • 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 Sentinel Features REST API or 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

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 Features REST API or web interface.

SRI for Basic Call Routing Feature

Description

Feature name

SRIForBasicCallRouting

Applicable contexts

SS7 service

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 Sentinel Features REST API or web interface.

USSD Push Notification Feature

Description

Feature name

USSDNotification

Applicable contexts

  • SS7 service

  • 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 Sentinel Features REST API or 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

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

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 black list THEN
    do not barr call
    RETURN
ENDIF

IF idp.calledPartyBCDNumber does not match using longest prefix match in white 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 black list and a white list containing the barring configuration. Numbers are matched using longest prefix.

  • The black list defines numbers to be barred.

  • The white list defines numbers to be allowed and overrides the black 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::::)

Black and White List configuration profile naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:CallBarring:BlackList or ${SELECTIONKEY}:CallBarring:WhiteList

${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable Feature specific

Address List entry table

${SELECTIONKEY}:CallBarring:BlackList:${ADDRESS}, ${SELECTIONKEY}:CallBarring:WhiteList:${ADDRESS}

Provisioning interfaces

The feature is provisioned using the Sentinel Features REST API or web interface.

Call Forwarding Detection Feature

Description

Feature script name

CallForwardingDetection

Applicable contexts

SS7 service

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

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 Features REST API or web interface.

Closed User Group Feature

Description

Feature script name

ClosedUserGroup

Applicable contexts

SS7 service

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 Features REST API or web interface.

Connect and Close Feature

Description

Feature name

ConnectAndClose

Applicable contexts

SS7 Service

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

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

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

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 Sentinel Features REST API or web interface.

Friends and Family Feature

Description

Feature name

FriendsAndFamily

Applicable contexts

  • SS7 service

  • 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 Sentinel Features REST API or web interface.

Home Zone Feature

Description

Feature script name

HomeZone

Applicable contexts

SS7 service

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 Sentinel Home Zone REST API or 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

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

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 AllowDisconnect InvokeTimeout CtrConfig VariableCcaPaths VariableTypes

1

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

message

123

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 Sentinel Features REST API or 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

  • Diameter Mediation Service

Prerequisite features

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 Sentinel Features REST API or 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

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

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

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

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 Sentinel Features REST API or web interface.

Roaming Reorigination Feature

The Re-origination 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

Prerequisite Features

Classify Call Scenario Feature

The re-origination 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 re-originated to the HPLMN using a pool of special routing numbers. The re-originated call is re-triggered from the HPLMN MSC.

The Re-origination feature should run at one of the pre credit check feature execution points for both the original InitialDP and the re-originated InitialDP. The Re-origination 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 re-originated 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 re-originated, or represent a re-originated dialog, then the Re-origination 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 re-originated. If the dialog should be re-originated, then it chooses a free special routing address and routes the call to this special routing address. The re-originated call may then be re-triggered from the HPLMN MSC

  • Receiving a re-originated 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

Re-originating 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 re-originated.

  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 re-origination is supported. Roaming partners that do not support the ERB(Disconnect) + ACH guarantee are listed in a re-origination configuration table which includes the VLR addresses of the operator. The Re-origination service determines if the VLR address is present in the table, and if so triggers re-origination.

Processing a reoriginated session

If a session is to be re-originated, 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 re-originated.

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 Re-origination 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 Re-origination 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 re-originated trigger includes these steps:

Determining if a dialog has been reoriginated

The re-origination feature analyses the InitialDP to determine whether the dialog is a re-originated dialog; if:

  1. The re-originated 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 re-originated 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 re-originated 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 re-originated InitialDP

  • copies the cap 1 InitialDP bearer capability (if present) to the re-originated InitialDP

  • copies the cap 1 InitialDP redirecting party ID (if present) to the re-originated InitialDP

  • copies the cap 1 InitialDP redirection information (if present) to the re-originated InitialDP

  • copies the cap 1 InitialDP location information (if present) to the re-originated InitialDP

  • copies the cap 1 InitialDP extensions (if present) to the re-originated InitialDP

  • sets the InitialDP session state field with the updated re-originated 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 re-originated 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 re-originated dialog is roaming. To ensure that the roaming indicator is set correctly, the Re-origination 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 re-origination. 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 re-origination 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 Sentinel Features REST API or web interface.

SMS Normalization Feature

Description

Feature script name

SMSNormalization

Applicable contexts

SS7 service MO SMS

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

Configuration profile naming

Provisioning interfaces

SS7 Determine Network Operator Feature

Description

Feature name

SS7DetermineNetworkOperator

Applicable contexts

SS7 service

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.

This feature is needed for multi-tenancy scenarios. This feature is intended to be used in the direct access case.

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 Sentinel Features REST API or web interface.

SS7 Subscriber Determination Feature

Description

Feature name

SubscriberDetermination

Applicable contexts

SS7 Service

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

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

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

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 Sentinel REST API or web interface.

Validate InitialDP Feature

Description

Feature name

ValidateInitialDP

Applicable contexts

SS7 service

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 Sentinel Features REST API or web interface.

Validate Third Party Call Request Feature SS7

Description

Feature name

Validate3rdPartyCallRequest

Applicable contexts

SS7 service

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

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

Configuration profile naming

Provisioning interfaces

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

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

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.

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

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.

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

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. For example, is this an ESRVCC registration scenario, or a regular registration scenario?

Determining the Registration type

The DetermineRegistrationSessionType analyses the Feature-Caps header:

  • If the +g.3gpp.atcf, +g.3gpp.atcf-mgmt and +g.3gpp.atcf-path parameters are present:

    • the session is classified as eSRVCCRegistration;

  • Otherwise, the session is classified as Regular3rdPartyRegistration.

Details

Feature script name

DetermineRegistrationSessionType

Applicable contexts

SIP service

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:eSRVCCRegistration::)

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 …​

MissingFeatureCapsHeader

If the first-party REGISTER request does not contain a Feature-Caps header

ESRVCCRegistration

The session is an eSRVCC registration scenario

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

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

Prerequisite features

Session state inputs and outputs

Inputs

NetworkOperator

The network operator, used for looking up registration data.

CallId

The call ID for the registration, used for looking up registration data.

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 in a multi-tenancy deployment.

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

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 Sentinel Registrar Determine Network Operator REST API or 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. It is used in the single-tenancy case.

Details

Feature script name

RegistrarPlatformOperatorIsNetworkOperator

Applicable contexts

SIP service

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

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

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:)

CallId

The call-id associate 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

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

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:)

CallId

The call-id associate with the activation session

PrivateId

The private-id of the UE

PublicIds

The list of public IDs provided in the 3rd party registrar message

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

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

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.

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

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

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.

Establishment to termination

The B2BUA feature divides the communication channel into two legs and mediates all SIP signaling between both ends of the session, from establishment to termination:

  • On an initial incoming SIP request, the feature creates an outgoing leg and links it to the triggering leg.

  • On all incoming SIP messages, if the triggering leg is linked, the feature adds an outgoing SIP message to the linked leg’s message queue, and sends it after the feature scripts have completed.

  • If configured to do so, on an incoming successful final response to an initial INVITE on the leg, the feature will send an early ACK, and will subsequently not B2BUA the ACK received from the linked leg. An early ACK will not be sent if there hasn’t been a completed SDP negotiation (offer & answer).

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 and B2BUA IEC, and SDP Comparison features.

See Sentinel SIP Feature Execution Points for more about running critical features.

Details

Feature script name

B2BUA

Applicable contexts

SIP service

Prerequisite features

none

Feature execution points

Pre

SipAccess_SessionAccept SipAccess_PartyRequest SipAccess_PartyResponse SipMidSession_PartyRequest SipMidSession_PartyResponse SubscriptionAccept SubscriptionSipRequest SubscriptionSipResponse SipTransaction_Accept SipTransaction_Request SipTransaction_Response

Post

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

Feature responses

Response Reason

featureHasFinished

Feature has finished.

featureFailedToExecute

Feature encountered a fatal error and was unable to continue.

featureIssuedWarning

Feature encountered a non-fatal error during execution.

B2BUA configuration

The configuration for the B2BUA feature is provisioned in the following table:

Parameter Type Description

PreserveCallIdOverB2BUA

Boolean

If true, the outgoing dialog will use the same SIP Call-ID as the incoming dialog.

SendEarlyInitialInviteACK

Boolean

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

Statistic When incremented

FailedToCreateOutgoingLeg

The feature encounters an error while attempting to create the outgoing leg.

FailedToCreateOutgoingMessage

The feature encounters an error while attempting to create an outgoing request on a newly created leg.

FailedToForwardMessage

The feature encounters an error while attempting to forward a message across the B2BUA.

FailedToLinkLegs

The feature encounters an error while attempting to link a newly created outgoing leg to the original incoming leg.

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 Sentinel Features REST API or web interface.

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

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

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

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.

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

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

PerLegCarrierSelectRoutingInformation

Map<String, String>

The table of leg names mapped to their corresponding Carrier-Select-Routing-Information AVP data

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

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.

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.

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.

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

Applicable contexts

SIP service

Prerequisite features

N/A

Feature execution points

All SubscriberCheck or SessionCheck post feature execution points: Post_SipAccess_SessionCheck Post_SubscriptionSessionCheck Post_SipTransaction_SessionCheck Post_SipThirdPartyAccess_SessionCheck Post_SipAccess_SubscriberCheck Post_SubscriptionSubscriberCheck Post_SipTransaction_SubscriberCheck Post_SipThirdPartyAccess_SubscriberCheck

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.

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.

Behaviour

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. For any given header type, 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.

Statistics

Name Description
AccessNetworkMccMncFoundInRegistrationData

Incremented when AccessNetwork MCC and MNC found in registration data

VisitedNetworkMccMncFoundInRegistrationData

Incremented when VisitedNetwork MCC and MNC found in registration data

AccessNetworkMccMncFoundInTrigger

Incremented when AccessNetwork MCC and MNC found in trigger

VisitedNetworkMccMncFoundInTrigger

Incremented when VisitedNetwork MCC and MNC found in trigger

UnableToDetermineAccessNetworkMccMnc

Incremented when AccessNetwork MCC and MNC not found in registration data or trigger

UnableToDetermineVisitedNetworkMccMnc

Incremented when VisitedNetwork MCC and MNC not found in registration data or trigger

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.

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

Provisioning Interfaces

The feature is provisioned using the Sentinel Features REST API or web interface.

Interim CDR Feature

SipInterimCdr is a system feature that is responsible for writing interim Call Detail Records throughout the session.

SipInterimCdr runs at various key points throughout a session and if any of its write conditions are met, it will create a new interim CDR based on session state, and write it out using the cdr-ra.

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

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 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 them to the CDR file.

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 was successfully written

CDRWriteError

Number of times a CDR was not successfully written

EventCDRWritten

Number of times an EventRecord CDR was successfully written

StartCDRWritten

Number of times a StartRecord CDR was successfully written

InterimCDRWritten

Number of times a InterimRecord CDR was successfully written

StopCDRWritten

Number of times a StopRecord CDR 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

Functionality

This feature 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.

Although the feature runs in many execution points, it inspects various session state fields to decide whether or not to write an interim CDR.

An interim CDR 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

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.

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.

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

Provisioning interfaces

The feature is provisioned using the Sentinel Features REST API or web interface.

Legacy CDR Feature

LegacyCdr is a system feature that is responsible for building a Call Detail Record that reflects the actions taken whilst processing a session.

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

Warning This feature is deprecated and not enabled by default. It has been superseded by the AVP CDR feature.

Details

Feature script name

LegacyCdr

Applicable contexts

SIP service

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

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

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

UserEquipmentInfo

org.jainslee.resources.diameter .cca.types.UserEquipmentInfo

The User-Equipment-Info AVP that contains the identity and capability of the terminal the subscriber is using for the connection to the network

DiameterServiceInfo feature

Functionality

This features uses the information from the session state fields mentioned above and constructs a protobuf message out of it for output. See Legacy 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

Max Call Duration 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. 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

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.

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, and its associated final response.

Details

Name in feature scripts

RecordTimestamps

Applicable contexts

SIP service

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

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

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 Sentinel SIP Service Configuration REST API or 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

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

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

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

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

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

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

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.

  1. On an incoming initial ACK or when the callEstablished session state field is true, a timer is set to the duration specified by the TimerInterval in the feature’s configuration.

  2. On the expiry of the timer, it is reset and Leg.refreshSession is instructed on each leg using the RefreshPeriod from the feature’s configuration.

  3. 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. The feature is also triggered on receiving a RAR. This will cause all legs to be refreshed immediately.

Details

Feature script name

SessionRefresh

Applicable contexts

SIP service

Prerequisite features

N/A

Feature execution points

Pre

SipAccess_SipRequest SipAccess_ChargingReauth SipMidSession_ChargingReauth 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

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

These parameters configure the Session Refresh feature:

Parameter Type Description

TimerInterval

long

Interval of periodic timer (seconds)

RefreshPeriod

long

Period of no activity for leg to refresh (seconds)

RefreshWithUpdateIfAllowed

boolean

Whether the session should be refreshed using UPDATE requests so long as the endpoint allows UPDATE requests.

Provisioning interfaces

The feature is provisioned using the Sentinel Features REST API or web interface.

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.

Details

Name in feature scripts

StoreHeaderInfo

Applicable contexts

SIP service

Prerequisite features

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.

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.

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

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

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

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 Features REST API or web interface.

Call Parties Address Determination Feature

Description

Feature name

CallPartiesAddressDetermination

Applicable contexts

SIP service

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

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

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

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

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

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

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

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.

Reauthorize Credit Feature

Description

Feature name

ReauthorizeCredit

Applicable contexts

SIP service

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

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. This feature is needed for multi-tenancy scenarios in the direct access case.

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

Prerequisite Features

Any feature setting the MidcallAnnouncementId 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.

The announcements are played by the MRF. The Language and the ID of the announcements to be played are set in the MidCallAnnouncementQueue, MidcallAnnouncementId and LanguageConfig session variables. If the MidcallAnnouncementId session variable is not set (null) or set to 0, the MidCallAnnouncementQueue is checked. If the queue is also clear, no announcement is played and 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 (eg the MidcallAnnouncementId 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 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).

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

MidcallAnnouncementId

Integer

Non-negative

ID of the announcement to be played — 0 indicates no announcement to play Increment InvalidAnnouncementIDs

Check the announcement queue

MidCallAnnouncementQueue

List<Integer>

Non-negative

ID of the announcements to be played

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

Default is false

 

MidCallAnnouncementPlayedParty

String

Leg name indicating which party the announcement will be played to

Linked leg will be passivated during announcement

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

PlayedAnnouncementIDs

int[]

List of announcement IDs

Updated with the announcement ID once it is played

MidcallAnnouncementId

Integer

Non-negative, non-zero, announcement in progress

Set to zero once announcement has been played, and null when all announcements are finished

PAShouldEndSessionWhenFinished

boolean

Set to true if the feature is invoked in the CreditLimitReached execution point. Can be cleared by a subsequent feature

MidCallAnnouncmeentQueue

List<Integer>

List of scheduled announcement IDs

A queue of announcements to play. As each announcement is played, it is removed from the queue.

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.

  • Add the AnnouncementId to the sessionstate PlayedList.

  • 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

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.

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

Configuration profile naming

Provisioning interfaces

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

Prerequisite features

Any feature setting the AnnouncementID 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 id and the language of the announcements to be played are set in the AnnouncementID and LanguageConfig session variables. 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 SipPlayAnnouncement feature to set the AnnouncementID 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

AnnouncementID

Integer

non-negative

ID of the current announcement to be played — 0, negative values and null indicate no announcement to play or in progress

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.

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 the announcement ID once it is played

AnnouncementID

Integer

non-negative

Set to id of current announcement to play (either by a preceding feature or by polling the early media announcement queue). Set to zero once all announcements have been played

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

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

  • Add AnnouncementId to sessionstate PlayedList

  • 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 Features REST API or web interface.

SIP Prefix and Suffix Analysis Feature

Description

Feature name

SipPrefixAndSuffixAnalysis

Applicable contexts

SIP Service

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 Features REST API or web interface.

SIP Short Code Feature

Description

Feature name

SipShortCode

Applicable contexts

SIP service

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.

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.

Provisioning interfaces

The feature is provisioned using the Sentinel Features REST API or web interface.

SIP Subscriber Determination Feature

Description

Feature name

SubscriberDetermination

Applicable contexts

SIP service

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

MSISDN

Check the subscriber is not already set before proceeding

Subscriber determination will take place

Outputs

Name Type Format Description

Subscriber

String

MSISDN string

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

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

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
            );
    // 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

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

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

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

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

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.

Diameter Service Features

Sentinel includes many features for Diameter networks:

Accept Diameter Mediation Session Feature

Description

Feature name

AcceptDiameterMediationSession

Applicable contexts

Diameter Service

Prerequisite features

None

Sets the Sentinel selection key session type to diametermediation.

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>:::)

To be updated with the session type for this session

Runtime exception handled by feature runner

Outputs

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

Response Reason

featureHasFinished

feature has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

Diameter Determine Network Operator Feature

Description

Feature name

DiameterDetermineNetworkOperator

Applicable contexts

Diameter Service

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.

This feature is needed for multi-tenancy scenarios. This feature is intended to be used in the direct access case. 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.

3GPP-IMSI-MCC-MNC : MCC and MNC extracted from the user’s IMSI (first 5 or 6 digits, as applicable from the presented IMSI).
— From 3gpp TS 32.299
which references 3gpp TS 29.061

Session state inputs and outputs

Inputs

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

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

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

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:

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:

Address NetworkOperator

00101

OpenCloud

00102

MVNO1

Configuration profile naming

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 Sentinel Diameter Determine Network Operator REST API or web interface.

Diameter Subscriber Determination Feature

Description

Feature name

SubscriberDetermination

Applicable contexts

Diameter Service

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

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

Name Type Format Description

Subscriber

String

Arbitrary

Subscriber determined from initial CCR, unless already set

Error scenarios

Scenario Handling

Session state InitialCcr is null or does not contain a SubscriptionId AVP

Report featureFailedToExecute

Feature responses

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.

Diameter Unconditional Reject Session Feature

Description

Feature name

UnconditionalRejectSession

Applicable contexts

Diameter Service

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

Response Reason

respondDiameterBaseResult

intended behaviour

featureHasFinished feature

has finished

Configuration

This feature is not configurable.

Provisioning interfaces

This feature has no provisioning interfaces.

USSD Features

Sentinel includes several features for processing USSD triggers:

  • USSD Balance Enquiry Feature — Performs a balance enquiry request against the OCS for the subscriber and reports the result.

  • USSD Callback Feature — Allows a subscriber to request via USSD that Sentinel set up a call between themselves and another party.

USSD Balance Enquiry Feature

Description

Feature name

USSD Balance Enquiry

Applicable contexts

USSD service

Prerequisite Features

None

The USSD Balance Enquiry feature performs a balance enquiry request against the OCS for the subscriber and reports the result.

The first step is to validate the received additional arguments for the Balance Enquiry feature, which are submitted via the ‘AdditionalArgument’ session state field.

Note Currently, this feature does not support any additional arguments, and if any are set, ‘featureFailedToExecute’ is reported to the core. No further validation is performed.

If validation succeeds, a balance enquiry request (in the form of an Ro CCR with the RequestedAction AVP set to CHECK_BALANCE) is sent to the OCS.

Note Currently, no mappers are involved when that CCR is produced, so its contents cannot be customised.

If any error case arises from the OCS request, the feature will report featureFailedToExecute and cease execution.

If the OCS responds successfully, a USSD response message is constructed and written to the ‘ResponseMessage’ session state field. The response message is composed of a configurable prefix string and the result of the balance enquiry check. If any errors arise during response construction, such as missing configuration, no message is written, featureFailedToExecute is reported and the feature ceases execution.

Example:

If the configurable ‘Text’ field in the USSDServiceResponseMessage configuration is set to ‘Your account balance is:’ and the current balance returned from the OCS is equivalent to EUR2.65, then the resulting ‘ResponseMessage’ string will be ‘Your account balance is: 2.65 EUR’.

Session State inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

AdditionalArgument

String

Extra USSD parameters supplied to this feature — should be null

Expected value is null

MSISDN

String

MSISDN

The subscriber address provided to the OCS in the balance enquiry CCR

Dependent on OCS behaviour

Outputs

Name Type Format Description

MAPResponseErrorType

int

error code

Indicates the failure mode of USSD Balance Enquiry to the USSD service

OCSRequestSendTime

Long

timestamp

Indicates the time the balance enquiry CCR was sent to the OCS

ResponseMessage

String

Plain text (e.g. “Your account balance is:”)

A configurable response message including the balance, to be forwarded to the subscriber by the USSD service

Error scenarios

Scenario Handling

Sessionstate AdditionalArgument is not null

Increment FailedEnquirySsfFaultCounter
Set sessionstate MAPResponseErrorType to MAP_USSD_ERROR_UNEXPECTED_DATA_VALUE
Report featureFailedToExecute

Error creating Ro Activity or exception sending CCR

Increment FailedEnquirySystemFaultCounter
Set sessionstate MAPResponseErrorType to MAP_USSD_ERROR_SYSTEM_FAILURE
Report featureFailedToExecute

OCS times out

Increment FailedEnquiryOcsFaultCounter
Set sessionstate MAPResponseErrorType to MAP_USSD_ERROR_SYSTEM_FAILURE
Report featureFailedToExecute

OCS response error

Increment FailedEnquiryOcsFaultCounter
Set sessionstate MAPResponseErrorType to MAP_USSD_ERROR_SYSTEM_FAILURE
Report featureFailedToExecute

No configured USSDResponseMessage

Set sessionstate MAPResponseErrorType to MAP_USSD_ERROR_SYSTEM_FAILURE
Report featureFailedToExecute

Feature responses

Response Reason

featureFailedToExecute

failed to send OCS request, OCS response timeout, OCS response error, invalid USSD parameters, and so on

featureHasFinished

feature has finished

Configuration

USSD service configuration:

Parameter Type Description

AccountScaling

Integer

The subscriber account balance scaling (for example, 100, 1000..)

UssdDataEncodingScheme

Byte

The USSD text message encoding type

WaitForConfirmation

Boolean

If the service should wait for a confirmation or not

USSDServiceResponseMessage configuration:

Parameter Type Description

Id

Integer

The response message ID (first digit marks the language)

Description

String

The response message description

Text

String

The text to be used as prefix during the response message construction

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

USSDServiceConfigurationTable

Service configuration

USSDServiceConfiguration

USSDServiceResponseMessageTable

Response message prefixes associated with particular messageIds

messageId, constructed as ‘currency-code*100 + 1’ (for example, 101)

USSD Callback Feature

Description

Feature name

USSD Callback

Applicable contexts

USSD service

Prerequisite features

None

The USSD Callback feature allows a subscriber to request via USSD that Sentinel set up a call between themselves and another party. The call will proceed according to the normal MOC session plan including SCUR charging, credit check, all MOC features and feature execution points. The call protocol is CAPv4.

The first step is to validate the received additional arguments for the USSD Callback feature, which are submitted via the ‘AdditionalArgument’ session state field. They must contain the CdPA argument, which however is not validated. If there are no additional arguments present the feature will report featureFailedToExecute and cease execution.

If validation succeeds, an HTTP call setup request is sent to a configurable host. In case of any error the feature reports featureFailedToExecute and takes no further action.

If the HTTP response code is ‘200 Ok’ its content string is checked to be non-empty and is then stored into the ‘ResponseMessage’ session state field. If it is an error response or invalid, the feature reports featureFailedToExecute to the core. In any case, feature execution is complete. It is then up to the HTTP server to establish the call through Sentinel.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

AdditionalArgument

String

CdPA parameter

Detach from HTTP Aci if required
Report featureFailedToExecute, featureHasFinished

MSISDN

String

MSISDN

Calling party address

Dependent on behaviour of HTTP host

Outputs

Name Type Format Description

MAPResponseErrorType

int

error code

Indicates the failure mode of USSD Balance Enquiry to the USSD service

ResponseMessage

String

Plain text (e.g. “Failed to setup call (SR)”)

A response message containing either an error message or the HTTP response content

Error scenarios

Scenario Handling

Sessionstate AdditionalArgument is null

Set sessionstate MAPResponseErrorType to MAP_USSD_ERROR_DATA_MISSING
Report featureFailedToExecute
Detach from HTTP Aci if required

No USSDCallbackConfiguration

Set sessionstate ResponseMessage to “Failed to setup call (SR)”
Report featureFailedToExecute
Detach from HTTP Aci if required

HTTP Error or IOException retrieving HTTP response content

Set sessionstate ResponseMessage to “Failed to setup call (Error)”
Report featureFailedToExecute
Detach from HTTP Aci if required

HTTP response timeout

Set sessionstate ResponseMessage to “Failed to setup call (Timeout)”
Report featureFailedToExecute
Detach from HTTP Aci if required

Feature responses

Response Reason

featureFailedToExecute

invalid USSD parameters, failed to send call setup request, received empty HTTP message or error response, response timeout etc

featureHasFinished

feature has finished

Format of the HTTP call setup request

The call setup request format is not configurable. However the URL Host and Port are configurable.

http://<HOST>:<PORT>/sentinel-ss7?cgpa=<CGPA>&cdpa=<CDPA>

CGPA and CDPA are read from session state fields MSISDN and AdditionalArgument respectively, and are determined by the USSD service itself (from the initiating USSD request).

Configuration

USSDCallback configuration:

Parameter Type Description

CallbackRequestHost

String

The host to which the callback HttpRequest shall be sent

CallbackRequestPort

Integer

The port to which the callback HttpRequest shall be sent

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

USSDServiceCallbackConfigurationTable

USSDCallback feature configuration

USSDServiceCallbackConfiguration

Test Features

Sentinel includes features for testing purposes:

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.

Test Set Announcement ID

Description

Feature name

TestSetAnnouncementID

Applicable contexts

SS7 service, SIP service

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

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

Scenario Handling

Null sentinel selection key

Report featureCannotStart

Missing address list

Report featureCannotStart

Missing address list prefixes

Report featureCannotStart

Feature responses

Response Reason

featureHasFinished

feature has finished

Configuration

The Test Set Announcement ID configuration requires an address list for configuration.

SchemaName List Name

TestSetAnnouncementId

testPrefixesToPlayAnnouncement

The announcement ID will be set based on the value looked up from the address list as follows:

Matched Address Announcement ID

34915

15

34916

17

34917

17

34918

18

34919

19

default

17

Test Set Session State

Description

Feature name

TestSetSessionState

Applicable contexts

SS7 service, SIP service

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

Scenario Handling

Missing configuration

Report featureCannotStart

Invalid configuration

Report featureCannotStart

Feature responses

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:

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

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. The utility components include:

Normalization Component

Description

Component name

Normalizer

Applicable contexts

  • SS7 service

  • SIP Service

Features using component

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 given to the component when used by the SIP normalization component.

Normalization is handled by the call type specific normalization features Voice Call Normalization Feature, SMS Normalization Feature and SIP Normalization Feature. Special character mapping and prefix and suffix analysis are also performed by the SS7 Prefix and Suffix Analysis Feature.

Note

Support formatting of special characters in SS7 signalling (such as: * → B, # → C) is performed by the SS7 Prefix and Suffix Analysis Feature.

Sentinel supports special character mapping only if they are prefixes or suffixes.

Configuration

Parameter Type Description

InternationalEscapeCode

String

Escape code for dialing international numbers (for example, 00)

NationalPrefix

String

National dialling prefix (for example, 0)

CountryCode

String

Country code

NetworkDialingCode

String

Network dialling code, used as the MNC

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

Provisioning interfaces

The Normalizer component is provisioned using the Sentinel Normalization REST API or Managing Normalization web interface.

ServiceTimerProvider

Description

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.

XPath Language Component

Description

Component name

Sentinel-XPath

Applicable contexts

  • SS7 service

  • Diameter Mediation Service

Features using component

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

Promotions

OCS Failure Handling Promotions

OCS Failure Handling Data Promotion Feature

Description

Feature name

OcsFailureHandlingDataPromotionFeature

Applicable contexts

Diameter service

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.

OCS Failure Handling SMS Promotion Feature

Description

Feature name

OcsFailureHandlingSmsPromotionFeature

Applicable contexts

Diameter service

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.

OCS Failure Handling Time Promotion Feature

Description

Feature name

OcsFailureHandlingTimePromotionFeature

Applicable contexts

Diameter service

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.

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 Sentinel REST API or web interface.

Promotions Commit Used Units Feature

Description

Feature name

PromotionsCommitUsedUnits

Applicable contexts

  • SS7 service

  • Diameter Mediation Service

Prerequisite features

Postrequisite features

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.

Promotions Free Reservations Feature

Description

Feature name

PromotionsFreeReservations

Applicable contexts

  • SS7 service

  • Diameter Mediation Service

Prerequisite features

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.

Scripted Promotions Feature

Description

Feature name

ScriptedPromotions

Applicable contexts

  • SS7 service

  • Diameter Mediation service

  • SIP service

Prerequisite features

Postrequisite features

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 (such as USSD callback), 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:

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:

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:

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:

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:

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:

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:

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 Sentinel Promotions REST API or web interface.

Promotion Selection Expressions

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

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

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'
    )
;

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:

Parameter Description

ServiceIDs

Array of integers

ServiceNames

Array of service name strings

Example profile:

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 Diameter Mediation REST API or web interface (under Sentinel > Service Configuration > Diameter Mediation > Service IDs).

Mappers

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

Mappers include:

Sentinel Diameter Mappers

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

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

Sentinel OCS Driver Mappers

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

Sentinel Registrar Mappers

ReceivedRegisterRequestToNetworkOperatorLookupKey

com.opencloud.sentinel.registrar.mapper.impl.ReceivedRegisterRequestToNetworkOperatorLookupKey

From …​ …​ To Description

IncomingSipRequest

String

Returns the To address host as the lookup key.

ReceivedRegisterRequestToSessionState

com.opencloud.sentinel.registrar.mapper.impl.ReceivedRegisterRequestToSessionState

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

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.

SessionStateToRegisterCdrAvpBasedMapper

com.opencloud.sentinel.registrar.mapper.impl.SessionStateToRegisterCdrAvpBasedMapper

From …​ …​ To Description

SentinelRegistrarSessionState

com.google.protobuf.Message

Builds an audit CDR from fields in session state

Sentinel SIP Mappers

Labels: pending_finishupdate

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

Sentinel SS7 Mappers

This page describes the Sentinel SS7 mappers.

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

Address Lists

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.

addresslist
Figure 1. addresses in an address list called “Prefixes”, mapped into a digit tree

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:

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:

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.

Provisioning

Using the Sentinel Element Manager

You provision Sentinel using the Sentinel Element Manager. The Sentinel Element Manager provides a web interface and machine API for provisioning Sentinel.

Tip The Sentinel Element Manager is an extension of the Rhino Element Manager (REM). See Installing the Sentinel 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:

Provisioning Configuration

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:

  1. create this file

  2. add the property definitions you want to customize.

You can also configure Sentinel EM to provision data in an external database.

Provisioning configuration options

sentinel.<featurename>.default-page-size

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

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

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

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

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

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

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

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

Description

The cache timeout (in milliseconds) to use for Sentinel core 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

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:

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:

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:

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.

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

Provisioning Data in TimesTen

Configuring JDBC provisioning lookup types and connections

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:

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:

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:

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:

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:

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.

Provisioning Web Interface

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 and machine API you will, at minimum, need to configure a Rhino instance in REM.

To access the Sentinel provisioning interface in REM:

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:

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.

Managing Session Plans

Associating feature execution scripts with points in the session

Use this management page to associate feature execution scripts with points in the session:

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.

Managing Cassandra

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:

300

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.

Managing Feature Execution Scripts

Changing, adding, and deleting feature execution scripts

To manage feature execution scripts:

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.

Managing Subscriber Data

Scoping, loading, editing, adding, and deleting subscriber data

To manage subscriber data:

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.

Using the Machine API

Use RESTful HTTP

The machine-provisioning API is available through RESTful HTTP.

Tip For a link to the API, select Sentinel ⇒ Machine API.
Note See Sentinel Provisioning REST API for more information.

Configuring Features, Services, Sentinel Core and Promotions

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.

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.

Managing Mappers

Configuring mappings

You can use this management page to view, add, and delete mappers and mapping sets.

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

Managing Plans, Session Types and Subscriptions

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.

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.

Managing Normalization

Scoping and configuring normalization

You can use this management page to add, edit, or delete normalization data.

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.

Managing Promotions

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.

300

Click image to enlarge

Adding, editing, and deleting a promotion configuration

To manage promotion configurations:

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:

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:

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:

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:

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.

Managing Correlation Resource Adaptor Entities

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:

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

To…​ Do this:

Add an ID pool

  • Click Add New.

    Blank ID pool correlation details display.

  • Enter all fields, and click Save.

    The new ID pool displays in the list at left.

Edit an ID pool

  • Click to select the ID pool in the list at left.

    ID pool correlation details display.

  • Make any changes, and click Save.

Delete an ID pool

  • Click to select the ID pool in the list at left.

  • Click Delete.

    A prompt asks you to confirm deletion.

Managing XCAP Host Mappings

Changing, adding, and deleting XCAP host mappings

To manage XCAP host mappings:

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.

Installing the Sentinel Provisioning Module

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

It requires a standalone distribution of REM 1.4.0 or compatible. REM can be installed with Jetty or Apache Tomcat. These instructions provide steps for configuring Apache Tomcat.

See the Rhino Element Manager User Guide to install and configure the Rhino Element Manager.

You’ll need these files to install the Sentinel Provisioning module:

  • apache-tomcat-<version>.zip

  • rhino-element-manager-<version>.zip

  • sentinel-express-element-manager-<version>.zip

Below are the procedures to set up Tomcat, install the REM extension, and run it securely

Set up Tomcat

To set up Apache Tomcat for the Sentinel Provisioning module:

1

Unzip apache-tomcat.zip:

cd ~/RhinoSDK  # or the location where your RhinoSDK is installed
export RHINO_HOME=`pwd`
unzip apache-tomcat.zip -d $RHINO_HOME
cd $RHINO_HOME/apache-tomcat*
export TOMCAT_HOME=`pwd`
mkdir rem_home

2

Create the file $TOMCAT_HOME/bin/setenv.sh with this content:

CATALINA_OPTS="-Drem.home=$CATALINA_BASE/rem_home -Dderby.stream.error.file=$CATALINA_BASE/rem_home/derby.log -Drem.encryption.password=changeit"

3

Set permissions:

chmod +x $TOMCAT_HOME/bin/*.sh

Install the REM extension

To install the REM extension for the Sentinel Provisioning Module:

1

Unzip rhino-element-manager.zip:

cd $RHINO_HOME
unzip rhino-element-manager.zip -d $RHINO_HOME
cd rhino-element-manager*
export REM_HOME=`pwd`

2

Copy sentinel-express-element-manager-<version>.zip into $REM_HOME/admin/extensions.

3

Run install-extensions.sh:

cd $REM_HOME/admin
./install-extensions.sh

4

Unzip rem.war:

cd $REM_HOME/admin/target
unzip rem.war

5

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

log4j.rootLogger=INFO, FILE, CONSOLE

log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=%d{ABSOLUTE} %-5p <%t> [%c] %m%n

log4j.appender.FILE=org.apache.log4j.FileAppender
log4j.appender.FILE.File=${rem.home}/rem.log
log4j.appender.FILE.layout=org.apache.log4j.PatternLayout
log4j.appender.FILE.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p <%t> [%c] %m%n

log4j.logger.rem=INFO
log4j.logger.openjpa=INFO
log4j.logger.org.apache.wink=INFO

# Uncomment for subscriberdata cache eviction logging
#log4j.logger.rem.server.sentinel.subscriberdata.cache=TRACE

log4j.logger.sentinel.audit=INFO, AUDIT
log4j.additivity.sentinel.audit=false

log4j.appender.AUDIT=org.apache.log4j.FileAppender
log4j.appender.AUDIT.File=${rem.home}/sentinel-audit.log
log4j.appender.AUDIT.layout=org.apache.log4j.PatternLayout
log4j.appender.AUDIT.layout.ConversionPattern="%d{yyyy-MM-dd HH:mm:ss,SSS}", "%c{1}", %m%n

6

Zip and move rem.war to webapps:

zip -rqu rem.war *
mv rem.war $TOMCAT_HOME/webapps/

7

Remove install files: (optional)

cd $RHINO_HOME
rm -rf rhino-element-manager*

8

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

9

Start Tomcat:

cd $TOMCAT_HOME
./bin/catalina.sh run
Note
Restarting Tomcat

To restart Tomcat when needed, run these commands:

cd $TOMCAT_HOME
./bin/catalina.sh stop
./bin/catalina.sh run

Security considerations

Below are recommendations for securely running the Sentinel Provisioning Module.

Use https

Be aware that the Sentinel machine API uses HTTP BASIC authentication. This passes the username and password with every request.

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

Set up SSL

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

Safeguard configuration data

By default, all REM and Sentinel provisioning configuration data is stored in the current working directory. When running REM from within Apache Tomcat, this means that the data will reside wherever you start Tomcat from. If Tomcat is stopped and then started from a different directory, the previous configuration data will not be found.

To specify a new directory for REM (and the Sentinel provisioning REM extension) to store its data in:

1

Edit (or create) ${TOMCAT_HOME}/bin/setenv.sh, modifying the `rem.home `property to a new value.

2

If you already had existing configuration data which you want to keep, make sure Tomcat is stopped and then move it to the new data directory. This data may include:

  • rem_data — REM configuration data

  • rhino-ems.ks — keystore containing Rhino instance trust certificates

  • sentinel_data — Sentinel provisioning configuration data

  • sentinel-provisioning-config.properties — Sentinel provisioning configuration settings.

3

Start/restart Tomcat.

Provisioning Auditing

The Sentinel provisioning system audits every write operation (create, update, and delete) that goes through it. This includes changes made both through the web-based GUI and via the machine REST API.

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 log4j.properties file.

log4j.logger.sentinel.audit=INFO, AUDIT
log4j.additivity.sentinel.audit=false

log4j.appender.AUDIT=org.apache.log4j.RollingFileAppender
log4j.appender.AUDIT.File=${rem.home}/sentinel-audit.log
log4j.appender.AUDIT.MaxBackupIndex=10
log4j.appender.AUDIT.MaxFileSize=10MB
log4j.appender.AUDIT.layout=org.apache.log4j.PatternLayout
log4j.appender.AUDIT.layout.ConversionPattern="%d{yyyy-MM-dd HH:mm:ss,SSS}", "%c{1}", %m%n

If you wish to disable the audit messages completely then add the following settings to the REM or Tomcat log4j.properties file.

log4j.logger.sentinel.audit=NONE

Using the XCAP API

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

XCAP host mappings control which Rhino instance, network operator, and 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.

XCAP host mappings can also be managed using the XCAP Server Configuration REST API.

Accessing the XCAP API

To access the XCAP API:

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.

Sentinel Alarms

Alarms raised by Sentinel

Source Type Instance ID Level

Correlation RA

correlation-config-error

correlation-id-pools

Critical

Message

Correlation ID pools for RA entity '$entityName$' have configuration problems.
$listOfErrors$

Raised

When the Correlation RA is activated or reconfigured and errors are detected in the ID pools configuration.

Cleared

When the RA is activated or reconfigured and no errors are detected in the ID pools configuration.

Source Type Instance ID Level

Any Sentinel service (SS7, SIP, Diameter) or Sentinel charge

mapperset-config-error

mapperset-configuration-table

Critical

Message

Profile table '`SentinelMapperSetConfigurationTable`' is missing

Raised

When a Sentinel service tries to find a Mapper, but cannot because the profile table is missing

Cleared

This table is created as Sentinel is installed. This issue should be resolved by the platform administrator, and the alarm manually cleared.

Source Type Instance ID Level

Any Sentinel service (SS7, SIP, Diameter) or Sentinel charge

mapperset-config-error

mapperset-entry-table

Critical

Message

Profile table '`SentinelMapperSetEntryTable`' is missing

Raised

When a Sentinel service tries to find a Mapper, but cannot because the profile table is missing

Cleared

This table is created as Sentinel is installed. This issue should be resolved by the platform administrator, and the alarm manually cleared.

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.

Charging Information

Charging Information describes the format and content of CDR files, and the information present in Diameter Ro.

Topics

CDR Formats

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

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

package com.opencloud.cdrformat;

// AVP based CDR

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;
    }

}

Legacy CDR Format

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.

Base types

The base types are used in CDRs for Sentinel SS7, Sentinel Diameter Mediation, and for legacy format support in Sentinel SIP (as non-default).

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

// SS7 Call CDR

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

// SS7 SMS CDR

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

// Diameter Service CDR

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;

}

Sentinel SIP Service

By default the Sentinel SIP Service uses the AVP CDR Format.

Sentinel SIP can be configured to use the legacy format. This format is defined as follows:

package com.opencloud.sentinel.cdr;

import "com/opencloud/sentinel/cdr/base-cdr-types.proto";

// SIP CDR

message SipCdr {

    optional string subscriber = 1;
    optional Time sessionInitiated = 2;
    optional Time sessionEstablished = 3;
    optional Time sessionEnded = 4;
    optional CallType callType = 5;
    optional string callingPartyAddress = 6;
    optional string calledPartyAddress = 7;
    optional string callId = 8;
    optional sint32 chargingResult = 9 [default = -1];
    optional int64 cumulativeReported = 10;
    repeated int32 ocsLatencySamples = 12 [packed=true];
    repeated int32 announcementIDs = 13;
    optional SipServiceType serviceType = 14 [default = Unknown];
    optional SentinelError sentinelError = 15 [default = None];
    optional int32 endSessionCause = 16;
    optional int32 ocsSessionTerminationCause = 17;

    optional string sentinelSelectionKey = 18;

    repeated string ocsSessionIDs = 19;

    repeated CDRChargingInstance chargingInstances = 21;

    optional string eventId = 22;

    extensions 50 to max;

    enum CallType {
        MOC = 1;
        MOC_3RDPTY = 2;
        MTC = 3;
        MFC = 4;
        EMERGENCY_CALL = 9;
    }

    enum SipServiceType {
        Unknown = 1;
        SipCall = 2;
        Subscription = 3;
        Message = 5;
    }

    message CDRChargingInstance {
        required string name = 1;

        repeated CDRSessionCounter sessionCounter = 2;
    }

    message CDRSessionCounter {
        required SessionCounterAddress address = 1;
        optional int64 reportedUsed = 2;
        optional int64 pendingRequested = 3;
        optional int64 cumulativeSentUsed = 4;
        optional int64 cumulativeCommittedUsed = 5;
        optional int64 cumulativeRequested = 6;
        optional int64 cumulativeGranted = 7;
        optional int64 cumulativeRequestedRefund = 8;
        optional int64 cumulativeGrantedRefund = 9;
        optional Time startTime = 10;
        optional Time endTime = 11;
        optional int64 cumulativeSuspendedDuration = 12;

        extensions 50 to max;

        message SessionCounterAddress {
            repeated AddressEntry entry = 1;

            message AddressEntry {
                required string key = 1;
                required string value = 2;
            }
        }
    }

}

Charging Content AVPs

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.

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.

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

No

No

No

Sentinel uses the Rating-Group AVP in preference to the Service-Identifier

Rating-Group

IETF RFC 4006 and 3GPP TS 32.299 v12.11.0 section 7.1.10

No

Yes

No

This AVP is set according to Session Counters and the ratingGroup session state field.

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

No

No

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.

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

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.

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

No

PS-Information AVP contains EPC layer information and as such is not populated by a SIP-AS.

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

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.

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-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-AGE-OF-INFORMATION

OC-AGE-OF-INFORMATION

Yes

Yes

Yes

OC-MCC-MNC

OC-MCC-MNC

Yes

Yes

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

Optional

Optional

Optional

It is included if the call flow performs a SRI request or SRI-for-SM request

Sentinel AVP Definitions

The following AVPs are OpenCloud defined AVPs used in the Sentinel Express product. All OpenCloud defined AVPs have a diameter vendor ID of 19808.

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.

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.

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

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

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.

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.

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.

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.

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 ]

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.

OC-Session-Counter

The OC-Session-Counter AVP (AVP code 1013) is of type Grouped. It represents a Session Counter used during the session.

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 ]

OC-Session-Counter-Address-Key

The OC-Session-Counter-Address-Key AVP (AVP code 1015) is of type UTF8String.

OC-Session-Counter-Address-Value

The OC-Session-Counter-Address-Value AVP (AVP code 1016) is of type UTF8String.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 for writing an Interim CDR and the leg for which the reason applies.

OC-Interim-CDR-Trigger ::= < AVP Header: 1037 >

                                   [ OC-Interim-CDR-Reason ]
                                   [ OC-Interim-CDR-Leg ]

OC-Interim-CDR-Reason

The OC-Interim-CDR-Reason AVP (AVP code 1038) is of type UTF8String.

OC-Interim-CDR-Leg

The OC-Interim-CDR-Leg AVP (AVP code 1039) is of type UTF8String.

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.

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.

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.

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.

OC-MCC-MNC

The OC-MCC-MNC AVP (AVP code 1061) is of type UTF8String. The length is 5 or 6 digits depending on the value of MNC, that can be 2 or 3. It is encoded as UTF8String characters representing the IMSI MCC-MNC numerical values. In accordance with 3GPP TS 29.060 24 (for GGSN), 3GPP TS 29.274 81 (for P-GW) and 3GPP TS 23.003 40, the MCC is 3 digits and the MNC is either 2 or 3 digits. There are no padding characters between the MCC and MNC.

OC-Access-Network-MCC-MNC

The OC-Access-Network-MCC-MNC (AVP code 1062) indicates the home network MCC-MNC, in case the access network can be identified. The information is extracted from the P-Access-Network-Info header.In the event that the P-Access-Network-Header header is not present the information can be extracted from registration records. It is a grouped AVP formed by:

  • OC-MCC-MNC

  • OC-Age-Of-Information

The OC-Age-Of-Information is the registration time.

OC-Visited-Network-MCC-MNC

The OC-Visited-Network-MCC-MNC (AVP code 1063) indicates the visited network MCC-MNC, in case the visited network can be identified. This information is extracted from the P-Visited-Network-Id header. In the event that the P-Visited-Network-Id header is not present the information can be extracted from registration records. It is a grouped AVP formed by:

  • OC-MCC-MNC

  • OC-Age-Of-Information

The OC-Age-Of-Information is the registration time.

OC-IMSI-MCC-MNC

The OC-IMSI-MCC-MNC (AVP code 1064) is extracted from the IMSI and indicates the network related to the subscriber’s IMSI. It is a grouped AVP formed by:

  • OC-MCC-MNC

  • OC-Age-Of-Information

The OC-Age-Of-Information is:

  • registration time

  • SRI response time in case it is extracted from the SRI response.

Interim CDRs

The purpose, lifecycle, and features related to Interim CDRs are described on this page.

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:

  1. Improved failure characteristics. Interim CDRs are recording more frequently during a session, so any system failures will result in less records being lost.

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

  3. 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:

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:

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

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:

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.

mo with ocs interim cdrs

Extending CDR content

To customise the content included in Interim CDRs, refer to Customising CDRs from the SDK documentation.

Rf Interface AVPs

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.

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 ]

Ro Interface AVPs

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.

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 ]

Sizing AVP CDRs

This section documents the storage requirements for AVP CDRs.

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

Working with CDRs

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.

Protobuf

Protobuf 2.3.0 is required to build and extend CDR modules included with the SDK. This guide covers installing Protobuf for use with the SDK. If using the product "out of the box", Protobuf is not required.

Topics

Installing List CDRs

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

$ ./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:

$ 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 https://repo.opencloud.come/artifactory/opencloud-internal-snapshots/opencloud/sentinel-core/2.7.0/sentinel-list-cdrs/2.7.0.0/sentinel-list-cdrs-package-2.7.0.0.zip ...
[ivy:resolve] ..... (8971kB)
[ivy:resolve] .. (0kB)
[ivy:resolve] 	[SUCCESSFUL ] opencloud#sentinel-list-cdrs#sentinel-core/2.7.0;2.7.0.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

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:

$ 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:

$ rm -rf sentinel-express-sdk/tools/list-cdrs/

Obtaining CDRs

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.

Running List CDRs

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:

$ ./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:

$ ./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:

log4j.logger.sentinel.cdr=DEBUG

Extension AVPs

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:

    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):

    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:

$ 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: 0
            ProtectedRule: 0
            VendorId: 19808
        OC-Play-Announcement-Id:
            AvpCode: 1002
            AvpName: OC-Play-Announcement-Id
            AvpType: Integer32
            MandatoryRule: 0
            ProtectedRule: 0
            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:

$ 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: 0
            ProtectedRule: 0
            VendorId: 19404
        ACME-My-Second-Custom-Code:
            AvpCode: 1000
            AvpName: ACME-My-Second-Custom-Code
            AvpType: UTF8String
            MandatoryRule: 0
            ProtectedRule: 0
            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. 1 if set, 0 if not set. Indicates whether support of the AVP is mandatory on the receiving end.

ProtectedRule

The "P" bit, indicating the need for encryption. 1 if set, 0 if not set.

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

Installing Protobuf

Protobuf 2.3.0 is required to build and extend CDR modules included with the SDK. The SDK infrastructure makes this version available for download from an Ant target.

Note Protobuf 2.3.0 can be downloaded as a standalone package here. To complete installation, follow the instructions in the included README.txt.

Installing Protobuf from the SDK using Ant

To install Protobuf use the install-protobuf Ant build target under the sentinel-express-sdk/tools directory:

$ cd /home/testuser/sentinel-express-sdk/tools
$ ant install-protobuf

init-build-extensions:

[...]

init-tools-common:

install-protobuf:
     [echo]
     [echo] Retrieving Protobuf...
    [mkdir] Created dir: /home/testuser/sentinel-express-sdk/tools/target
      [get] Getting: https://s3-ap-southeast-2.amazonaws.com/ocaws-downloads/third-party/google/protobuf/protobuf-2.3.0.tar.gz
      [get] To: /home/testuser/sentinel-express-sdk/tools/target/protobuf-2.3.0.tar.gz
      [get] ....................................................
      [get] ....................................................
      [get] ....................................................
      [get] ....................................................
      [get] .....
     [echo]
     [echo] Protobuf retrieved.
     [echo]
     [echo] Unpacking Protobuf...
     [echo]
   [gunzip] Expanding: /home/testuser/sentinel-express-sdk/tools/target/protobuf-2.3.0.tar.gz to /home/testuser/sentinel-express-sdk/tools/target/protobuf-2.3.0.tar
    [untar] Expanding: /home/testuser/sentinel-express-sdk/tools/target/protobuf-2.3.0.tar into /home/testuser/sentinel-express-sdk/tools
     [echo]
     [echo]
     [echo] Protobuf unpacked.
     [echo] Requires further install steps, please read protobuf-2.3.0/README.txt for further details.
     [echo]

BUILD SUCCESSFUL
Total time: 6 seconds

To complete installation, follow the instructions in sentinel-express-sdk/tools/protobuf-2.3.0/README.txt.

Uninstalling Protobuf

If you want to uninstall the version of Protobuf installed by the SDK, use the uninstall-protobuf Ant target under the sentinel-express-sdk/tools/ directory:

$ cd /home/testuser/sentinel-express-sdk/tools
$ ant install-protobuf

init-build-extensions:

[...]

init-tools-common:

uninstall-protobuf:
     [echo] Uninstalling (deleting) the protobuf install from: /home/testuser/sentinel-express-sdk/tools/protobuf-2.3.0/
   [delete] Deleting directory /home/testuser/sentinel-express-sdk/tools/protobuf-2.3.0

BUILD SUCCESSFUL
Total time: 2 seconds

Alternatively, just delete the protobuf-2.3.0 directory:

$ rm -rf sentinel-express-sdk/tools/protobuf-2.3.0/

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