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
-
Installing the SDK has instructions on installing the Sentinel framework
-
Sentinel Overview and Concepts provides a high-level overview of Sentinel
-
Installing the Sentinel Provisioning Module has instructions for installing the Rhino Element manager extension module
Getting Started
This section explains how to set up a standalone version Sentinel Express on a Rhino SDK.
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.
 |
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 |
||
Rhino 2.4.0.14 or later - optional - to be used when installing and configuring Rhino manually |
||
Rhino Element Manager 1.4.0 |
||
Sentinel Express SDK including out of the box installer |
||
(Optional) Cassandra Database, version 2.0.17 or later version from the 2.0.x series |
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 |
|---|---|
2 |
Rhino must be started at least once to generate the necessary configuration files. To start Rhino, in the $ ./start-rhino.sh (or |
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 $ ./stop-rhino.sh --nice |
 |
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 <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:
All of these settings can be found in |
|
Socket permissions |
You will need to add the host address where the installer is running to the mlet configuration file.
<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>
|
 |
Start Rhino to load the new configuration
To start Rhino, in the This applies the Rhino and JVM configuration. |
Get a license
| |
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 |
3 |
In this directory, start the Rhino Console with the |
4 |
In the Rhino Console execute, this command: installlicense [PATH_TO_LICENSE_FILE] ( |
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.
| |
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.
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
| |
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 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 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 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 |
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 sdk.component.version [1.0] > This value will be used for the 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 sdk.ivy.publish.revision [1.0.0] > This value is used as the base of the |
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 |
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 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. |
| |
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 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 cd apache-tomcat-<version> cp /full/path/to/sentinel-express-element-manager-<version>.em.jar rem_home/plugins/ |
|---|
Customize plugin logging
1 |
Unzip cd apache-tomcat-<version> mkdir rem-tmp cd rem-tmp unzip ../webapps/rem.war WEB-INF/classes/log4j.properties |
|---|---|
2 |
Edit 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 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:
-
Sentinel Common Configuration — Configuration data common to one or more Sentinel services.
-
Sentinel for Diameter — Configuration data related to the Sentinel Diameter-to-Diameter mediation service.
-
Sentinel for SIP — Configuration data related to the Sentinel SIP service.
-
Sentinel for SS7 — Configuration data related to the Sentinel SS7 service.
-
Sentinel for USSD — Configuration data related to the Sentinel USSD service.
 |
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 |
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) |
| |
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. |
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. |
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, |
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.
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 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, |
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. |
Sentinel for SIP
| |
See Sentinel Common Configuration for configuration options applicable to all Sentinel services. |
-
Activity Test Configuration for SIP — Determines when Sentinel will test for the continued liveness of a SIP session that has had a period of inactivity.
-
Registrar Cassandra Subscriber Data Store Config — Configuration options for the Cassandra data store facade of the Sentinel Registrar.
-
Registrar Configuration — Configuration options for the Sentinel Registrar.
-
SDP Comparison for Rating Condition Change Determination — 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.
-
SIP Sentinel Configuration — Defines the home network IDs and home country codes for a Sentinel selection key.
-
SIP Session Control Configuration — Determines how the SIP Sentinel service controls the duration of sessions.
-
SIP Third Party Call Configuration — Determines how the SIP Sentinel service behaves when initiating SIP sessions in response to a non-SIP triggering.
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.
| |
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: |
|
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, |
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, |
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, |
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.
|
||
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, |
Provisioning interfaces
The configuration can be provisioned using the Sentinel machine provisioning API — see SIP Third Party Call REST API.
Sentinel for SS7
| |
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.
-
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.
| |
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.
| |
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 |
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 |
|
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, |
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.
| |
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
}
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, |
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:
|
Configuration profile naming
| Configuration Profile Table Name | Description | Profile Naming |
|---|---|---|
DiameterConfigurationTable |
Service configuration |
SentinelSelectionKey (for example, |
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:
|
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, |
Provisioning interfaces
The configuration can be provisioned using the Sentinel machine provisioning API — see SS7 Session Control REST API.
Sentinel for USSD
| |
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.
-
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
| |
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
| |
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
| |
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
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:
-
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.
-
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.
| |
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 |
|
String |
The SLEE profile table with an RA configuration profile for this RA entity. |
|
String |
The SLEE profile in the ConfigProfileTable with configuration for this RA entity. |
|
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 |
|
Int |
The maximum time (measured in ms) the Correlation RA will spend trying to allocate a correlation ID. |
|
Int |
The maximum time (measured in ms) that an active correlation ID is considered to be still valid. |
|
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.
| |
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. |
|
An array of address prefixes that corresponds to this pool. The default pool has an empty addressPrefixes array. |
|
An array of node IDs for which this pool has correlation IDs. |
|
If true, configure this ID pool with a pre-configured set of correlation IDs, else derive the correlation IDs. |
|
The preconfigured set of correlation IDs per node (delimited with ‘:’). |
|
The minimum correlation ID value used in the cluster. 0 to maxCorrelationIDInCluster |
|
The maximum correlation ID value used in the cluster. 0 to (10^18-1) |
|
The number of digits the correlation ID should have. Minimum of number of digits in maxCorrelationIDInCluster to 18 maximum. |
|
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 forNodeIds[0] -
NodeIds[1]—PreconfiguredCorrelationIdSet[1]which is a ‘:’ separated string containing all the correlation IDs forNodeIds[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 ofCorrelationIDRangePerNode[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 |
|---|---|
|
Count of correlation IDs which have been requested via |
|
Count of correlation queries which returned immediately (synchronous delivery) as the local RA had the data available. |
|
Count of correlation queries which did not return immediately (asynchronous delivery) as the local RA did not have the data available. |
|
Count of correlation queries which required delivering data to another correlation RA instance. |
|
Count of correlation queries which could not be remotely delivered as the destination RA for a correlation ID was unknown. |
 |
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 thegetNewCorrelationID(String associatedAddress, byte[] correlationData)method on theCorrelationProvider. 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 theCorrelationProvider. This returns aCorrelationResultwhich 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, andCorrelationResult.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
ActivityContextInterfaceobject 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.CorrelationResultEventevent. -
Handle failures in an event handler for the
com.opencloud.slee.resources.correlation.CorrelationFailureEventevent.
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.
| |
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:
-
Scripted Promotions Feature — may be configured to use a database to store the promotions buckets
-
Friends and Family Feature — may be configured to fetch friends and family data from a relation database
-
Home Zone Feature — may be configured to fetch home zone data from a relation database
-
Subscriber Data Lookup Feature — may be configured to fetch subscriber data from a relation database
| |
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 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
DiameterConfigtable. -
The config profile shows that the known OCS nodes are named
diameterserveranddiameterserver1. -
The routing priority metric for both nodes is set to 1 to indicate equal priority, meaning that load balancing will be applied.
-
The
DiameterMediationOcsConfigurationTableconfiguration 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 caseopencloud). However this behaviour can be overridden on a per-session basis by setting theOCSIdfield in session state using, for example,SubscriberDataLookupor 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)
| |
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 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.
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.
| |
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.
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 networks |
|
|
Diameter networks |
|
|
processing USSD triggers |
|
|
testing |
General Features
Sentinel includes many features that are useable in many networks:
-
Do Not Charge Session Feature — Notifies the Sentinel core to not charge the session.
-
Http Determine Network Operator Feature — Extracts the name of the Network Operator from an HTTP request.
-
OcsParameterConfiguration Feature — Sets the value of two session state fields related to determining the number of units to request from the OCS.
-
Platform Operator is Network Operator 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.
-
Session Tracing Activation Feature — Used to determine if session tracing should be performed on this session or not, based on the subscriberId session state field.
-
Subscriber Data Lookup Feature — 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.
-
Subscriber Validity Feature — Performs a check that a subscriber is within a validity period within two inclusive dates.
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.
| |
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. |
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
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 |
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 |
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, |
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.
| |
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 operator to copy into NetworkOperator field of key |
Runtime exception handled by feature runner |
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, |
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 |
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
| |
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, |
${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, |
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 |
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 |
|
CUGOutgoingAccessAllowed |
Boolean |
|
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 |
PromotionValidityStartDates |
String[] |
Used by the |
PromotionValidityEndDates |
String[] |
Used by the |
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, |
SubscriberDataLookupSqlConfigProfileTableName |
SQL statement configuration |
SentinelSelectionKey (for example, |
${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.
Subscriber Validity Feature
Description
Feature script name |
SubscriberValidity |
|---|---|
Applicable contexts |
All services |
Prerequisite features |
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 |
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:mmformat. -
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 — Performs a MAP AnyTimeInterrogation lookup based on the address selected by a previous execution of the Determine ATI Lookup Number Feature.
-
Determine ATI Lookup Number Feature — An initial trigger feature used to configure a subsequent execution of the ATI Lookup Feature.
-
Determine MNP Lookup Number Feature — An initial trigger feature used to configure a subsequent execution of the MNP Lookup Feature.
-
Determine SRI Lookup Number Feature — An initial trigger feature used to configure a subsequent execution of the SRI for Basic Call Routing Feature.
-
Flash SMS Notification Feature — A pre-credit-check, post-credit-check, or end-session feature.
-
MNP Lookup Feature — A MAP AnyTimeInterrogation MNP lookup based on the address selected by a previous execution of the Determine MNP Lookup Number Feature.
-
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.
-
USSD Push Notification Feature — A pre-credit-check, post-credit-check, or end-session feature early in the feature list.
ATI Lookup Feature
The ATI Lookup feature performs a MAP AnyTimeInterrogation lookup.
Description
Feature name |
ATILookup |
|---|---|
Applicable contexts |
SS7 service |
Prerequisite Features |
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 |
Session State inputs and outputs
Inputs
| Name | Type | Format | Description | Behaviour if null/invalid |
|---|---|---|---|---|
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
selection key (for example, |
For selecting configuration data |
See error handling for |
ATILookupNumber |
String |
MSISDN string |
Subscriber MSISDN to perform the ATI lookup for |
See error handling |
Error scenarios
| Scenario | Handling |
|---|---|
Missing entry in ATILookupFeatureConfigProfileTable |
Increment SendFailures stat |
Null sessionstate ATILookupNumber |
Increment SendFailures stat |
Error parsing ATILookupNumber |
Increment SendFailures stat |
Null sessionstate HLRAddress |
Increment SendFailures stat |
Null sessionstate GSMSCFAddress |
Increment SendFailures stat |
Failed to send request Increment |
SendFailures stat |
ATIResponse missing SubscriberInfo.MnpInfo |
Increment MalformedResponses and ReceivedResponses stats |
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 |
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: |
|
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 |
Return address for responses (such as address of Sentinel) |
|
HLRAddress |
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 |
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, |
For selecting configuration data |
Report |
InitialDPArg |
com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |
InitialDP which triggered this session |
Report |
|
CallType |
com.opencloud.sentinel.common.CallType |
Session type of this call for determining from configuration which party address to look up |
Report |
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, |
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, |
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 |
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, |
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, |
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 |
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, |
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 |
|
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.
| |
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, |
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[] |
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 |
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 |
Abort from HLR |
Increment HlrProviderAborts or HlrUserAborts |
Timeout waiting for HLR response |
Increment HlrTimeouts |
Exception closing dialog in any HLR dialog failure scenario |
Increment SmsDeliveryFailures |
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 |
OpenRefuse from MSC |
Increment MscSS7ProviderErrors |
Abort from MSC |
Increment MscProviderAborts or MscUserAborts |
Timeout waiting for MSC response |
Increment MscTimeouts |
Configuration
The Flash SMS Notification configuration includes:
| Parameter | Type | Description |
|---|---|---|
SccpOriginatingAddress |
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: |
|
InvokeTimeout |
Long |
SRIforSM and MTForwardSM invoke timeouts in milliseconds (for example, 5000). A 0 value results in CGIN RA defaults being used. |
TemplateHlrSccpAddress |
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 |
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 |
Local SCCP address (for example, |
|
AddressStringServiceCentreAddress |
Service centre address (for example, |
|
ShortMsgMTApplicationContext |
The MAP application context to be used for the dialog towards the MSC. Must be one of:
|
Call flow
There are two MAP requests as party of the MTForwardSM process:
-
Obtaining the routing information from the HLR.
-
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
| |
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, |
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 |
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, |
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 |
Error scenarios
| Scenario | Handling |
|---|---|
Missing entry in MNPLookupFeatureConfigProfileTable |
Increment SendFailures stat |
Null sessionstate MNPLookupNumber |
Increment SendFailures stat |
Error parsing MNPLookupNumber |
Increment SendFailures stat |
Null MNPSRFSccpAddress configured in MNPLookupFeatureConfigProfileTable |
Increment SendFailures stat |
Null GSMSCFAddressString configured in MNPLookupFeatureConfigProfileTable |
Increment SendFailures stat |
Exception while trying to send ATIRequest |
Increment SendFailures stat |
OpenRefuse from MNP SRF |
Close dialog Increment SS7ProviderErrors or SS7UserErrors |
Abort from MNP SRF |
Close dialog |
Timeout waiting for MNP SRF response |
Close dialog |
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 |
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: |
|
InvokeTimeout |
Long |
AnyTimeInterrogation invoke timeout in milliseconds (for example, 5000). A 0 value results in CGIN RA defaults being used. |
GSMSCFAddress |
Return address for responses (for example, address of Sentinel) |
|
MNPSRFSccpAddress |
Static address of an MNP SRF. |
Configuration profile naming
| Configuration Profile Table Name | Description | Profile Naming |
|---|---|---|
MNPLookupFeatureConfigProfileTable |
Feature configuration |
SentinelSelectionKey (for example, |
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 |
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, |
For selecting configuration data |
Increment SendFailures stat Report featureFailedToExecute Report featureHasFinished Return |
SRILookupNumber |
String |
MSISDN |
Address for which to perform SRI lookup |
Return |
Error scenarios
| Scenario | Handling |
|---|---|
Missing profile entry in SRIForBasicCallRoutingFeatureConfigProfileTable |
Increment SendFailures stat |
Exception creating MSISDN string using sessionstate SRILookupNumber |
Report featureHasFinished |
Null HLRAddress or GsmScfAddress in config profile |
Increment SendFailures stat |
Exception sending SRI request to HLR |
Increment SendFailures stat |
OpenRefuse from HLR |
Close dialog |
Abort from HLR |
Close dialog |
Timeout waiting for HLR response |
Close dialog |
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 |
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: |
|
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 |
HLRAddress |
HLR address for the SRI |
|
GSMSCFAddress |
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, |
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 |
|
Prerequisite features |
|
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, |
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 |
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 |
Configuration
The USSD Push Notification configuration includes:
| Parameters | Type | Description |
|---|---|---|
SccpOriginatingAddress |
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: |
|
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
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
WaitForConfirmationtrue mode, the feature will immediate return continue once the notify request is sent and will not wait for the response. -
In
WaitForConfirmationfalse 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, |
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 — Allows the dialog processing to proceed if the application context is acceptable.
-
Call Barring Feature — A network operator barring feature.
-
Classify Call Scenario Feature — Classifies the call’s Session Type, Roaming Indicator, and Service Type, which are stored in session state variables for future features.
-
Call Forwarding Detection Feature — Analyses an MT initialdp to determine if early call forwarding applies for this call.
-
Closed User Group Feature — Indicates to the OCS any CUGs that apply to the current session, and optionally restricts a subscriber to sessions within a CUG.
-
Connect And Close Feature — An initial trigger feature which calls connectAndClose() on the feature endpoint.
-
Continue And Close Feature — An initial trigger feature which calls continueAndClose() on the feature endpoint.
-
Do Not Monitor Session Feature — An initial trigger feature which instructs Sentinel core not to monitor the call.
-
Emergency and Special Number Feature — 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.
-
Friends and Family Feature — Sets a special OCS tariff code if a subscriber is making a call to a number in their FnF list.
-
Home Zone Feature — Determines if the subscriber is within a defined set of home zones on originating calls.
-
Play Announcement Feature — Plays an announcement to the calling party during call establishment or after the called party disconnects.
-
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.
-
Relay Dialog During Dialog Analysis Feature — Requests Sentinel core to relay the received dialog to another network element.
-
Relay Dialog During Initial Trigger Analysis Feature — Requests Sentinel core to relay the received dialog to another network element.
-
Release Call and Close Dialog Feature — A very simple feature that instructs Sentinel to release the call or SMS and close the dialog with the MSC.
-
Roaming Default Call Forwarding Feature — Defines roaming-specific forwarding addresses for Busy, No reply cases, to prevent tromboning of forwarded calls to numbers in the subscriber’s HPLMN.
-
Roaming Re-origination Feature — 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.
-
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.
-
Short Code Feature — 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.
-
SMS Normalization Feature — All features executed after this feature access the normalized numbers when accessing the idp in session state.
-
SS7 Determine Network Operator Feature — Sets the Network Operator element of the Sentinel selection key, based on the value returned by the DetermineNetworkOperator function
-
SS7 Subscriber Determination Feature — Used to determine the subscriber address, based on parameters from the InitialDP and session state.
-
SS7 Unconditional Reject Session Feature — Unconditionally refuses the dialog with refuse reason set to USER_NO_REASON_GIVEN.
-
Validate 3rd Party Call Request Feature (SS7) — Checks the received HTTP request to see if it is well formed.
-
Validate InitialDP Feature — Performs validation checks to ensure that the InitialDP has sufficient parameters to be handled correctly by Sentinel.
-
Voice Call Normalization Feature — All features executed after this feature will access the normalized numbers when accessing the idp in session state.
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, |
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, |
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 |
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.
| |
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 |
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 |
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, |
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 |
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 |
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.)
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
| |
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, |
For selecting configuration data |
Report featureCannotStart, featureHasFinished |
InitialDPArg |
com.opencloud.slee.resources.cgin.cap_v1.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, |
TeleServiceConfigProfileTable |
TeleService configuration |
SentinelSelectionKey + ':' + TeleServiceCode (for example, |
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.
| |
The ICB and OCB capabilities of the CUG Supplementary Service are not supported:
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, |
For selecting configuration data |
Report featureCannotStart, featureHasFinished |
InitialDPArg |
com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |
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) |
|
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 |
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) |
|
ClosedUserGroupEnabled |
Boolean |
true or false |
Whether the subscriber has closed user group support enabled |
Equivalent behaviour if null or false |
ClosedUserGroupList |
String[] |
Array of closed user group names |
The closed user groups this subscriber belongs to |
Increment ClosedUserGroupNotEnabled |
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 |
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 |
SessionState: CUG preferred id is invalid |
Set sessionstate ClosedUserGroupCall to false |
OtherPartyAddress could not be set successfully |
Set sessionstate ClosedUserGroupCall to false |
No CUG Group was selected |
Set sessionstate ClosedUserGroupCall to false |
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, |
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
Continue and Close Feature
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.
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, |
For selecting configuration data |
Report featureCannotStart, featureHasFinished |
InitialDPArg |
com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |
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.
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 |
|
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, |
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 |
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 |
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 |
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, |
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, |
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 |
Error scenarios
| Scenario | Handling |
|---|---|
Sessionstate |
CallType is null Set Sessionstate InHomeZone to false |
Sessionstate InitialDPArg is null |
Set Sessionstate InHomeZone to false |
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, |
HomeZoneFeatureSqlProfileTable |
SQL statement configuration |
SentinelSelectionKey (for example, |
HomeZoneFeatureZonesProfileTable |
Zone table if profiles selected |
SentinelSelectionKey:ZoneName (for example, |
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
ConnectToResourceonly, to connect to an SRF integrated with the controlling MSC. -
Using
EstablishTemporaryConnectionand an assisting dialog to connect to a non-integrated SRF. -
Using
Connectto 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 |
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
selection key (for example, |
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 |
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 |
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 |
Announcements can reference variables based on latest CCA see Configuration |
No action |
Error scenarios
| Scenario | Handling |
|---|---|
Null CorrelationProvider |
Increment ConfigurationErrors |
Sessionstate SentinelSelectionKey is null |
Increment InputParameterErrors |
ACI not provided to the announcement feature |
Increment InputParameterErrors |
No profile for selection key and AnnouncementID in AnnouncementProfileTable |
Increment InputParameterErrors |
No profile for selection key in AnnouncementConfigProfileTable |
Increment InputParameterErrors |
Null TariMillis in AnnouncementConfigProfile |
Increment InputParameterErrors |
Exception invoking RequestReportBCSM on dialog |
Increment ErrorsArmingAbandon |
Dialog object not provided to the announcement feature in the activity context interface |
Increment InputParameterErrors |
Invalid type configured for the announcement ID (Should be tone, message or messages) |
Increment InputParameterErrors |
TooManyInvokesException or ProtocolException whiling sending CTR or PlayAnnouncement |
Increment ErrorsSendingCTRAndPA |
Received SS7 Abort |
Increment Ss7Aborts |
Received SS7 Error |
Increment Ss7Errors |
Received Abandon or Disconnect |
If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input |
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 |
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 |
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 |
|
[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 |
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 |
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. |
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, |
AnnouncementResourceConfigProfileTable |
ConnectToResource resource configuration |
SentinelSelectionKey:ctrConfigName (for example, |
AnnouncementConfigProfileTable |
Additional resource configuration |
SentinelSelectionKey:configName (for example, |
${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 |
|
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.
| |
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 |
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 |
Inputs
| Name | Type | Format | Description | Behaviour if null/invalid |
|---|---|---|---|---|
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
selection key (for example, |
For selecting configuration data |
Report featureCannotStart, featureHasFinished |
InitialDPArg |
com.opencloud.slee.resources.cgin.cap_v1. |
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.
Feature responses
| Response | Reason |
|---|---|
relayDialog |
the dialog should be relayed |
featureHasFinished |
feature has finished |
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 |
Prerequisite features |
None |
This feature requests Sentinel core to relay the received dialog to another network element.
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
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 |
Release Cause to use for call control session release |
Report featureCannotStart, featureHasFinished |
|
SMSUserReleaseCause |
com.opencloud.slee.resources.in.datatypes.sms.RPCause |
Release Cause to use for SMS session release |
Report featureCannotStart, featureHasFinished |
|
LatestOcsAnswer |
org.jainslee.resources.diameter.ro.types.CreditControlAnswer |
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 |
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, |
For selecting configuration data |
Runtime exception handled by feature runner |
LatestEventReportBCSM |
com..opencloud..slee..resources..cgin..callcontrol..CCEventReportBCSMArg |
Argument of the latest event report BCSM received |
Report featureCannotStart, featureHasFinished |
|
InitialDPArg |
com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |
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 |
CfNoReply |
String |
MSISDN |
Call forwarding destination address when subscriber does not answer |
If CfBusy also null, increment FeatureNotEnabledForSubscriber |
Subscriber |
String |
MSISDN |
For recording RedirectingPartyNumber in the connect arg if call forwarding is triggered |
Runtime exception handled by feature runner |
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.
| |
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. |
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, |
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 |
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.
| |
See Correlation Resource Adaptor to understand how the reorigination-correlation-ra works and how it can be configured |
| |
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
InitialDPstored 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
Session state inputs and outputs
Inputs
| Name | Type | Format | Description | Behaviour if null/invalid |
|---|---|---|---|---|
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
selection key (for example, |
For selecting configuration data |
Report featureCannotStart, featureHasFinished |
InitialDPArg |
com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |
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 |
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 |
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:
-
if the dialog is for originating treatment. The first
InitialDPwill be triggered on DP2 (Collected Info). Terminating and forwarded dialogs are not re-originated. -
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).
-
-
if the
InitialDP VLR addressis for a roaming party for which re-origination is supported. Roaming partners that do not support theERB(Disconnect)+ACHguarantee 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:
-
Create the address we will use to select an id-pool.
-
Create the data that we will associate with the correlation ID.
-
Get a new correlation entry (passing the address and correlation data).
-
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.
| |
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
CAP1InitialDPArgobject -
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[].
| |
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:
-
The re-originated InitialDP will be triggered on DP3 (Analyzed Info).
-
The application context is supported. Supported application contexts are:
-
cap-v2-gsmSSF-to-gsmSCF-AC
-
capssf_scfGenericAC (CAP3).
-
-
The called party is a special routing number.
| |
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
CAP1InitialDPArgobject -
copies the cap 1
InitialDPcalled party bcd number to the re-originatedInitialDP -
copies the cap 1
InitialDPbearer capability (if present) to the re-originatedInitialDP -
copies the cap 1
InitialDPredirecting party ID (if present) to the re-originatedInitialDP -
copies the cap 1
InitialDPredirection information (if present) to the re-originatedInitialDP -
copies the cap 1
InitialDPlocation information (if present) to the re-originatedInitialDP -
copies the cap 1
InitialDPextensions (if present) to the re-originatedInitialDP -
sets the
InitialDPsession state field with the updated re-originatedInitialDP.
| |
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. |
| |
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:
|
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.
Configuration
Correlation RA configuration
| |
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 |
The address nature |
|
NumberingPlan |
The numbering plan of the address |
|
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, |
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, |
For selecting configuration data |
Report featureCannotStart, featureHasFinished |
CAP3InitialDPSMSArg |
com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg |
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 |
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 |
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, |
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, |
Only updated if network operator is determined |
OriginatingSccpAddress |
com.opencloud.slee.resources.cgin.SccpAddress |
Set to triggering DialogOpenRequestEvent originating address |
|
ResponderSccpAddress |
com.opencloud.slee.resources.cgin.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 |
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 |
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 |
InitialDP which triggered this session |
Fall back to CAP3InitialDPSMSArg |
|
CAP3InitialDPSMArg |
com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg |
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 |
Error scenarios
| Scenario | Handling |
|---|---|
InitialDPArg and InitialDPSMSArg not present or do not contain subscriber address |
Report featureFailedToExecute |
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.
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
EventReportBCSMcontains 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
EventReportBCSMcontains 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
EventReportBCSMcontains 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 |
Latest event report |
Do not set release cause |
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 |
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.
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 \ |
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 |
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, |
${PLATFORMOPERATOR}_ShortCode_AddressListConfigurationTable |
Address list configuration |
${SELECTIONKEY}:ShortCode:AddressList |
${PLATFORMOPERATOR}_ShortCode_AddressListEntryTable |
Feature specific Address List entry table |
${SELECTIONKEY}:ShortCode:AddressList:${ADDRESS} |
Validate InitialDP Feature
Description
Feature name |
ValidateInitialDP |
|---|---|
Applicable contexts |
SS7 service |
Typical feature execution points |
DirectAccess_SessionPreCreditCheck |
Prerequisite features |
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, |
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 |
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, |
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 |
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.
| |
The SS7 service only accepts the HTTP request for processing if the path contains sentinel-ss7 |
Error scenarios
| Scenario | Handling |
|---|---|
IOException while retrieving HttpRequest content |
Increment CouldNotProcessHttpRequest |
Report |
refuseDialog |
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, |
For configuring normalizer |
Runtime exception handled by feature runner |
InitialDPArg |
com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |
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 |
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 |
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:
-
Third Party Registrar System Features — critical features that process a 3rd party REGISTER request trigger, and can be used in feature execution pre and post scripts
-
Third Party Registar User Features — features that can be used in feature execution user scripts
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 — Parses the received third party REGISTER request body and extracts the 1st party REGISTER request and response
-
Extract Public and Private Identities — Analyses the 1st party REGISTER request and response and extracts public and private indentities
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.
| |
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 |
|
Session state inputs and outputs
Inputs
| Name | Format | Description |
|---|---|---|
SentinelSelectionKey |
selection key |
For selecting a mapper that maps third party REGISTER request to session state fields |
Outputs
| Name | Format | Description |
|---|---|---|
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 |
A |
The 1st party REGISTER request |
EncapsulatedRegisterResponse |
A |
The 1st party REGISTER response |
RejectRegisterRequest |
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.
| |
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 |
|
Session state inputs and outputs
Inputs
| Name | Format | Description |
|---|---|---|
SentinelSelectionKey |
selection key |
For selecting a mapper that maps 1st party REGISTER and response to public and private ids in session state fields. |
EncapsulatedRegisterRequest |
The 1st party REGISTER request |
|
EncapsulatedRegisterResponse |
The 1st party REGISTER response |
Outputs
| Name | Format | Description |
|---|---|---|
CallId |
The value of the |
The call id of the 1st party REGISTER request |
PrivateId |
The username parameter of the |
The private id of the subscriber, taken from the 1st party REGISTER request |
PublicIds |
The value of a |
Public ids of the subscriber, taken from |
RegisteredContact |
Array of Strings, where each element is value of one |
All the |
RegisteredContactUris |
Array of Strings, where each element is |
The |
PubGruu |
A SIP URI, as a String |
The public GRUU (Globally Routable User Agent) from the first |
TempGruu |
A SIP URI, as a String |
The temporary GRUU (Globally Routable User Agent) from the first |
RejectRegisterRequest |
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.
-
AcceptRegisterRequest — Issues a 200 OK on the triggering REGISTER leg.
-
RegistrarDetermineNetworkOperator — Determines which network operator a REGISTER request is related to, in a multi-tenancy deployment.
-
FetchPreviousRegistrationData — Retrieves pre-existing, active registration data associated with an incoming REGISTER request.
-
DetermineRegistrationActionType — Classifies a REGISTER request according its type (register, re-register, or de-register).
-
DetermineRegistrationSessionType — Classifies a REGISTER request according to how it should be handled. For example, is this an ESRVCC registration scenario, or a regular registration scenario.
-
DetermineVisitedNetwork — Extracts a value from the p-visited-network-id header(s) to be included in registration data.
-
RegistrarPlatformOperatorIsNetworkOperator — Records that the network operator is the same as the platform operator. (Used in the single-tenancy case.)
-
ScheduleRejectRegisterRequest — Signals to the SIP core that the 3rd party REGISTER request should be rejected.
-
RejectRegisterRequest — Issues a SIP error response on the triggering REGISTER leg.
-
RemoveRegistration — It removes all Third Party Registration state associated with the current Registration from Data Storage.
-
StoreSubscriberData — Writes Third Party Registration state to Data Storage.
-
WriteRegistrarAuditCdr — Writes an audit Call Detail Record (CDR) that summarises the action taken on the triggered REGISTER request.
-
DeterminePublicIdentities — Checks and retrieves Public ID information for a registration.
Accept REGISTER Request
Determine Public Identities
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. |
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:
-
If the
REGISTERrequest 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 theREGISTERrequest. -
If the
REGISTERrequest is for registration or re-registration, or third-party registration data is currently stored in the HSS; then the feature will immediately reject theREGISTERrequest.
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:
| 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 |
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-mgmtand+g.3gpp.atcf-pathparameters 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
Determine Visited Network
This feature extracts a value from the p-visited-network-id header(s) that is to be included in registration data.
| |
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
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 |
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:
-
Use the platform level default.
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 |
Mappers
This feature uses a mapper that conforms to:
| Mapping | Mapper Execution Point |
|---|---|
IncomingSipRequest.class → String.class |
RegistrarMappingPoint.DetermineNetworkOperator |
Feature responses
featureFailedToExecute() |
|
|---|---|
featureHasFinished() |
Once the feature has finished execution. |
Statistics
Stats interface |
DetermineNetworkOperatorStats |
|---|---|
Parameter set to monitor |
|
| 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 |
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 |
|---|---|
|
|
|
|
|
|
Details
Feature script name |
RejectRegisterRequest |
|---|---|
Applicable contexts |
SIP service |
Prerequisite features |
None |
Session state inputs and outputs
Inputs
| Name | Format | Description |
|---|---|---|
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 |
An |
The SIP error response code to use when rejecting the third party REGISTER request |
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 |
|---|---|
CallId |
The call-id associate with the activation session |
PrivateId |
The private-id of the UE |
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).
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 |
|---|---|
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 |
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 |
|
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.
-
B2BUA Feature — Performs B2BUA Behaviour, setting up an outgoing dialog and forwarding SIP Messages between the dialogs.
-
B2BUA SCUR Features — Provide default session charging behaviour for Sentinel SIP as a B2BUA.
-
B2BUA IEC Features — Provide immediate event charging for Sentinel SIP as a B2BUA.
-
B2BUA ECUR Features — Provide event charging with unit reservation for Sentinel SIP as a B2BUA.
-
Session Refresh Feature — Periodically instructs all INVITE dialog legs to refresh.
-
SIP Downstream Forking Feature — Handles a SIP call forked downstream by the S-CSCF, an application, or other UAS.
-
Subscribe Downstream Forking Feature — Handles a SIP subscription forked downstream by the S-CSCF, an application, or other UAS.
-
SDP Comparison Feature — Updates charging information with the OCS when the media streams of a session have changed.
-
SDP Monitor Feature — Keeps track of SDP offers and answers on a leg.
-
Remove Headers From Outgoing Messages Feature — removal of headers from outgoing messages based on configuration.
-
SDP Rewriter Feature — Rewrites SDPs to avoid conflicts between legs.
-
Sequential Forked SDP Mediation — Ensures that the SDPs in responses to sequentially forked invites are delivered as UPDATES , not as 183s.
-
Max Call Duration Feature — Monitors the call duration and terminate the call if the maximum time has exceeded.
-
AVP CDR Feature — Writes a Call Detail Record in AVP format when the session ends.
-
Legacy CDR Feature — Writes a Call Detail Record when the session ends (deprecated).
-
SIP Do Not Charge Feature — Disables charging of the current session.
-
Diameter Service Info Feature — Constructs
IMS-InformationandPS-InformationAVPs for CDRs and Credit-Control-Requests. -
Determine Cause Code Feature — Determines the value to be used for the
Cause-CodeAVP in theIMS-InformationAVP -
Record Timestamps Feature — Records the time at which the initial INVITE and the associated final response were received.
-
Store Header Info Feature — Records in session state various pieces of information required by other features.
-
Extract Network Info Feature — Records in session state the MCC and MNC values for the subscriber parsed from PVNI and PANI headers.
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.
| |
By default, Sentinel runs 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 |
|
CallId |
String |
The unique ID of the call |
|
CallingPartyAddress |
String |
The address of the calling party |
|
CallType |
Enumerated |
The type of the call. One of |
|
ChargingResult |
int |
The result code of the Diameter session |
Sentinel SIP service |
DiameterServiceContextId |
String |
The Diameter context ID of the relevant service |
|
EndSessionCause |
Integer |
The end session cause code |
|
EventId |
String |
|
|
ImsInformation |
org.jainslee.resources.diameter .ro.types.vcb0.ImsInformation |
The IMS-Information Diameter AVP |
|
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, |
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 |
|
Subscriber |
String |
The subscriber associated with the session |
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.
| |
This feature only supports writing binary CDRs. If the cdr-ra is configured to write text CDRs the feature will fail to execute. |
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- 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).
| |
|
| |
|
Session state inputs and outputs
Inputs
| Name | Format | Description | Behaviour if null/invalid |
|---|---|---|---|
SentinelSelectionKey |
Selection key |
For selecting mappers |
Increment InputParameterErrors Common cleanup actions |
CurrentSipFeatureExecutionPoint |
Enum value |
Used to classify the triggering event |
N/A |
B2BUAChargingCounterAddress |
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 |
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 |
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 |
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_INSTANCEitself -
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.
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.
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);
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).
| |
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 |
|
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 |
|
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
| |
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. |
| |
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 |
selection key (for example, |
For selecting mappers |
Increment InputParameterErrors Common cleanup actions |
CurrentSipFeatureExecutionPoint |
Enum value |
Used to classify the triggering event |
N/A |
B2BUAChargingCounterAddress |
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 |
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 |
Non-negative long |
The number of pending requested units |
N/A |
Outputs
| Name | Format | Description |
|---|---|---|
B2BUAChargingCounterAddress |
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_INSTANCEitself -
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.
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);
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
ReAuthRequestsfrom 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,
| |
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 |
|
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 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_INSTANCEitself -
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.
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.
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);
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
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 |
|---|---|
|
Dialog was terminated with a SIP 3xx response. The actual value of the code will match the response status. |
|
Dialog was terminated with a SIP 2xx response. The actual value of the code will match the response status. |
|
Subscription dialog ended normally. |
|
Transaction dialog ended normally. |
|
Invite session ended normally. |
|
Invite session setup failed. |
|
There was an internal error in Sentinel and no other code can be determined. |
|
Dialog was terminated with a SIP 4xx response. The actual value of the code will match the response status. |
|
Dialog was terminated with a SIP 5xx response. The actual value of the code will match the response status. |
|
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 |
|---|---|---|
|
Invite Session |
|
|
Invite Session |
|
|
Subscription |
|
|
Transaction |
|
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.
-
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.
-
Check if the calling leg has already been released by the leg manager. If this has happened, one of two things can happen:
-
If a cause code had previously been determined in an earlier run of the feature, that code will be preserved.
-
If no cause code has been determined, then
-1(Successful transaction) will be used.
-
-
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:
-
If the response status is
200 OKthen a code of-1(Successful transaction) will be used. -
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.
-
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.
-
Check if the calling leg has already been released by the leg manager. If this has happened, one of two things can happen:
-
If a cause code had previously been determined in an earlier run of the feature, that code will be preserved.
-
If no cause code has been determined, then
-2(End of subscribe dialog) will be used.
-
-
Check if the most recently received
SUBSCRIBErequest has aExpiresheader with the value0. If this is the case, then-2(End of subscribe dialog) will be used. -
Check for a final response the most recent
SUBSCRIBErequest (regardless of whether it has been sent or is queued) that has a status that is greater than or equal to300. 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.
-
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.
-
Check if the calling leg has already been released by the leg manager. If this has happened, one of two things can happen:
-
If a cause code had previously been determined in an earlier run of the feature, that code will be preserved.
-
If no cause code has been determined, then
2(Unsuccessful session setup) will be used.
-
-
Check if a SIP
BYErequest has been sent or received, or is queued to be sent on the calling party leg. If this is the case, then2(Unsuccessful session setup) will be used. -
Check for a final response to the initial
INVITErequest (regardless of whether it has been sent or is queued) that has a status that is greater than or equal to300. 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 |
PerLegFinalResponseTimeMillis |
long |
Holds the time when the initial INVITE final response arrived on each leg. Used for the |
ChargingIdentifier |
String |
Used for the |
Outputs
| Name | Type | Description |
|---|---|---|
ImsInformation |
org.jainslee.resources.diameter.ro.types.vcb0.ImsInformation |
The |
PerLegEventType |
Map<String, org.jainslee.resources.diameter.ro.types.vcb0.EventType> |
The table of leg names mapped to their corresponding |
PerLegEarlyMediaDescription |
Map<String, org.jainslee.resources.diameter.ro.types.vcb0.EarlyMediaDescription> |
The table of leg names mapped to their corresponding |
PerLegSdpMediaComponents |
Map<String, org.jainslee.resources.diameter.ro.types.vcb0.SdpMediaComponent> |
The table of leg names mapped to their corresponding |
PerLegTimeStamps |
Map<String, org.jainslee.resources.diameter.ro.types.vcb0.TimeStamps> |
The table of leg names mapped to their corresponding |
PerLegCallingPartyAddress |
MultiMap<String, String> |
The table of leg names mapped to their corresponding |
PerLegCalledPartyAddress |
MultiMap<String, String> |
The table of leg names mapped to their corresponding |
PerLegCarrierSelectRoutingInformation |
Map<String, String> |
The table of leg names mapped to their corresponding |
PerLegRequestedPartyAddress |
Map<String, String> |
The table of leg names mapped to their corresponding |
PerLegInitialCallingPartyRequestURIString |
Map<String, String> |
The table of leg names mapped to IntialCallingPartyRequestURI - used for the |
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 |
TerminatingInterOperatorIdentifier |
String |
Used for the |
IMEI |
String |
Used as the |
UserSessionId |
String |
The session’s Call-ID, used for the |
IMSChargingId |
String |
The |
CallType |
Enum |
Used to set the |
AccessNetworkInfo |
String |
Used for the |
DiameterCauseCode |
int |
Used for the |
ChargingIdentifier |
String |
Used for the |
Outputs
| Name | Type | Description |
|---|---|---|
ImsInformation |
org.jainslee.resources.diameter.ro.types.vcb0.ImsInformation |
The |
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 |
PaniMccsMncs |
List<com.opencloud.sentinel.common.MccMnc> |
If set, the feature will not attempt to do |
RegistrationRecords |
RegistrationRecord |
|
Outputs
| Name | Type | Description |
|---|---|---|
PvniMccMnc |
com.opencloud.sentinel.common.MccMnc |
The |
PaniMccsMncs |
List<com.opencloud.sentinel.common.MccMnc> |
A list of |
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, |
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.
| |
By default, Sentinel runs 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 |
|
LegForCdrs |
String |
Name of the leg for which CDRs should be written |
Defaults to |
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 |
|
CallType |
Enumerated |
The type of the call. One of |
|
ChargingResult |
int |
The result code of the Diameter session |
Sentinel SIP service |
DiameterServiceContextId |
String |
The Diameter context ID of the relevant service |
|
EndSessionCause |
Integer |
The end session cause code |
|
EventId |
String |
|
|
ImsInformation |
org.jainslee.resources.diameter .ro.types.vcb0.ImsInformation |
The IMS-Information Diameter AVP |
|
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, |
Various features |
SipServiceType |
Enumerated |
The type of service Sentinel is processing. One of |
|
Subscriber |
String |
The subscriber associated with the session |
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
SipInterimCdrfeature timer, if no CDR has been recently written -
On session end
-
When a feature (e.g. SDP Monitor) sets
WriteCdrOnSDPChangeto true
Also see Charging Information for general information about the contents of CDRs and CCRs.
| |
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, |
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.
| |
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 |
|
CallId |
String |
The unique ID of the call |
|
CallingPartyAddress |
String |
The address of the calling party |
|
CallType |
Enumerated |
The type of the call. One of |
|
ChargingResult |
int |
The result code of the Diameter session |
Sentinel SIP service |
EndSessionCause |
Integer |
The end session cause code |
|
EventId |
String |
|
|
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, |
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 |
|
Subscriber |
String |
The subscriber associated with the session |
|
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 |
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.
| |
This feature only supports writing binary CDRs. If the cdr-ra is configured to write text CDRs the feature will fail to execute. |
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 |
|
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 selecting configuration data |
Increment InputParameterErrors, |
CallEstablished |
Boolean |
|
|
Initially set to |
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
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 |
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
HeadersToRemoveFromOutgoingMessagesconfiguration will be removed. -
For any SIP message present on a leg’s SipMessageQueue any
Supportedheader value matching an entry in theSupportedHeaderValuesToToRemoveFromOutgoingMessagesconfiguration will be removed.
| |
In order to capture all outgoing SIP messages this feature should be the last feature to run in If configured this feature will modify the content of any outgoing message with a matching header or See Sentinel SIP Feature Execution Points for more information. |
Details
Feature script name |
RemoveHeadersFromOutgoingMessages |
|---|---|
Applicable contexts |
SIP service |
Prerequisite features |
none |
Feature execution points |
|
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 |
SupportedHeaderValuesToRemoveFromOutgoingMesssages |
String[] |
Each entry of the array represents a value e.g |
| |
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 |
FailedToRemoveHeaderFromOutboundMessage |
A header matching a configured |
RemovedSupportedHeaderValueFromOutboundMessage |
A |
FailedToModifySupportedHeaderOfOutboundMessage |
A failure occurred removing a |
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 |
Feature execution points |
|
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:
See SDP Comparison for an overview of the process
Session state inputs and outputs
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 |
Audio16KHzSingleChannel |
DVI4/16000/1 |
Video90KHzSingleChannel |
MPV/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:
-
When an SDP offer is received, the feature updates the leg’s
latestReceivedSDP,previousReceivedSDPandlatestReceivedSDPSequenceNumberand waits for the corresponding answer. -
When the corresponding SDP answer is sent, the feature updates the leg’s
latestSentSDP,previousSentSDPandlatestSentSDPSequenceNumber. -
If the offer/answer exchange is successful the current
committedSDPbecomes thepreviousCommittedSDPand the leg’scommittedSDPis set to the latest sent SDP on the leg. ThecommittedSDPSequenceNumberis set to the latest SDP sequence number. -
If the offer/answer exchange is unsuccessful, the previous
committedSDPandcommittedSDPSequenceNumbervalue(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- 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 |
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. |
Feature responses
| Response | Reason |
|---|---|
featureHasFinished |
Feature has finished. |
featureCannotStart |
Feature parameter error and was unable to start. |
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.
| |
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 |
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. |
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
ReservationChargingInstancein the session, clears any charging instructions that are pending and finalises charging if the charging instance is not in theFinalstate. -
sets the
MonitorCallOnlysession state field totrue.
| |
|
Details
Feature script name |
DoNotChargeSipSession |
|---|---|
Applicable contexts |
SIP service |
Prerequisite features |
N/A |
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.
Call flows
S-CSCF Downstream Forking call flow examples. For simplicity, these examples have non-reliable provisional responses.
Downstream fork error
SCSCF forks INVITE downstream of Sentinel. B-Party- B' send 487 Final response
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).
| |
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.
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 |
|
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 |
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 |
Session Refresh Feature
The Session Refresh feature periodically instructs all INVITE dialog legs to refresh.
-
On an incoming initial
ACKor when thecallEstablishedsession state field istrue, a timer is set to the duration specified by theTimerIntervalin the feature’s configuration. -
On the expiry of the timer, it is reset and
Leg.refreshSessionis instructed on each leg using theRefreshPeriodfrom the feature’s configuration. -
The
RefreshPeriodrepresents the period of no activity before a refresh request should occur. If no messages have been sent or received on a leg within theRefreshPeriod, 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.
| |
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 |
|
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 selecting configuration data |
Increment InputParameterErrors common cleanup actions |
CallEstablished |
Boolean |
|
|
Initially set to |
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. |
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.
| |
3GPP TS 24.229 (Release 8 and later) permits multiple |
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-valuewill be taken and stored in theIMSChargingIdsession state field. -
If the
term-ioiparameter is present, its value will be taken and stored in theTerminatingInterOperatorIdentifiersession state field. -
If the
orig-ioiparameter is present, its value will be taken and stored in theOriginatingInterOperatorIdentifiersession state field. -
If any additional charging identifier parameters are present, one will be taken and stored in the
ChargingIdentifiersession state field.-
Any of the following parameters can be used:
gcid,dslcid,bcid,itc-id, orecid. -
If no additional charging identifiers are found, the
icid-valuewill be used for theChargingIdentifier.
-
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.
Subscribe Downstream Forking Feature
The Subscribe Downstream Forking Feature manages the additional SIP legs that can result from forked subscriptions.
-
When Sentinel sends or forwards an initial SUBSCRIBE, a downstream proxy may fork the request to several targets.
-
Each target that accepts the SUBSCRIBE will send an initial NOTIFY back to Sentinel.
-
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 .
-
If additional NOTIFYs arrive as a result of a fork, then the
SubscribeDownstreamForkingfeature is needed to determine how to handle them. -
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 theSubscribeDownstreamForkingfeature automatically rejects the NOTIFY with a 481 response, and no new leg is created. -
If the event package does support forking, then the
SubscribeDownstreamForkingfeature 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 |
|
Feature execution point |
SubscriptionSipRequest [Pre] |
Example Call Flows
Session state inputs and outputs
Inputs
| Name | Type | Format | Description |
|---|---|---|---|
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
selection key |
For selecting configuration data |
Outputs
| Name | Type | Format | Description |
|---|---|---|---|
ForkedNotifyResult |
ForkedNotifyResult |
Enum values: |
Describes the outcome of the feature:
|
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 — Verifies the triggering event is a SIP INVITE and initializes a SIP session.
-
B2BUA Subscription Activity Guard Feature — Shuts down subscriptions that don’t end cleanly.
-
Call Parties Address Determination Feature — Attempts to extract the called and calling parties addresses from the
INVITEand set the ‘CallingPartyAddress’ and ‘CalledPartyAddress’ session state fields. -
Determine Call Type 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.
-
Determine Chargeable Leg Feature — Sets the chargeable leg based on the call type
-
Determine If Roaming Feature — Sets the call’s Roaming Indicator, which is stored in a session state variable for future features.
-
Determine Registration Status 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.
-
Determine Service Type Feature — Classifies the call’s service Type, which is stored in a session state variable for future features.
-
End Mid Session Feature — Used to notify the Sentinel core to end the call.
-
End Session Feature — An initial trigger feature to notify the Sentinel core to end the call. Supports ‘sip_trigger’, ‘http_trigger’ and ‘sipcall’ session types.
-
Reauthorize Credit Feature — Used to notify the sentinel core to reauthorize credit post initial credit check.
-
Send Failure End Session Feature — Used to notify the sentinel core to end session on a send message instruction failure.
-
SIP Determine Network Operator Feature — Sets the Network Operator element of the Sentinel selection key, based on the value returned by the DetermineNetworkOperator function
-
SIP Mid Session Play Announcement Feature — Plays an announcement to the configured party during mid session.
-
SIP Normalization Feature — Normalizes the
request-URIand other select address headers in the receivedINVITErequest. -
SIP Play Announcement Feature — Plays an announcement to the calling party during call establishment.
-
Sip Set Language Feature — Sets the language used by the announcement features
-
SIP Prefix and Suffix Analysis Feature — Performs prefix and suffix digit analysis on the
request-URIof the receivedINVITErequest. -
SIP Short Code Feature — A pre-credit check feature that performs number translation of short-codes in the
request-URIof the receivedINVITErequest. -
SIP Subscriber Determination Feature — Inspects the SIP INVITE to determine the subscriber address for this session and set the Subscriber session state field.
-
SIP Third Party HTTP Trigger Feature — Creates the A and B party legs with the
INVITEmessages based on the parameters from the received HTTP request. -
SIP Third Party Call Setup Feature — Manages third party call setup and SDP negotiation.
-
SIP Third Party Charging Feature — Setup SCUR charging instance for third party call.
-
Subscription Expiry Feature — Used to manage expiry timers for active subscriptions.
-
Unconditional Reject Session Feature — Unconditionally rejects a session with SIP response of SC_FORBIDDEN.
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, |
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, |
Updated selection key including session type determined from application context |
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. |
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 |
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 |
Error scenarios
| Scenario | Handling |
|---|---|
Address record in SIP Invite is null or missing URI |
Report featureCannotStart |
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 |
Configuration feature naming
| Configuration Profile Table Name | Description | Profile Naming |
|---|---|---|
DetermineCallTypeConfigurationTable |
Sentinel configuration table |
SentinelSelectionKey (for example, |
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 |
CallTypeIsMobileTerminating |
The feature determines that the call type is |
CallTypeIsMobileForwarded |
The feature determines that the call type is |
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 |
|---|---|
|
|
|
|
|
|
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 |
|---|---|
|
|
|
|
|
|
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:
-
The
Request-URIhas acauseparameter with one of the following values:302,404,408,480,486,487,503. -
There is a
History-Infoheader 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.
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
LegForCdrssession 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
LegForCdrssession 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.
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 |
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
Determine Service Type Feature
Description
| |
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:
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
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;
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 |
For determining release cause code if the UserReleaseCause is not set |
Use default call release cause SC_FORBIDDEN |
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 |
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.
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 |
Session state
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) |
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.
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.
PassiveParty does not accept being put on hold
The feature will simply end the announcement and allow the session to continue.
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.
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.
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, |
For selecting configuration data |
Increment InputParameterErrors |
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 |
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 |
MidcallAnnouncementId session state field is ⇐ 0 |
Increment InvalidAnnouncementIDs |
Null sessionstate SentinelSelectionKey |
Increment InputParameterErrors |
ACI not provided to the announcement feature |
Increment InputParameterErrors |
SipSession object not provided to the announcement feature in the activity context interface |
Increment InputParameterErrors |
Announcement properties not found for announcement ID |
Increment InputParameterErrors |
Announcement resource config not found for resource config ID |
Increment ConfigurationErrors |
Failed to send INVITE to Media Server |
Increment SipSendErrors |
Error received from MRF on Invite |
Send Ack with Rejection to played party |
Error received from MRF on Cancel due to played party BYE |
Increment SipErrors |
MediaServer response timeout to INVITE |
Send Ack with Rejection to played party |
MediaServer response timeout to Cancel |
Increment SipErrors |
Failed to send 200 Prack response |
Increment SipSendErrors |
Failed to send ACK to MRF |
Increment SipSendErrors |
Failed to send BYE to MRF |
Increment SipSendErrors |
Failed to send CANCEL to MRF |
|
Failed to send 183 response due to unable to access INVITE from SIPSession |
Increment InputParameterErrors |
Failed to send 183 response |
Increment SipSendErrors |
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.
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 |
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 |
MediaServerURI |
String |
The configured value for the media server URI |
RouteDirectToResource |
Boolean |
The configured value for the route direct to resource |
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 |
Configuration profile naming
| Configuration Profile Table Name | Description | Profile Naming |
|---|---|---|
SipAnnouncementProfileTable |
Announcement configuration profiles |
SentinelSelectionKey:id |
SipAnnouncementProfileTable |
Announcement configuration profiles |
SentinelSelectionKey:id:language |
SipAnnouncementResourceConfigProfileTable |
Announcement resource addresses and other resource configuration data |
SentinelSelectionKey:resourceConfigName |
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 -
Fromaddress -
Toaddress -
P-Asserted-Idaddress (if present) -
P-Served-Useraddress (if present).
| |
The SipNormalization feature will only do analysis of an address if:
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 |
| |
The Called Party The Called Party |
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, |
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 |
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.
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.
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.
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.
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, |
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 |
Poll the |
EarlyMediaAnnouncementQueue |
List<Integer> |
A list of positive integers |
A list of IDs of the subsequent announcements to be played — entries such as |
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 |
ACI not provided to the announcement feature |
Increment InputParameterErrors |
SipSession object not provided to the announcement feature in the activity context interface |
Increment InputParameterErrors |
Announcement properties not found for announcement ID |
Increment InputParameterErrors |
Announcement resource config not found for resource config ID |
Increment ConfigurationErrors |
Failed to send INVITE to Media Server |
Increment SipSendErrors |
Error received from MRF |
Increment SipErrors |
MediaServer response timeout |
Increment SipErrors |
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 |
Failed to send BYE to MRF |
Increment SipSendErrors |
Failed to send CANCEL to MRF |
|
Failed to send 183 response due to unable to access INVITE from SIPSession |
Increment InputParameterErrors |
Failed to send 183 response |
Increment SipSendErrors |
Common cleanup actions: |
|
|---|
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 |
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, |
SipAnnouncementProfileTable |
Announcement configuration profiles |
SentinelSelectionKey:id (for example, |
SipAnnouncementResourceConfigProfileTable |
Announcement resource addresses and other resource configuration data |
SentinelSelectionKey:resourceConfigName (for example, |
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 |
The SIP prefix and suffix analysis feature performs prefix and suffix digit analysis on the request-URI of the received INVITE request.
| |
The
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:
stripprefix/suffix orretainprefix/suffix, and set session parameter with configured value.
-
-
If the directive is
strip, then the request-URI is updated in the outgoingINVITE.
| |
The Subsequent features may make additional changes to the |
| Parameter | Description |
|---|---|
Address |
Prefix or suffix to match |
Description |
|
ListId |
|
ParameterName |
Session state field to set (for example, |
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 |
| |
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 |
| |
The Called Party The Called Party |
Session state inputs and outputs
Inputs
| Name | Type | Format | Description | Behaviour if null/invalid |
|---|---|---|---|---|
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
selection key (for example, |
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} |
| |
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 |
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.
| |
The SipShortCode feature will only do analysis if:
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).
| |
The Subsequent features may make additional changes to the request URI, so the final address sent in the |
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 |
| |
The Called Party The Called Party |
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, |
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, |
${PLATFORMOPERATOR}_SipShortCode_AddressListConfigurationTable |
Address list configuration |
${SELECTIONKEY}:SipShortCode:SipShortCodeAddressList |
${PLATFORMOPERATOR}_SipShortCode_AddressListEntryTable |
Feature specific Address List entry table |
${SELECTIONKEY}:SipShortCode:SipShortCodeAddressList:${ADDRESS} |
| |
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 |
Error scenarios
| Scenario | Handling |
|---|---|
Called Party leg Invite Request is null or does not contain Subscriber address |
Report featureFailedToExecute |
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 |
|
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:
-
First unlinks the legs created by SIP Third Party HTTP Trigger Feature.
-
Starts to set up the call.
-
The setup begins with A party negotiation.
-
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.
-
The call will be established if a positive answer was received from the B party.
Otherwise the call setup fails.
| |
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.
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 |
|
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 selecting configuration data |
Configuration
See under SIP Third Party Call Configuration. The only parameter used by this feature is NoAnswerApplicationTimer.
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
Session state inputs and outputs
Outputs
| Name | Type | Format | Description |
|---|---|---|---|
CallType |
com.opencloud.sentinel.common.CallType |
|
Call type of this call |
SessionType |
com.opencloud.sentinel.common.SessionType |
|
Session type of this call |
APartyLegName |
String |
|
A party leg name created by the feature |
BPartyLegName |
String |
|
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: |
Sends HTTP 200OK response with the |
Error on leg creation |
Sends HTTP 200OK response with the |
On CreditLimitReached or OCSFailure |
Sends HTTP 200OK response with the |
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);
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
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.
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, |
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 |
|
Related features |
|
Typical feature execution points |
SipThirdPartyAccess_SubscriberCheck |
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);
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 |
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 |
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.
Diameter Service Features
Sentinel includes many features for Diameter networks:
-
Accept Diameter Mediation Session Feature — Sets the Sentinel selection key session type to ‘diametermediation’
-
Diameter Determine Network Operator Feature — Sets the Network Operator element of the Sentinel selection key based on the value returned by the
DetermineNetworkOperatorfunction -
Diameter Subscriber Determination Feature — Used to determine the subscriber address based on AVPs in the
CreditControlRequest(INITIAL) -
Diameter Unconditional Reject Session Feature — Unconditionally rejects a Diameter session.
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, |
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, |
Updated selection key including session type determined from application context |
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).
which references 3gpp TS 29.061
Session state inputs and outputs
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 |
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.
| |
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 |
Initial CCR which triggered this session |
Unless subscriber was pre-determined, report featureFailedToExecute, featureHasFinished |
Error scenarios
| Scenario | Handling |
|---|---|
Session state InitialCcr is null or does not contain a SubscriptionId AVP |
Report featureFailedToExecute |
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.
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.
| |
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.
| |
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 |
Error creating Ro Activity or exception sending CCR |
Increment FailedEnquirySystemFaultCounter |
OCS times out |
Increment FailedEnquiryOcsFaultCounter |
OCS response error |
Increment FailedEnquiryOcsFaultCounter |
No configured USSDResponseMessage |
Set sessionstate MAPResponseErrorType to MAP_USSD_ERROR_SYSTEM_FAILURE |
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, |
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
Error scenarios
| Scenario | Handling |
|---|---|
Sessionstate AdditionalArgument is null |
Set sessionstate MAPResponseErrorType to MAP_USSD_ERROR_DATA_MISSING |
No USSDCallbackConfiguration |
Set sessionstate ResponseMessage to “Failed to setup call (SR)” |
HTTP Error or IOException retrieving HTTP response content |
Set sessionstate ResponseMessage to “Failed to setup call (Error)” |
HTTP response timeout |
Set sessionstate ResponseMessage to “Failed to setup call (Timeout)” |
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).
Test Features
Sentinel includes features for testing purposes:
| Feature | Description |
|---|---|
com.opencloud.sentinel.feature.common.test.TestNeverFinish |
This feature starts (calls |
com.opencloud.sentinel.feature.notification.TestSetNotificationMessage |
This feature sets the “NotificationMessage” session state field to the string “notification” |
com.opencloud.sentinel.feature.initialtrigger.TestSetAnnouncementId |
|
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” |
| |
These features are included for test purposes and may not be suitable for use in production environments. |
| |
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
Error scenarios
| Scenario | Handling |
|---|---|
Null sentinel selection key |
Report featureCannotStart |
Missing address list |
Report featureCannotStart |
Missing address list prefixes |
Report featureCannotStart |
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 |
Configuration
The Test Set Session State feature:
-
is configured through the
TestSetSessionStateConfigTableprofile 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 — The Sentinel Normalizer normalizes International, Unknown, National, or Subscriber NADI format addresses
-
Service Timer Provider — The ServiceTimerProvider API is used by features to raise feature-specific timers.
-
XPath Language Component — The Sentinel XPath component supports a subset of the XPath language, which supports Diameter messages in Sentinel.
Normalization Component
Description
Component name |
Normalizer |
|---|---|
Applicable contexts |
|
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.
| |
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.
| |
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, |
${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.
| |
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 |
|
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.
| |
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
This section covers:
| |
For an overview of what promotions are and how they work, see the Sentinel Overview and Concepts Guide. |
OCS Failure Handling Data Promotion Feature
OCS Failure Handling SMS Promotion Feature
OCS Failure Handling Time Promotion Feature
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.
Promotions Commit Used Units Feature
Description
Feature name |
PromotionsCommitUsedUnits |
|---|---|
Applicable contexts |
|
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 |
|
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 |
|
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 |
PromotionValidityStartDates |
Used by the |
PromotionValidityEndDates |
Used by the |
Each scripted promotion is configured in the PromotionsTable:
| Parameter | Description |
|---|---|
SelectionKey |
Sentinel selection key the promotion is scoped to (for example, |
PromotionName |
Promotion name (for example, |
BucketName |
Bucket name (for example, |
PromotionPriority |
Promotions selection priority |
PromotionConditionSrc |
See Promotion Selection Expressions (for example |
EncodedValidityEnd |
Used by the |
EncodedValidityStart |
Used by the |
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, |
PromotionBucketsConfigTable |
Configuration of promotion bucket properties (such as access type) |
SentinelSelectionKey:BucketName (for example, |
PromotionsConfigTable |
Configuration of promotions behaviour |
SentinelSelectionKey (for example, |
PromotionsDbQueryConfigProfileTable |
DbQuery statement configuration |
SentinelSelectionKey for example, |
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, |
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, |
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.
|
||
|
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 |
Configuration profile naming
| Configuration Profile Table Name | Description | Profile Naming |
|---|---|---|
ServiceIDConfigTable |
Selection of database implementation and rating group for the feature |
SentinelSelectionKey (for example, |
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 |
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 |
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. |
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 |
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 |
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.
Addresses in an address list are sequences of: 0 … 9, a … f, A … F, #, *, .
| |
You provision address lists using the Sentinel Element Manager. See the Sentinel Administration Guide for details. |
| |
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)
| |
An address list is identified by two properties:
|
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> |
| |
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.
| |
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:
-
create this file
-
add the property definitions you want to customize.
You can also configure Sentinel EM to provision data in an external database.
Provisioning configuration options
You can configure these Sentinel provisioning options:
sentinel.<featurename>.default-page-size
Description |
The default page size used when listing entries in this resource collection. |
|---|---|
Java type |
int |
Default value |
10 |
Example |
|
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.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.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.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.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.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.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 |
|
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.
|
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.
|
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.
|
4 |
Click the Edit button. |
5 |
Fill in all the fields with the Cassandra connection information, and click Save.
|
Provisioning Data in TimesTen
Configuring JDBC provisioning lookup types and connections
Below are instructions for configuring JDBC provisioning lookup types and the connection to the TimesTen database.
Configuring JDBC provisioning lookup types
Sentinel comes with three JDBC-based provisioning service implementations: for subscriber data, promotion buckets, and home zones.
Subscriber data
To use the JDBC-based provisioning service implementation for subscriber data, in the provisioning GUI:
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.
|
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.
|
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.
|
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 |
3 |
Edit (or create) # 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 <!-- ... -->
<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) <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
| |
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.
|
For help using each of the Sentinel management panels, see:
| |
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.
Click image to enlarge The diagram for that session plan displays.
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.
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).
Click image to enlarge
|
||||
4 |
To set or change the script associated with a particular point and selection key:
|
||||
5 |
To remove a script association:
|
Managing Cassandra
| |
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:
Click image to enlarge
| |
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.
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.
Click image to enlarge
|
||||
3 |
To add a new script:
Click image to enlarge
|
||||
4 |
|
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.
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).
Click image to enlarge |
3 |
To edit a subscriber data record:
|
4 |
To add a new subscriber data record:
|
5 |
To delete the selected subscriber data record:
|
Using the Machine API
Use RESTful HTTP
The machine-provisioning API is available through RESTful HTTP.
| |
For a link to the API, select Sentinel ⇒ Machine API. |
| |
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.
Click image to enlarge Tabs display for the configuration types available for that feature.
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.
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.
Click image to enlarge To view or edit the details of an existing entry:
|
||
4 |
To add a new entry:
|
||
5 |
To delete a selection:
|
Managing Mappers
Configuring mappings
You can use this management page to view, add, and delete mappers and mapping sets.
| To… | Do this: | ||
|---|---|---|---|
View mappings |
Click image to enlarge |
||
Add a mapping |
|
||
Delete mappings |
|
||
Add a mapper set |
|
||
Delete a mapper set |
|
||
Publish a mapper set |
|
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.
Click image to enlarge |
|---|---|
2 |
To add a plan, session type, or subscription for the selected operator:
|
3 |
To delete the selected plan, session type, or subscription:
|
Managing Normalization
Scoping and configuring normalization
You can use this management page to add, edit, or delete normalization data.
1 |
Click image to enlarge If no normalization configuration exists at the selected level, an Add New button displays.
Click image to enlarge (Otherwise, the existing normalization configuration displays.) |
|---|---|
2 |
To add normalization data:
Click image to enlarge
|
3 |
To edit normalization data:
|
4 |
To delete normalization data:
|
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.
Click image to enlarge
Adding, editing, and deleting a promotion configuration
To manage promotion configurations:
1 |
|
|---|---|
2 |
To add a promotion configuration:
|
3 |
To edit a promotion configuration:
|
4 |
To delete a promotion configuration:
|
Editing, adding, and deleting promotion bucket configurations
To manage promotion bucket configurations:
1 |
|
|---|---|
2 |
To edit a promotion bucket configuration:
|
3 |
To add a new promotion bucket configuration:
|
4 |
To delete the selected promotion bucket configurations:
|
Editing, adding, and deleting SQL configurations
To manage SQL configurations for promotions:
1 |
|
|---|---|
2 |
To add an SQL configuration:
|
3 |
To edit an SQL configuration:
|
4 |
To delete the selected SQL configuration:
|
Editing, adding, and deleting promotion tables
To manage promotion tables:
1 |
|
|---|---|
2 |
To add a promotion table:
|
3 |
To edit a promotion table:
|
4 |
To delete a promotion table:
|
Loading, editing, adding, and deleting promotion buckets
To manage promotion buckets:
1 |
|
|---|---|
2 |
To load a promotion bucket:
|
3 |
To edit the loaded promotion bucket:
|
4 |
To delete the loaded promotion bucket:
|
5 |
To add a new promotion bucket:
|
Managing Correlation Resource Adaptor Entities
Configuring Correlation Resource Adaptor Entities
| |
For general information on the Correlation RA and its use in Sentinel, please see Correlation Resource Adaptor. |
To configure correlation resource adaptor entities:
1 |
|
||||||||
|---|---|---|---|---|---|---|---|---|---|
2 |
|
||||||||
3 |
|
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 |
|
Add a new XCAP host mapping |
|
Delete the selected XCAP host mapping. |
|
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 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 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 cd $RHINO_HOME unzip rhino-element-manager.zip -d $RHINO_HOME cd rhino-element-manager* export REM_HOME=`pwd` |
|---|---|
2 |
Copy |
3 |
Run cd $REM_HOME/admin ./install-extensions.sh |
4 |
Unzip |
5 |
Edit 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 |
7 |
Remove install files: (optional) cd $RHINO_HOME rm -rf rhino-element-manager* |
8 |
Import a Rhino Trust Certificate into REM: |
9 |
Start Tomcat: cd $TOMCAT_HOME ./bin/catalina.sh run |
| |
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) |
|---|---|
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:
|
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.
| |
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.
|
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
|
|
|
| |
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 — describes the formats used for CDRs
-
Working with CDRs — describes tooling to extract the content of CDRs
-
Ro Interface AVPs — describes the population of AVPs on the Ro interface
-
Charging Content AVPs — describes the populated AVPs for both online and offline charging
-
Interim CDRs — describes Interim CDRs for offline charging
-
Sizing AVP CDRs — describes sizing requirements when using AVP CDRs
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 — describes the formats used for AVP CDRs
-
Legacy CDR Format — describes the format used for Legacy CDRs
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-Resultvalue of-1means that online charging was not used for the session. -
Otherwise the value is set to the Diameter
Result-CodeAVP 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 |
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 |
Node-Functionality |
32.299 v12.11.0 section 7.2.113 |
Yes |
Yes |
Yes |
Set to value |
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 |
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 |
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 |
Yes |
No |
Yes |
n/a |
|
OC-Play-Announcement-Id |
Yes |
No |
Yes |
n/a |
|
OC-Call-Type |
Yes |
No |
Yes |
Role-Of-Node AVP has similar meaning on the Ro interface |
|
OC-Service-Type |
Yes |
No |
Yes |
n/a |
|
OC-Charging-Result |
Yes |
No |
Yes |
||
OC-OCS-Session-Id |
Yes |
No |
Yes |
This is the session ID in Ro |
|
OC-OCS-Session-Termination-Cause |
Yes |
No |
Yes |
||
OC-Sentinel-Error |
Yes |
No |
Yes |
||
OC-Charging-Instance |
Yes |
No |
Yes |
||
OC-Event-Id |
Yes |
No |
Yes |
||
OC-Call-Id |
Yes |
No |
Yes |
The Ro Session Id optional part includes the SIP Call ID |
|
OC-End-Session-Cause |
Yes |
No |
Yes |
||
OC-Start-Time |
Yes |
No |
Yes |
||
OC-End-Time |
Yes |
No |
Yes |
||
OC-Session-Start-Time |
Yes |
No |
Yes |
||
OC-Session-Established-Time |
Yes |
No |
Yes |
Included if an INVITE session is answered |
|
OC-Session-End-Time |
Yes |
No |
Yes |
||
OC-Session-Counter |
Yes |
No |
Yes |
||
OC-Interim-CDR-Trigger |
Yes |
No |
Yes |
||
OC-AGE-OF-INFORMATION |
Yes |
Yes |
Yes |
||
OC-MCC-MNC |
Yes |
Yes |
Yes |
||
OC-ACCESS-NETWORK-MCC-MNC |
Yes |
Yes |
Yes |
||
OC-VISITED-NETWORK-MCC-MNC |
Yes |
Yes |
Yes |
||
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-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:
-
Improved failure characteristics. Interim CDRs are recording more frequently during a session, so any system failures will result in less records being lost.
-
Interop with offline charging systems. This format is designed to reflect the message content requirements for interaction with offline charging systems via the Rf interface.
-
More accurate. This format records changes in specific AVPs (e.g. SIP SDP AVPs) during the lifecycle of a session allowing changes in media state to be more accurately tracked.
Interim CDR content
Interim CDRs are written as a collection of AVPs conforming to the definitions listed in Sentinel AVP definitions. In addition to the standard AVPs, Interim CDRs contain additional AVPs to facilitate interpretation and correlation of their content.
These additions are summarized in the following table:
| 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. |
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 |
|---|---|
Determines which leg to charge then records it to the |
|
Detects when SDPs have changed and sets the |
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.
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 |
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 |
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 |
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 |
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 |
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 |
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
| |
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 — describes how to install the List CDRs tool
-
Obtaining CDRs — describes how to obtain CDRs used as input to the List CDRs tool
-
Running List CDRs — describes how to run the List CDRs tool
-
Extension AVPs — describes how to configure extension AVPs in the List CDRs tool
-
Installing Protobuf — describes how to install Protobuf
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
| |
See Setting up Ant in the Sentinel Express SDK guide. |
Installing List CDRs Standalone
The above two approaches are automated ways of installing the List CDRs package (sentinel-list-cdrs-package.zip) into a particular location: sentinel-express-sdk/tools/list-cdrs/.
Both the above methods place a List CDRs installer archive at sentinel-express-sdk/tools/target/sentinel-list-cdrs-package.zip.
This sentinel-list-cdrs-package.zip archive can be moved to and unzipped into another location outside of the SDK and used as a standalone tool.
To install the List CDRs package as a standalone tool, simply unzip the sentinel-list-cdrs-package.zip archive to your chosen destination directory.
The mechanisms for invoking and configuration the List CDRs tools are the same as when running the tool inside the SDK. Simply substitute /home/testuser/sentinel-express-sdk/tools/list-cdrs with /your/chosen/directory/list-cdrs.
Uninstalling List CDRs
If you want to uninstall the List CDRs tool, use the uninstall-list-cdrs Ant target under the sentinel-express-sdk/tools directory:
$ 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).
| |
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.
| |
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.
| |
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.
1if set,0if not set. Indicates whether support of the AVP is mandatory on the receiving end. - ProtectedRule
-
The "P" bit, indicating the need for encryption.
1if set,0if 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.
| |
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
| |
See Setting up Ant in the Sentinel Express SDK guide. |
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/