# Sentinel Administration Guide

Sentinel Express - Version 2.9.0

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 Express Provisioning Module has instructions for installing the Rhino Element manager plugin

## Getting Started

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

In this section…​

- Preparing to Install Sentinel Express— prerequisites needed to install Sentinel Express services into Rhino

- Installing Sentinel Express Services— how to install the Sentinel Express services into Rhino

- Installing the Sentinel Express Provisioning Module— how to (optionally) install the Sentinel Express Provisioning module into the Rhino Element Manager

## Preparing to Install Sentinel Express

| Artifactory This page refers to a public Artifactory instance that is no longer available. Please contact us via support if you require more information.

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.9.0/opencloud/sentinel-pack/2.9.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 (7.0.x series or 8.5.x series, not 9.x.x series) | http://tomcat.apache.org |
Rhino 2.6.1.0 or later - optional - to be used when installing and configuring Rhino manually | Rhino 2.6.1 SDK from Artifactory | Rhino Documentation
Rhino Element Manager 2.6.1.0 or later | REM Download Page | REM Documentation
Sentinel Express SDK including out of the box installer | Sentinel Express SDK, from Artifactory | Sentinel Express SDK
(Optional) Cassandra Database, version 2.1.17 or later version from the 2.1.x series | http://cassandra.apache.org/download/ | http://wiki.apache.org/cassandra/GettingStarted

### Install and configure Rhino and the JVM

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

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

#### Install Rhino

1 | Start by choosing a location to extract the contents of the Rhino package. We’ll refer to this directory as `RHINO_HOME`.
2 | Rhino must be started at least once to generate the necessary configuration files. To start Rhino, in the `RHINO_HOME` directory, execute:
    $ ./start-rhino.sh
(or `start-rhino.bat` on Microsoft Windows).
3 | Wait until Rhino is ready. It prints the following message in its log when ready:
    SLEE successfully started on node(s) [101]
4 | Stop Rhino by executing in the `RHINO_HOME` directory:
    $ ./stop-rhino.sh --nice

| For more about installing and configuring the Rhino TAS, please see the Rhino v2.6.1 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.6.1 management database size is insufficient and should be increased to at least 300MB. To do this, edit `RHINO_HOME/config/rhino-config.xml` on all nodes, increasing the `<committed-size>` in the following section:
        <memdb>
          <jndi-name>ManagementDatabase</jndi-name>
          <message-id>10003</message-id>
          <group-name>rhino-db</group-name>
          <committed-size>300M</committed-size>
          <stripe-count>1</stripe-count>
          ...
        </memdb>
JVM | You’ll also need to configure the JVM: The Rhino `HEAP_SIZE` setting should be set to 2048m at a minimum. The recommended `MAX_NEW_SIZE` and `NEW_SIZE` setting for a Rhino node running Sentinel Express is 1/4th of the total heap size (for example, 512m when the `HEAP_SIZE` is 2048m). The `MaxPermGen` size should be increased from its default, to at least 384MB. To do this in Rhino 2.4, modify the flags `-XX:MaxPermSize=` and `-XX:PermSize=` in `RHINO_HOME/config/jvm_args`. All of these settings can be found in `RHINO_HOME/config/config_variables` after running Rhino for the first time.
Socket permissions | You will need to add the host address where the installer is running to the mlet configuration file. For RhinoSDK the configuration file is `RHINO_HOME/config/mlet.conf` For Rhino Production the configuration file is `RHINO_HOME/node-xxx/config/permachine-mlet.conf` In the configuration file look for the XML tag `<security-permission-spec>` and add the following entry, replacing <IP ADDRESS> with your installer’s IP address:
    <mlets>
        <mlet enabled="true">
            <classpath>
                <jar-url>$${rhino.dir.base.url}/lib/jmxr-adaptor.jar</jar-url>
                <security-permission-spec>
                    .... other entries

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

                    .... other entries
                </security-permission-spec>
            </classpath>
        </mlet>
    </mlets>

| Start Rhino to load the new configuration To start Rhino, in the `RHINO_HOME` directory run `start-rhino.sh` (or `start-rhino.bat` on Microsoft Windows). This applies the Rhino and JVM configuration.

### Get a license

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

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

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

To install your license file:

1 | Make sure Rhino is started and running.
2 | Go to the `RHINO_HOME/client/bin` directory.
3 | In this directory, start the Rhino Console with the `rhino-console` script (or `rhino-console.bat` in Microsoft Windows).
4 | In the Rhino Console execute, this command:
    installlicense [PATH_TO_LICENSE_FILE]
(`[PATH_TO_LICENSE_FILE]` should be relative to the `RHINO_HOME/client/bin` directory.)

### Ports

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

Port | Purpose
--- | ---
5060 | SIP traffic
5061 | Secure SIP traffic
8080 | REM GUI
1199-1203 | RMI Access

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

### OpenCloud product dependencies

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

Product | Series
--- | ---
Rhino | 2.6.1.x
REM | 2.6.1.x
SIP | 2.6.0.x
CGIN | 2.0.0.x
SIS | 2.6.1.x
SIS-EM | 2.6.1.x
Diameter | 3.1.1.x
CDR-RA | 2.3.0.x
HTTP-RA | 2.4.0.x
DB-Query-RA | 1.4.0.x
FSM Tool | 1.2.0.x
CQL-RA | 1.1.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:

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

2. Run the installer

For further information on installation read:

- SIS and CGIN

- Background information for the installer

- The Sentinel Installer

### 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.
| It’s easiest if you create a new directory in the home directory.
    user@machine$ mkdir ~/sentinel-express
2 | Unzip.
    user@machine$ cp ~/sentinel-express-sdk.zip ~/sentinel-express
    user@machine$ cd ~/sentinel-express
    user@machine$ unzip sentinel-express-sdk.zip

### 2. Run the installer

The install program is split into several "phases".

These are:

- initialisation of the environment

- question and answer (in interactive mode)

- execution of installation

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

To run the installer:

1 | The `installer` command is in the `build/bin` directory of the extracted Sentinel Express SDK .
    testuser@machine$ cd ~/sentinel-express/sentinel-express-sdk
    testuser@machine$ ./build/bin/installer
The installer first initialises the environment. It typically shows output similar to the following
    Initialising the SDK ...
    Retrieving Installer dependencies ... done.
2 | Question and answer to determine necessary settings The installer will prompt the user for various values. A value inside square brackets, if present, is the default answer for that question. When the user presses the `Enter` key without entering any value the default is used if it is present. If the default isn’t present, the prompt will be repeated. In subsequent runs of the installer, the default will reflect the values that the user has previously entered. Explanations of all of the questions the installer will ask are laid out over the next few steps. Note that some of the questions will only appear under certain circumstances, so not all of them will be seen in a given installer run.
3 | Taking the SDK offline The user is prompted as to whether or not they want to take the SDK offline.
    You can optionally take the SDK offline by creating a local repository. This will take several minutes depending on connection speed, but will make subsequent retrievals much faster and remove the need for an internet connection.
    Do you want to take the SDK offline? y/[N] >
If the user presses the `Enter` key then the default of `N` is applied by the installer. This means that the SDK remains online, and will connect to the OpenCloud repositories on an as-needs basis. Answering yes will create a local Ivy repository that includes all of the remote artifacts required to build the SDK. The user is then presented with progress information related to the downloading of artifacts necessary to take the SDK offline. This process can take more than 30 minutes.
4 | Basic SDK Questions
    Your organization's name, e.g. Rocket Communications Inc.
    sdk.component.vendor [UNSET] >
This value will be used for the `vendor` portion of the SLEE Component ID for all SLEE components published by the SDK.
    sdk.component.version [1.0] >
This value will be used for the `version` portion of the SLEE Component ID for all SLEE components published by the SDK.
    The name of the platform operator, e.g. Rocket.
    sdk.platform.operator.name [UNSET] >
The name of the platform operator for the system. It is used extensively throughout configuration profiles.
    An Ivy organization field, recommended lower case with no whitespace e.g. "rocket".
    sdk.ivy.org [UNSET] >
This value is used as the `org` value for all Ivy artifacts created by the SDK.
    sdk.ivy.publish.revision [1.0.0] >
This value is used as the base of the `revision` value for all Ivy artifacts created by the SDK. When an artifact is actually published, additional letters and numbers will be appended to this number to identify specific releases, snapshots and milestones.
5 | Install Rhino Questions
    You can either have the installer set up a Rhino SDK for you or point it at an existing Rhino installation, SDK or production.
    Note: If you want to use an existing Rhino installation it has to be running and a proper license has to be installed when finishing the installation after the configuration. Also make sure that you have adjusted the memory settings and created a tcapsim-gt-table.txt file as detailed in the documentation.
    Set up a Rhino SDK installation automatically? y/[N] >
If you allow the installer to set up a new Rhino SDK installation, it will prompt for a license file.
    Enter the path to your Rhino license file > /home/testuser/Downloads/opencloud.license
It then installs the Rhino SDK and starts it. If you instruct the installer to use an existing Rhino, the installer will prompt for the path to the Rhino client directory.
    Enter the path to your Rhino client directory > /home/testuser/rhino/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
6 | Review settings Once all questions have been answered, the user is provided the opportunity to review and if happy, accept the settings. TIP: settings are saved to disk, so that they can be read later.
    Review settings
    ***************

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

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

    ... edited for brevity

    Accept these values? [Y]/n > y

    Updating file {sdk-path}/sdk.properties

    Configuration changes written.
If the user presses the `n` key then the questions are asked again. Note that the list of configuration files that have been modified are printed out by the configuration portion.
7 | Which product(s) to deploy The user can choose which Sentinel products to deploy as part of the installation, any combination of Sentinel SIP, Sentinel SS7 and Sentinel Diameter can be specified.
    This installer can be used to create deployment modules for one or more of the following Sentinel products: "diameter", "sip" and "ss7". Please enter the products you would like to deploy as a comma-separated list.
    Which products do you want to deploy? [sip,ss7,diameter] >
For each option the user specifies, a deployment module will be created to deploy the specified product.
8 | Sentinel SS7 with SIS If Sentinel SS7 was one of the products selected for deployment, the user will be presented with an option to install Sentinel SS7 with SIS.
    Do you want to install sentinel-ss7 with SIS? y/[N] >
If the user enters `y` then Sentinel Express will install and configure SIS for use with the Sentinel SS7 service.
9 | Creation of a deployment module The installer will now create the required deployment module(s). This may take several minutes.
10 | Execution phase Now that the installer has gathered all necessary information it provides the user with the option to install Sentinel Express immediately.
    Install now? [Y]/n >
If the user wants to install at a later time, they can press the `n` key. The installer exits having saved settings that the user has entered. I.e. the installer can be run later if desired.
    Installing Rhino ... done.
    Starting Rhino in the background ... done.
    Publishing deployment module deploy-sentinel-diameter ... done.
    Publishing deployment module deploy-sentinel-sip ... done.
    Publishing deployment module deploy-sentinel-ss7 ... done.

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

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

| 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 `installer.log` is created in this directory. If there is a previous `installer.log` file, it is moved to `installer_[date].log`. The value of `[date]` is the time of the last write timestamp in the file.

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

## Installing the Sentinel Express Provisioning Module

| Artifactory This page refers to a public Artifactory instance that is no longer available. Please contact us via support if you require more information.

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

It requires REM 2.6.1 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

  - download from https://repo.opencloud.com/artifactory/opencloud-sentinel-express-2.9.0/opencloud/rem/2.6.2/rem-package/

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

  - download for your release version from https://repo.opencloud.com/artifactory/opencloud-sentinel-express-2.9.0/opencloud/sentinel-pack/2.9.0/sentinel-express-element-manager

- (optional) the SIS REM plugin —`sis-em-<version>.em.jar`

  - download for your release version from https://repo.opencloud.com/artifactory/opencloud-sentinel-express-2.9.0/opencloud/sis-em/2.6.1/sis-em

Below are the procedures to:

- set up Tomcat

- install the REM plugin

- customize plugin logging

- import Rhino trust certificate

- run it securely

| REM restart required After installing and configuring the plugin, you will need to restart REM, for example by restarting the Tomcat webapp it is running in:
    ${CATALINA_BASE}/bin/catalina.sh stop
    ${CATALINA_BASE}/bin/catalina.sh start

### Set up Tomcat

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

1 | Follow the instructions for running REM on Apache Tomcat in the REM Guide.
2 | Create the `rem_home/plugins` directory.
    cd apache-tomcat-<version>
    mkdir -p rem_home/plugins

### Install the REM plugin

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

1 | Copy `sentinel-express-element-manager-<version>.em.jar` into `rem_home/plugins`.
    cd apache-tomcat-<version>
    cp /full/path/to/sentinel-express-element-manager-<version>.em.jar rem_home/plugins/
2 | (Optional) Copy `sis-em-<version>.em.jar` into `rem_home/plugins`.
    cd apache-tomcat-<version>
    cp /full/path/to/sis-em-<version>.em.jar rem_home/plugins/

### Customize plugin logging

1 | Unzip `log4j2.properties` from `rem.war`:
    cd apache-tomcat-<version>
    mkdir rem-tmp
    cd rem-tmp
    unzip ../webapps/rem.war WEB-INF/classes/log4j2.properties
2 | Edit `WEB-INF/classes/log4j2.properties` with this content:
    rootLogger.level=INFO
    rootLogger.appenderRef.console.ref=CONSOLE
    rootLogger.appenderRef.file.ref=FILE

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

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

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

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

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

    appender.AUDIT.type = RollingFile
    appender.AUDIT.name = AUDIT
    appender.AUDIT.fileName = ${rem.home}/sentinel-audit.log
    appender.AUDIT.layout.type = PatternLayout
    appender.AUDIT.layout.pattern = "%d{yyyy-MM-dd HH:mm:ss,SSS}", "%c{1}", %m%n
3 | Replace `WEB-INF/classes/log4j2.properties` in `rem.war`:
    zip ../webapps/rem.war WEB-INF/classes/log4j2.properties
4 | Remove temporary files:
    cd ..
    rm -rf rem-tmp

### Import Rhino trust certificate

This can also be done using the REM web UI.

1 | Import a Rhino Trust Certificate into REM:
    "${JAVA_HOME}/bin/keytool" -importcert -file ${RHINO_HOME}/rhino-trust.cert -keystore "${TOMCAT_HOME}/rem_home/rhino-ems.ks" -storepass changeit -noprompt

### Security considerations

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

#### Use https

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.

| All service configuration can be managed using the Sentinel Element Manager web-based interface or the Sentinel Sentinel Provisioning REST API.

## Sentinel Common Configuration

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

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

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

## Core Configuration

### Description

Configuration name | Sentinel Core Configuration
Applicable contexts | All

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

### Configuration

The Sentinel Core Configuration includes:

Parameters | Description
--- | ---
PlatformOperator | The platform operator for this Sentinel installation
DefaultNetworkOperator | The default network operator for this Sentinel installation
NetworkOperators | The list of network operators that may be used in the configuration
HttpParameterForHttpDetermineNetworkOperator | The HTTP parameter that is used the HTTP Determine Network Operator feature
DefaultOcsEntityID | The default OCS entity ID
MaximumCallDuration | The maximum permitted call duration. If set to 0 the call duration is unlimited. Must be a whole multiple of the reservation time as set in the `OcsParameterConfiguration` feature `RequestUnitsSeconds`. It is recommended that the multiple is 2 or greater. Maximum call duration is intended to prevent excess call durations and is not intended as a way to limit normal calls
FeatureTimeOut | The feature timeout in milliseconds. May be configured between -1 and 1800000. -1 turns off feature timers. Feature timeout under 1 sec (1000) is not recommended

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SentinelConfigurationTable | Core configuration | Fixed name

### Provisioning interfaces

The configuration is provisioned using the Sentinel Sentinel Core REST API or web interface.

## Mediation Layer Configuration

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

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

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

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

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

## Diameter Mediation Configuration

### Description

Configuration name | Diameter Mediation
Applicable contexts | SS7/SIP/Diameter service

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

### Configuration

The DiameterMediation configuration includes:

Parameters | Description
--- | ---
CloseSessionOnErrorBehaviour | String value, either ERRORS_END_SESSION or CCR_T_ENDS_SESSION. Determines if the Diameter Mediation layer ends sessions to the OCS after receiving an update CreditControlAnswer (CCA-U) with an error code in the Result-Code AVP on command level, or leaves sessions open to be terminated explicitly via a termination CreditControlRequest (CCR-T)
VtTimerEnabled | Boolean value Determines if the Diameter Mediation layer performs charging refresh based on the Validity-Time
VTTimerOffset | Integer value Offset value used to compute Validity-Time timer expiry. timeInMs = (VT + offset) * 1000

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

| The Tcc Timer and Validity-Time timers are armed redundantly if the session is replicated.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
DiameterMediationConfigurationTable | Diameter Mediation configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API.

## OCS Configuration

### Description

Configuration name | OCS Configuration
Applicable contexts | SS7/SIP/Diameter service

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

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

### Configuration

The OCS configuration includes:

Parameters | Value | Description
--- | --- | ---
DestinationRealm | String | The value to be used in the Destination-Realm-AVP for outgoing Credit-Control-Requests.
DestinationHost | String | The value to be used in the Destination-Host-AVP for outgoing Credit-Control-Requests.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
DiameterMediationOcsConfigurationTable | OCS default configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API.

## OCS Destination Configuration

### Description

Configuration name | OCS Destination Configuration
Applicable contexts | SS7/SIP/Diameter service

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

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

### Configuration

The OCS Destination configuration includes:

Parameters | Value | Description
--- | --- | ---
OcsId | String | The ID of this OCS Destination configuration. If the OcsId session state field is set and matches this field, then this OCS Destination configuration will be used when establishing the connection to the OCS.
DestinationRealm | String | The value to be used in the Destination-Realm-AVP for outgoing Credit-Control-Requests to this OCS.
DestinationHost | String | The value to be used in the Destination-Host-AVP for outgoing Credit-Control-Requests to this OCS.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
DiameterMediationOCSDestinationTable | OCS Destination configuration | SentinelSelectionKey:OcsId (for example, `OpenCloud:::::Ocs1`)

### Diameter RA configuration profile

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

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API.

## TccTimer Configuration

### Description

Configuration name | Tcc Timer
Applicable contexts | SS7/SIP/Diameter service

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

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

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

  Duration = (GsuScaleFactorMultiplier * GSU)/GsuScaleFactorDivisor + GsuOffset

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

  Duration = (VtScaleFactorMultiplier * VT)/VtScaleFactorDivisor + VtOffset

- switched off completely

- set to a constant value.

### Configuration

The TccTimer configuration includes:

Parameters | Value | Description
--- | --- | ---
DefaultTccTimeout | Long | The timer duration if USE_DEFAULT_TIMEOUT is set
TccOption | String | one of NO_TCC, USE_DEFAULT_TIMEOUT, USE_VT, USE_GSU. Determines what option shall be used to calculate the Tcc timer duration.
GsuScaleFactorMultiplier | Integer | Used when tccOption is set to USE_GSU.
GsuScaleFactorDivisor | Integer | Used when tccOption is set to USE_GSU.
GsuOffset | Integer | Used when tccOption is set to USE_GSU.
VtScaleFactorMultiplier | Integer | Used when tccOption is set to USE_VT.
VtScaleFactorDivisor | Integer | Used when tccOption is set to USE_VT.
VtOffset | Integer | Used when tccOption is set to USE_VT.
TccMinValue | Long | The outcome of any of the Tcc calculation options above is capped at this value; in other words, the Tcc timer duration cannot fall below this threshold value.

| The Tcc Timer is armed redundantly if the session is replicated.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
TccTimerConfigurationTable | TccTimer configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API.

## Configuration Common to SS7 and SIP Services

Configuration common to the SS7 and SIP services.

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

## Activity Test Configuration

### Description

Configuration name | Activity Test
Applicable contexts | SS7 service, SIP service

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

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

### Configuration

The Activity Test configuration includes:

Parameters | Value | Description
--- | --- | ---
TimerModeType | String | Either ‘chargingPeriodMultiple’ or ‘fixedDuration’.
ChargingPeriodMultiple | Decimal | If the Timer Mode Type is set to ‘chargingPeriodMultiple’ and the call is chargeable, this value specifies a multiple of the charging period duration to use as the timer duration.
FixedDuration | Integer | If the Timer Mode Type is set to ‘fixedDuration’, or the call is not chargeable, this value specifies a fixed timer duration in seconds.
ActivityTestInvokeTimeout | Integer | Specifying the period of time to wait, in milliseconds, for a successful response to an Activity Test. If a successful response is not received within this time period, the Activity Test is regarded as failed.
RandomPeriod | Long | Specifying the basis for an additional random period that will be added to the calculated duration. The concrete period added will be in the range of [0..RandomPeriod]

### Configuration Profile Naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
ActivityTestConfigurationTable | Service configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

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

## Sentinel for Diameter

### Description

Configuration name | Diameter Sentinel
Applicable contexts | Diameter service

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

### Configuration

The DiameterSentinel configuration includes:

Parameters | Value | Description
--- | --- | ---
CreditFinalisationWaitingTime | Long | Number of milliseconds Sentinel will wait for receipt of a CCR-T after having received an ASA. If the CCR-T is not received within this timeframe Sentinel will send a synthesized CCR-T to the OCS to finalise the OCS-session and will simply terminate the client-session
SuppressAbortSessionRequest | Boolean | When false, the Diameter service sends received Abort-Session-Request messages on to the Diameter CTF client peer; when true, the Diameter service responds immediately with an ASA, without sending the Abort-Session-Request to the CTF peer, closing the CTF session, and sending a final CCR-T with zero used service units.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
DiameterSentinelConfigurationTable | Service configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API.

## Sentinel for SIP

| 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: `HssCache` or `Cassandra`.
WriteAuditCdr | If audit CDRs should be written
AuditCdrPrivateIdFilter | A private-id for which an audit CDR should be written. This setting over-rides 'WriteAuditCdr'. Values of null or "" are ignored.
CdrStreamName | The cdr stream where audit CDRs are written

### Provisioning interfaces

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

## SDP Comparison for Rating Condition Change Determination

### Description

Configuration name | SDP Media Codec Profile Table
Applicable contexts | SIP service

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

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

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

### Configuration

The Sentinel SIP configuration includes:

Parameters | Description
--- | ---
EncodingName | the encoding name; typically represented in an rtpmap attribute (for example, G723)
EquivalenceClass | the equivalance class to which this codec belongs (for example, Audio8KHzSingleChannel)
Channels | the number of channels for the media attribute encoding (for example, 1)
ClockRate | the clock rate for the media attribute encoding (for example, 8000)

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SDPMediaCodecProfileTable | SDP Media Codec equivalance class configuration | SentinelSelectionKey + EncodingName/ClockRate/Channels (for example, `OpenCloud::::G723/8000/1`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API — see SIP Service Configuration REST API.

## SIP Sentinel Configuration

### Description

Configuration name | Sip Sentinel Configuration
Applicable contexts | SIP service

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

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

### Configuration

The Sentinel SIP configuration includes:

Parameters | Description
--- | ---
HomeCountryCodeIDs | Indicates the home country codes for a network or platform operator as defined by the Sentinel selection key.
HomeNetworkIDs | Indicates the home network IDs for a network or platform operator as defined by the Sentinel selection key.
MaxEventDeliveryCycles | Indicates maxinum number of event delivery cycles. Used to prevent infinite loops of local events and abort session when it is exceeded.
IcscfUri | Indicates the SIP URI of the I-CSCF. Used when the AS needs to communicate directly with the I-CSCF.
ISOCode | Indicates the ISO country code for a network or platform operator as defined by the Sentinel selection key.
MCC | Indicates the Mobile Country Code for a network or platform operator as defined by the Sentinel selection key.
MNCs | Indicates the Mobile Network Codes list with same Mobile Country Code.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SipSentinelConfigurationTable | Service configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API — see SIP Service Configuration REST API.

## SIP Session Control Configuration

### Description

Configuration name | SIP Session Control
Applicable contexts | SIP service

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

### Configuration

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

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

The SIP session control configuration includes:

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

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SipSessionControlMethodTable | Service configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API — see SIP Session Control REST API.

## SIP Third Party Call Configuration

### Description

Configuration name | Sip Third Party Call Configuration
Applicable contexts | SIP service

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

### Configuration

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

The SIP Third Party Call configuration includes:

Parameters | Value | Description
--- | --- | ---
ExpiresHeader | Integer | to use for the Expires header.
MaxForwardsHeader | Integer | to use for the MaxForwards header.
RouteHeaderURI | String | contains the URI to use for the Route header.
| This configuration value can be overridden in `SentinelSipSessionState` to allow features to perform their own destination determination. e.g. for load balancing.
SupportedHeader | String | to use for the Supported header.
UserAgentHeader | String | to use for the User Agent header.
TransportAsEnum |  | The Transport type to use. This may currently be ‘udp’ or ‘tcp’.
IsSipURIUsed | Boolean | A value determining whether the SIP URI configuration value is used.
SipURIDomain | String | A value containing the SIP URI, if used. (See IsSipURIUsed boolean above).
NoAnswerApplicationTimer | Integer | A value determining how long before the ‘no answer’ timer will fire.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SipThirdPartyCallConfigurationTable | Service configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API — see SIP Third Party Call REST API.

## Sentinel for SS7

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

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

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

- Handling GSM Call Forwarding Active on MTC

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

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

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

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

## Activity Test Configuration for SS7

### Description

Configuration name | Activity Test
Applicable contexts | SS7 service

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

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

| 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 `SuppressTerminatingPartyCallInformationReport` is also true.
CallAlertingTimePrereservationSeconds |  | The number of seconds of credit to pre-reserve in the initial credit reservation if call alerting time is chargeable. This value should be set to the maximum expected alerting time. This option is only relevant if `CallAlertingTimeIsChargeable` is set to true.
CirTimeout |  | The number of milliseconds to wait for CIRp before timeout and continuing the session. May be set between range 500 - 10000, with a default of 3000.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
CallInformationReportConfigurationTable | Service configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API — see Call Information Report REST API.

## Handling GSM Call Forwarding Active on MTC

### Identifying GSM call forwarding active

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

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

### Handling GSM call forwarding active

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

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

### References

NOLDUS | CAMEL INTELLIGENT NETWORKS FOR THE GSM, GPRS AND UMTS NETWORK | Rogier Noldus | 2006 | John Wiley & Sons, Ltd

## Relay Dialog Configuration

### Description

Configuration name | Relay Dialog Configuration
Applicable contexts | SS7 service

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

### Configuration

The Relay Dialog Configuration includes:

Parameters | Description
--- | ---
RelayDestinationSccpAddress | The destination SCCP address string of the external network element for relayed dialogs

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
RelayDialogConfigurationTable | Service configuration | SentinelSelectionKey (for example, OpenCloud::::)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API — see SS7 Relay Dialog ConfigurationProfile REST API.

## SS7 Call Configuration

### Description

Configuration name | SS7 Call Configuration
Applicable contexts | SS7 service

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

### Configuration

The SS7 Call Configuration includes:

Parameters | Description
--- | ---
NoAnswerApplicationTimer | time (seconds) to use for the No Answer application timer when requesting event reports from the MSC
ThirdPartyCallSetupGmscAddress | SCCP address string of the GMSC used when setting up third party calls.
ThirdPartyCallSetupScfAddress | (optional) SCCP address string of the SCF used when setting up third party calls.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SS7CallConfigurationTable | Service configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API — see SS7 Call Configuration REST API.

## SS7 Diameter Configuration

### Description

Configuration name | SS7 Diameter Configuration
Applicable contexts | SS7 service

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

### Configuration

The SS7 Diameter Configuration includes:

Parameters | Description
--- | ---
EventChargingMethod | One of: `reserveAndCharge` (for ECUR) `chargeAndRefund` (for IEC)

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
DiameterConfigurationTable | Service configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API — see SS7 Diameter Configuration REST API.

## Session Control Configuration

### Description

Configuration name | Session Control
Applicable contexts | SS7 service

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

### Configuration

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

- for controlling the charging for the duration for the session

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

The Session Control configuration includes:

Parameters | Description
--- | ---
SessionControlMethod | Whether charging during the session shall be performed via internal SLEE Timer, via Apply Charging Reports from the MSC, or via Call Information Report once at the very end of the session. Valid options are: protocolDefault— Use a sensible default for the currently executing protocol. notControlled— Don’t control call duration. controlViaSleeTimer— Periodically perform charging queries based on configurable session timer. controlViaApplyCharging— Use `ApplyCharging` messages to drive charging interactions. Default for CAP session control. controlViaSleeTimerWithFinalACR— Send an initial `ApplyChargingRequest` and expect a final `ApplyChargingReport`. Use session timer to control charging interactions mid-call in the same way as controlViaSleeTimer. Default for CS1+ session control. controlViaCallInformationReport— Use CallInformationReport-based charging interaction method.
PreferredEndCallChargingEvent | Whether to use Apply Charging Report or Call Information Report for credit finalisation, in the case where both these events are available at call end. Valid options are: ‘useACR’, ‘useCIRp’.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SessionControlMethodTable | Service configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

The configuration can be provisioned using the Sentinel machine provisioning API — see SS7 Session Control REST API.

## Sentinel Components

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

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

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

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

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

- Address lists

- SLEE usage parameter sets

## Resource Adaptors

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

### OpenCloud Resource Adaptors used by Sentinel

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

The Resource Adaptors Entities may include:

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

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

- cgin — adapts inbound CAP sessions for CAMEL IN integration

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

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

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

- dbquery-0 — manages relational database connections through JDBC

- hector — manages Cassandra connections

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

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

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

### CGIN RA

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

### Resource Adaptor Overviews

Below are overviews of:

- CDR resource adaptor

- CGIN resource adaptor

- Correlation resource adaptor

- DB Query resource adaptor

- Diameter resource adaptor

- SIP SIS resource adaptor

- Unique ID resource adaptor

## 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
--- | ---
`sentinel-cgin` | `cginra`
`sentinel-cgin-atilookup` | `cginmapra`
`sentinel-cgin-flashsms` | `cginmapra`
`sentinel-cgin-mnplookup` | `cginmapra`
`sentinel-cgin-sribasiccall` | `cginmapra`
`sentinel-cgin-ussdnotification` | `cginmapra`

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

## Correlation Resource Adaptor

### Correlation RA Overview

#### What is the Correlation RA?

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

The Correlation RA is used for two cases in Sentinel:

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

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

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

### Configuring a Correlation RA entity

A Correlation RA entity configuration consists of:

- [ra-configuration]

- [entity-configuration]

- [pools-configuration]

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
`ConfigProfileTable` | String | The SLEE profile table with an RA configuration profile for this RA entity.
`ConfigProfile` | String | The SLEE profile in the ConfigProfileTable with configuration for this RA entity.
`CorrelationIdPoolProfileTable` | String | The SLEE profile table with correlation ID pool definitions for this Correlation RA entity.

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

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

#### Correlation RA entity configuration profile

The Correlation RA configuration profile has the following attributes:

Name | Type | Description
`RequestTimeout` | Int | The maximum time (measured in ms) the Correlation RA will spend trying to allocate a correlation ID.
`CorrelationIDExpiryTimerPeriod` | Int | The maximum time (measured in ms) that an active correlation ID is considered to be still valid.
`NumberOfThreadPool` | Int | How many threads the Correlation RA entity should use.

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

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

#### Correlation RA entity ID pools configuration

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

- a default ID pool (optional)

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

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

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

`addressPrefixes` | An array of address prefixes that corresponds to this pool. The default pool has an empty addressPrefixes array.
`nodeIds` | An array of node IDs for which this pool has correlation IDs.
`isPreconfiguredCorrelationIdSetUsed` | If true, configure this ID pool with a pre-configured set of correlation IDs, else derive the correlation IDs.
`preconfiguredCorrelationIdSet` | The preconfigured set of correlation IDs per node (delimited with ‘:’).
`minCorrelationIDInCluster` | The minimum correlation ID value used in the cluster. 0 to maxCorrelationIDInCluster
`maxCorrelationIDInCluster` | The maximum correlation ID value used in the cluster. 0 to (10^18-1)
`correlationIDNumberOfDigits` | The number of digits the correlation ID should have. Minimum of number of digits in maxCorrelationIDInCluster to 18 maximum.
`correlationIDRangePerNode` | The number of correlation IDs that can be used for each node in the cluster.

There are two possible configuration options for correlation ID pools.

##### A prescribed set of IDs for each node

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

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

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

- etc.

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

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

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

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

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

- `NodeIds[0]`—`[MinCorrelationIDInCluster …​ MinCorrelationIDInCluster + CorrelationIDRangePerNode[0]]`

- `NodeIds[1]`—`[MinCorrelationIDInCluster + CorrelationIDRangePerNode[0] + 1 …​ MinCorrelationIDInCluster + +CorrelationIDRangePerNode[0] + 1 + CorrelationIDRangePerNode[1]]`

- etc.

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

##### Provisioning Interfaces

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

#### Monitoring Correlation RA entity statistics

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

Counters

Name | Description
--- | ---
`correlationGets` | Count of correlation IDs which have been requested via `findCorrelationEntry()`
`localGets` | Count of correlation queries which returned immediately (synchronous delivery) as the local RA had the data available.
`remoteGets` | Count of correlation queries which did not return immediately (asynchronous delivery) as the local RA did not have the data available.
`remoteDelivery` | Count of correlation queries which required delivering data to another correlation RA instance.
`unknown` | Count of correlation queries which could not be remotely delivered as the destination RA for a correlation ID was unknown.

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

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

### Using the Correlation RA

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

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

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

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

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

CorrelationProvider interface:

    public interface CorrelationProvider {

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

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

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

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

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

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

CorrelationResult interface:

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

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

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

CorrelationActivity interface:

    public interface CorrelationActivity {

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

    }

#### Handling synchronous results

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

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

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

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

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

#### Handling asynchronous results

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

Requesting correlation data asynchronously is done as follows:

- Create a new correlation activity using `CorrelationProvider.createActivity()`

- Get an `ActivityContextInterface` object for the activity.

- Attach the SBB local object to the ACI.

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

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

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

The follow example demonstrates the handling an asynchronous correlation query:

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

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

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

#### Javadoc API

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

## DBQuery Resource Adaptor

### DBQuery resource adaptor entities

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

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

View the Diameter RA documentation here.

### Diameter resource adaptors

There are currently three diameter resource adaptor entities in Sentinel:

- `diameterro-0`— for OCS connections

- `diameterro-1`— for client connections

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

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

#### Session timeouts

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

#### Diameter version configuration

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

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

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

#### OCS load balancing

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

##### Example configuration for OCS load balancing

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

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

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

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

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

The following `rhino-console` session shows the complete configuration:

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

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

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

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

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

## SIP SIS Resource Adaptor

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

| Refer to the SIS documentation for more information about the SIP SIS resource adaptor.

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

Link name | Default Bound RA entity
--- | ---
`sentinel-sip` | `sip-sis-ra`

### Sentinel and SIS

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

#### Configuring SIS

Use the `sis-console` or SIS REM Module to modify the default SIS and sip-sis-ra configuration properties; see the SIS administration guide and SIS REM Module user guide for more details on managing the SIS instance.

##### Configuring the network interface

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

## Unique ID Resource Adaptor

### What is the Unique ID RA?

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

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

#### Usage within Sentinel

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

### Configuring the Unique ID RA entity

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

### Type and format of the IDs

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

### Using the Unique ID RA

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

## Features

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

Feature category | For…​
--- | ---
General | many networks
Query and Notification | querying network elements and sending notifications
CAMEL | CAMEL networks
SIP | SIP networks
Diameter Service | Diameter networks
Test | testing

## General Features

Sentinel includes many features that are useable in many networks:

- Do Not Charge Session Feature— 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.

- 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
SAS Support | No
Prerequisite Features | None

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

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

### Session state inputs and outputs

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

### Error scenarios

This feature has no error conditions.

### Feature responses

Response | Reason
--- | ---
doNotChargeSession | intended behaviour
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## HTTP Determine Network Operator Feature

### Description

Feature name | HttpDetermineNetworkOperator
Applicable contexts | SS7 Service, SIP Service, Sentinel Charge Example
SAS Support | No
Prerequisite Features | None

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

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

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

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | A selection key to be populated with the network operator for this session | Runtime exception handled by feature runner

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>:<network>:::`) | A Sentinel selection key with a non-empty network operator field

### Error scenarios

Scenario | Handling
--- | ---
Trigger is not an HTTP request | Report featureCannotStart Finish
Malformed name-value pair in HTTP request | Increment CouldNotDetermineNetworkOperator stat Use SentinelConfiguration defaultNetworkOperator
Configured name-value pair not found in request | Increment CouldNotDetermineNetworkOperator stat Use SentinelConfiguration defaultNetworkOperator
No configured mapping found for value in `SentinelHttpParameterToNetworkOperatorProfileTable` | Increment CouldNotDetermineNetworkOperator stat Use SentinelConfiguration defaultNetworkOperator

### Feature responses

Response | Reason
--- | ---
featureCannotStart | Trigger event must be an HttpRequest
featureHasFinished | feature has finished

### Configuration

The `SentinelHttpParameterToNetworkOperatorProfileTable`:

Parameter | Description
--- | ---
NetworkOperator | Network operator this profile’s name is mapped to

Relevant fields of the `SentinelPlatformConfigurationTable`:

Parameter | Description
--- | ---
HttpParameterForHttpDetermineNetworkOperator | Name of the HTTP parameter to search for in the request URL
DefaultNetworkOperator | Network operator to fall back to if the HTTP parameter is not found in the request URL, or no mapping is found in the SentinelHttpParameterToNetworkOperatorProfileTable

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SentinelHttpParameterToNetworkOperatorProfileTable | Mapping of HTTP parameter values to network operator names | HTTP parameter value (for example, 00102)

### Provisioning interfaces

The feature is provisioned using the Sentinel HTTP Determine Network Operator REST API or web interface.

## OcsParameterConfiguration Feature

### Description

Feature name | OcsParameterConfiguration
Applicable contexts | SS7 Service, SIP Service, Diameter Service
SAS Support | No
Prerequisite Features | None

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, <platform>::::) | For selecting configuration data | Do not set RequestUnitsSeconds or RequestUnitsServiceSpecificReport featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
RequestUnitsSeconds | Long | Positive integer | Number of seconds to request from OCS in a decentralized unit determination scenario
RequestUnitsServiceSpecific | Long | Positive integer | Number of service-specific units to request from OCS in a decentralized unit determination scenario

### Error scenarios

Scenario | Handling
--- | ---
Missing configuration profile | Use session state defaults

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

The OcsParamConfigFeatureConfigProfileTable:

Parameter | Type | Description
--- | --- | ---
RequestUnitsSeconds | Long | Units in seconds for Requested-Service-Unit/CC-Time Integer
RequestUnitsServiceSpecific | Long | Units as defined by the service for Requested-Service-Unit/CC-Service-Specific-Units Integer

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
OcsParamConfigFeatureConfigProfileTable | Selection of ocs parameters | SentinelSelectionKey (for example, `OpenCloud:OpenCloud:::`)

### Provisioning interfaces

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

## Platform Operator is Network Operator Feature

### Description

Feature name | PlatformOperatorIsNetworkOperator
Applicable contexts | All Services
SAS Support | No
Prerequisite Features | None

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

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

Platform Operator | Network Operator | Session Type | Plan | Subscriber
--- | --- | --- | --- | ---
OpenCloud |  |  |  |

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

Platform Operator | Network Operator | Session Type | Plan | Subscriber
--- | --- | --- | --- | ---
OpenCloud | OpenCloud |  |  |

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | Selection key including platform operator (for example, `<platform>::::`) | Platform operator to copy into NetworkOperator field of key | Runtime exception handled by feature runner

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | Selection key including network operator equal to platform operator (for example, `<platform>:<platform>:::`) | Platform operator has been copied into NetworkOperator field

### Error scenarios

This feature always succeeds.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## Session Tracing Activation Feature

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

### Description

Feature name | SessionTracing
Applicable contexts | All services
SAS Support | No
Prerequisite Features | None

Two functions will be supported initially:

- Prefix and exact match of the subscriber number based on Black/White lists

- Percentage of Calls (not subscriber specific).

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

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
Subscriber | String | SIP, Diameter, or SS7 Subscriber number format — see the respective Subscriber Determination features | The subscriber address for this session | Report featureCannotStart, featureHasFinished

#### Outputs

This feature does not write to SessionState.

### Error scenarios

Scenario | Handling
--- | ---
Missing entry in SessionTracingFeatureConfigProfileTable | Report featureCannotStart
Sessionstate Subscriber is null | Report featureCannotStart
Missing SessionTracingAddressPrefixList, addressListId, or addressList | Do not enable tracing

### Feature responses

Response | Reason
--- | ---
featureCannotStart | Configuration data is not found or subscriber address is not set in session state
featureHasFinished | feature has finished

### Configuration

#### General feature configuration

Parameter | Type | Description
--- | --- | ---
AverageNumberOfCallsToBeTraced | Integer | Calls per 10,000 traced: 0(0%), 1(0.01%), 10(0.1%), 100(1%), 1000(10%)
IsListScreeningModeUsed | Boolean | true/false. True selects list screening; false selects random tracing of sessions.

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

Percentage setting:

- 0 — no calls are enabled

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

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

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

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

- No other configuration values valid

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

#### Address list configuration

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

#### Tracing output

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

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

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SessionTracingFeatureConfigProfileTable | Session tracing configuration parameters | SentinelSelectionKey (for example, `OpenCloud::::`)
${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable | Address list configuration | ${SELECTIONKEY}:SessionTracing:AddressPrefixList
${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable | Feature specific Address List entry table | ${SELECTIONKEY}:SessionTracing:AddressPrefixList:${ADDRESS}

### Provisioning interfaces

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

## Subscriber Data Lookup Feature

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

### Description

Feature script name | SubscriberDataLookup
Applicable contexts | All services
SAS Support | No
Prerequisite Features | One of SS7 Subscriber Determination Feature, SIP Subscriber Determination Feature or Diameter Subscriber Determination Feature

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
Subscriber | String | SIP, Diameter, or SS7 Subscriber number format — see the respective Subscriber Determination features | The subscriber for this session whose data is to be retrieved from the subscriber database | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
Any sessionstate field | Supported types: String, Boolean, Integer, String[], Date[], Date | Any format | Data to be loaded into sessionstate from subscriber database

### Error scenarios

Scenario | Handling
--- | ---
Missing lookup type configuration | Report featureCannotStart
Sessionstate Subscriber is null | Report featureCannotStart
Exception while loading subscriber data from data source | Report featureCannotStart
No subscriber data found or empty record | Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureCannotStart | invalid configuration
featureFailedToExecute | invalid subscriber
featureHasFinished | feature has finished

### Configuration

#### Subscriber record field configuration:

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

Field | Type | Description
--- | --- | ---
ColIdx | String | Indicates the column index of this field in a subscriber data record. Should match the profile name.
InsertParamIdx | int | Indicates the column index of this field in a subscriber data record. Should match the profile name.
ResFieldname | String | Name of the field when read into a result record
SessionStateFieldname | String | Name of the session state field this field should be loaded into
Type | String | The type of the field, both in session state and in the data source. Supported types: String, Boolean, Integer, String[], Date[], Date
UpdateParamIdx | int | Indicates the column index of this field in a subscriber data record. Should match the profile name.

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

- Platform operator

- Network operator

- Session type

- The field definitions are configurable by Sentinel selection key.

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

- MySQL via JDBC

- TimesTen via JDBC

- Oracle via JDBC

- Cassandra database (experimental).

- JSLEE profiles (testing purposes)

#### Data source configuration

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

Field | Type | Description
--- | --- | ---
LookupType | String | One of dbQuery, profile, profileIms, or Cassandra

Lookup type | Description
--- | ---
dbQuery | Uses the dbquery-0 ra entity to perform the subscriber data query. This option is used for all the different RDBMS types such as MySQL, Oracle, and TimesTen. The type of database used and the associated settings are configured in the {{dbquery-0}}resource adaptor entity configuration. See DBQuery Resource Adaptor for further configuration information.
profile | Uses the ${PLATFORMOPERATOR}_SubscriberDataRecordProfileTable for the lookup. Only suitable for small sets of subscribers for testing and development purposes.
profileIms | Uses the ${PLATFORMOPERATOR}SubscriberDataImsPublicUserIdentityProfileTable and ${PLATFORMOPERATOR}SubscriberDataRecordProfileTable for the query.
Cassandra | Experimental.

#### SQL statement configuration

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

SubscriberDataLookupSqlConfigProfileTable:

Field | Type | Description
--- | --- | ---
LoadSQL | String | The SQL query for loading subscriber data from the data source. For example:
    SELECT * FROM OpenCloud_Subscribers WHERE MSISDN = ?
ListSQL | String | The SQL query for listing Subscriber Data record ids (msisdns). For example:
    SELECT MSISDN FROM OpenCloud_Subscribers ORDER BY MSISDN
InsertSQL | String | The SQL query for inserting a new Subscriber Data record. For example:
    INSERT INTO OpenCloud_Subscribers
        (MSISDN,IMSI,FirstCall,subscriberlanguage,Account,SubscriptionType,ValidityStart,
        ValidityEnd,HomeZoneEnabled,HomeZoneList,ocsId,FriendsAndFamilyEnabled,FriendsAndFamilyList,
        ClosedUserGroupEnabled,ClosedUserGroupList,ClosedUserGroupPreferred,CUGIncomingAccessAllowed,
        CUGOutgoingAccessAllowed,CfBusy,CfNoReply,PromotionList,PromotionValidityStartDates,
        PromotionValidityEndDates)
    VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
UpdateSQL | String | The SQL query for updating a Subscriber Data record. For example:
    UPDATE OpenCloud_Subscribers
        SET IMSI = ?,FirstCall = ?,subscriberlanguage = ?,Account = ?,SubscriptionType = ?,
            ValidityStart = ?,ValidityEnd = ?,HomeZoneEnabled = ?,HomeZoneList = ?,ocsId = ?,
            FriendsAndFamilyEnabled = ?,FriendsAndFamilyList = ?,ClosedUserGroupEnabled = ?,
            ClosedUserGroupList = ?,ClosedUserGroupPreferred = ?,CUGIncomingAccessAllowed = ?,
            CUGOutgoingAccessAllowed = ?,CfBusy = ?,CfNoReply = ?,PromotionList = ?,
            PromotionValidityStartDates = ?,PromotionValidityEndDates = ?
        WHERE MSISDN = ?
DeleteSQL | String | The SQL query for deleting a Subscriber Data record. For example:
    DELETE FROM OpenCloud_Subscribers WHERE MSISDN = ?
loadByImsPublicUserIdentitySQL | String | SQL statement for loading a subscriber data record by a subscriber’s IMS public user identity; for example:
    SELECT subs.* FROM @platform.operator.name@_Subscribers subs
        INNER JOIN @platform.operator.name@_SubscriberImsPublicUserIdentity sipids
        ON subs.MSISDN = sipids.SubscriberId
        WHERE sipids.ImsPublicUserId = ?
listImsPublicUserIdentitiesSQL | String | SQL statement for listing a subscriber’s IMS public user identities based on their subscriber ID
insertImsPublicUserIdentitySQL | String | SQL statement for inserting a new IMS public user identity for a subscriber
deleteImsPublicUserIdentitySQL | String | SQL statement for deleting a single IMS public user identity for a subscriber
deleteAllImsPublicUserIdentitiesForSubscriberSQL | String | SQL statement for deleting all of a subscriber’s IMS public user identities
useImsPublicUserIdentities | boolean | Use IMS Public User Identity SQL statements?
DatabaseRequestTimeout | int | The timeout period for any SQL query. Must be greater than 0
AsynchronousQuery | boolean | Uses DBQuery RA events to return result sets if true otherwise blocks the staging thread waiting for DatabaseRequestTimeout period using futures.

### Subscriber data schema

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

Parameter name | Parameter type | Description
--- | --- | ---
MSISDN | String | Identifies the subscriber record
Language | String | Language code set during first call handling
Account | String | Account code required by the OCS

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

Parameter name | Parameter type | Description
--- | --- | ---
IMSI | String | Required by some service features
OCSId | String | Id of the OCS for this subscriber
SubscriptionType | String | identifes the subscription type of the subscriber
ValidityStart | String | Time and timezone of subscription validity. See Subscriber Validity Feature
ValidityEnd | String | Time and timezone of subscription validity. See Subscriber Validity Feature
HomeZoneEnabled | Boolean | True when HomeZone feature is activated for this subscriber. See Home Zone Feature
HomeZoneList | String[] | List of zones for this subscriber. See Home Zone Feature
FriendsAndFamilyEnabled | Boolean | true when HomeZone feature is activated for this subscriber. See Friends and Family Feature
FriendsAndFamilyList | String[] | List of zones for this subscriber. See Friends and Family Feature
ClosedUserGroupEnabled | Boolean | true when HomeZone feature is activated for this subscriber. See Closed User Group Feature
ClosedUserGroupList | String[] | List of zones for this subscriber. See Closed User Group Feature
ClosedUserGroupPreferred | Integer | List of zones for this subscriber. See Closed User Group Feature
CUGIncomingAccessAllowed | Boolean | See Closed User Group Feature
CUGOutgoingAccessAllowed | Boolean | See Closed User Group Feature
CfBusy | String | Forwarding number on busy. See Default Call Forwarding Feature
CfNoReply | String | Forwarding number on no reply. See Default Call Forwarding Feature
PromotionList | String array | Used by the `subscriberIsEligible` promotion script function. See Scripted Promotions Feature
PromotionValidityStartDates | String[] | Used by the `subscriberIsEligible` promotion script function. See Scripted Promotions Feature, and Subscriber Validity Feature for the date format
PromotionValidityEndDates | String[] | Used by the `subscriberIsEligible` promotion script function. See Scripted Promotions Feature, and Subscriber Validity Feature for the date format

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

Parameter name | Parameter type | Description
--- | --- | ---
CURRENTLY NONE |  |

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

Example:

MSISDN | 34600000001
Language | English
Account | 6325
IMSI | 346000000021234
OCSId | 1
SubscriptionType | No
ValidityStart | 1299193200664
ValidityEnd | 3161070000000
HomeZoneEnabled | false
HomeZoneList | [WgtnCBD]
FriendsAndFamilyEnabled | false
FriendsAndFamilyList | [34600000001]
ClosedUserGroupEnabled | false
ClosedUserGroupList | [CUG1Profile]
ClosedUserGroupPreferred | 1
CfBusy | 34600000002
CfNoReply | 34600000003
PromotionList | [FreeOffpeakVoice]
PromotionValidityStartDates | [1299193200664]
PromotionValidityEndDates | [3161070000000]
IMS | Public User Identities

Parameter Name | Parameter type | Description
--- | --- | ---
ImsPublicUserId | String | an IMS public user identity
SubscriberId | String | subscriber ID used as key to the subscriber data table

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
${PLATFORMOPERATOR}_SubscriberDataRecordProfileTable | Per subscriber data records — use only for very small subscriber sets | MSISDN
${PLATFORMOPERATOR}_SubscriberDataImsPublicUserIdentityProfileTable | IMS public user identity to subscriber ID table — use only for very small subscriber sets | IMS Public User Identity, for example sip:user34600000002@opencloud.com
SubscriberDataLookupConfigProfileTableName | Field configuration and session state mapping | SentinelSelectionKey (for example, `OpenCloud::::`)
SubscriberDataLookupSqlConfigProfileTableName | SQL statement configuration | SentinelSelectionKey (for example, `OpenCloud::::`)
${SELECTIONKEY}_SubscriberDataLookupFieldDefinitionProfileTable | Table for mapping sql columns to session state; note that the SELECTIONKEY part has ‘^’ as separator character in this case for the table name! | Any name unique to the table

### Database schemas

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

### Provisioning interfaces

The SubscriberDataLookup feature subscriber records and configuration may be provisioned using the Sentinel Subscriber Data REST API or web interface for the records and feature configuration.

### Additional database support

For additional database support, please contact OpenCloud.

## Subscriber Validity Feature

### Description

Feature script name | SubscriberValidity
Applicable contexts | All services
SAS Support | No
Prerequisite features | SubscriberDataLookup

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

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

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

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

### OCS interface

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
ValidityStart | long | The time in UTC milliseconds from the epoch | Start of the subscriber’s validity period | value ⇐0 implies validity until ValidityEnd
ValidityEnd | long | The time in UTC milliseconds from the epoch | End of the subscriber’s validity period | value ⇐0 implies validity from ValidityStart

#### Outputs

This feature does not write to sessionstate.

### Error scenarios

Scenario | Handling
--- | ---
Invalid subscriber | Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureFailedToExecute | invalid subscriber
featureHasFinished | feature has finished

### Configuration

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

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

Parameter | Type | Description
--- | --- | ---
ValidityStart | String | Time and timezone of subscription validity
ValidityEnd | String | Time and timezone of subscription validity

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

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

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

Example:

ValidityStart | 2011-03-04T12:00:00+02:00
ValidityEnd | 2070-03-04T00:00:00-08:00

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

### Provisioning interfaces

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

## Query And Notification Features

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

- ATI Lookup Feature— 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
SAS Support | No
Prerequisite Features | Determine ATI Lookup Number Feature

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

The ATI response is saved in the Sentinel session state.

### Feature parameters

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

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

### Session State inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | See error handling for `ATILookupFeatureConfigProfileTable`
ATILookupNumber | String | MSISDN string | Subscriber MSISDN to perform the ATI lookup for | See error handling

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
AnyTimeInterrogationRes | com.opencloud.slee.resources.cgin.map.MAPAnyTimeInterrogationRes | MAPAnyTimeInterrogationRes | The ATIResponse from the HLR for the ATILookup

### Error scenarios

Scenario | Handling
--- | ---
Missing entry in ATILookupFeatureConfigProfileTable | Increment SendFailures stat Report featureFailedToExecute
Null sessionstate ATILookupNumber | Increment SendFailures stat Report featureFailedToExecute
Error parsing ATILookupNumber | Increment SendFailures stat Report featureFailedToExecute
Null sessionstate HLRAddress | Increment SendFailures stat Report featureFailedToExecute
Null sessionstate GSMSCFAddress | Increment SendFailures stat Report featureFailedToExecute
Failed to send request Increment | SendFailures stat Report featureFailedToExecute
ATIResponse missing SubscriberInfo.MnpInfo | Increment MalformedResponses and ReceivedResponses stats Do not set sessionstate AnyTimeInterrogationRes End and detach from dialog

### Feature responses

Response | Reason
--- | ---
featureFailedToExecute | ATI response timeout or failed sending request
featureHasFinished | feature has finished

### Configuration

The ATI Lookup configuration includes:

Parameters | Type | Description
--- | --- | ---
SccpOriginatingAddress | SCCP address | Will be used as the TCAP Calling Party Address in dialogs initiated towards the HLR and MSC. May be null, in which case the local SCCP address configured for the platform is used. Example: `type=c7,ri=gt,digits=34607012345,nature=national,national=true`
InvokeTimeout | Long | AnyTimeInterrogation invoke timeout in milliseconds (for example, 5000). A ‘0’ value results in CGIN RA defaults being used.
RouteOnSubscriberNumber | Boolean | ‘true’ will route based on the selected ATILookupNumber.
GSMSCFAddress | AddressString | Return address for responses (such as address of Sentinel)
HLRAddress | SCCP address | Static HLR address, or dynamic address template used when performing dynamic routing.
QueryLocationInfo | Boolean | Whether to include location info query in the ATI request.
QuerySubscriberState | Boolean | Whether to include subscriber state query in the ATI request.
QueryIMEI | Boolean | Whether to include IMEI query in the ATI request.
QueryMSClassmark | Boolean | Whether to include MS Classmark query in the ATI request.

### HLR routing determination

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

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
ATILookupFeatureConfigProfileTable | Feature configuration | SentinelSelectionKey (such as `OpenCloud::::`)

### Provisioning interfaces

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

## Determine ATI Lookup Number Feature

### Description

Feature name | DetermineATILookupNumber
Applicable contexts | SS7 service
SAS Support | No
Prerequisite Features | Classify Call Scenario Feature SS7 Subscriber Determination Feature (optional, based on feature configuration.)

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |  | InitialDP which triggered this session | Report featureCannotStart
CallType | com.opencloud.sentinel.common.CallType |  | Session type of this call for determining from configuration which party address to look up | Report featureCannotStart

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
ATILookupNumber | String | MSISDN string | The subscriber address to perform the ATI Lookup for

### Error scenarios

Scenario | Handling
--- | ---
Missing entry in DetermineATILookupNumberConfigProfileTable | Report featureCannotStart
Session state InitialDPArg is null | Report featureCannotStart
Session state InitialDPArg not CAP | Report featureCannotStart
Session state CallType is null | Report featureCannotStart
No configured lookup party for call scenario | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureCannotStart | invalid or missing configuration
featureHasFinished | feature has finished

### Configuration

The Determine ATI Lookup Number configuration includes:

Parameters | Type | Description
--- | --- | ---
MobileOriginatingParty | LookupPartyEnum | The party to use for the subsequent ATI Lookup (via the ATI Lookup Feature) for mobile originating calls.
MobileTerminatingParty | LookupPartyEnum | The party to use for the subsequent ATI Lookup (via the ATI Lookup Feature) for mobile terminating calls.
MobileForwardedParty | LookupPartyEnum | The party to use for the subsequent ATI Lookup (via the ATI Lookup Feature) for mobile forwarded calls.

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

Value name | Description
--- | ---
CallingPartyNumber | Indicates to set the ATI Lookup number from the InitialDP.CallingPartyNumber
CalledPartyNumber | Indicates to set the ATI Lookup number from the InitialDP.CalledPartyNumber
CalledPartyBCDNumber | Indicates to set the ATI Lookup number from the InitialDP.CalledPartyBCDNumber
SessionSubscriber | Indicates to set the ATI Lookup number from the Sentinel session subscriber.

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

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
DetermineATILookupNumberConfigProfileTable | Feature configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

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

## Determine MNP Lookup Number Feature

### Description

Feature name | DetermineMNPLookupNumber
Applicable contexts | SS7 service
SAS Support | No
Prerequisite Features | Classify Call Scenario Feature SS7 Subscriber Determination Feature (Optional, based on feature configuration.)

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |  | InitialDP which triggered this session, from which the lookup number will be read | Report featureCannotStart
CallType | com.opencloud.sentinel.common.CallType |  | Session type of this call for determining from configuration which party address to lookup | Report featureCannotStart

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
MNPLookupNumber | String | MSISDN string | The subscriber address to perform the MNP Lookup for

### Error scenarios

Scenario | Handling
--- | ---
Missing entry in DetermineMNPLookupNumberConfigProfileTable | Report featureCannotStart
Sessionstate InitialDPArg is null | Report featureCannotStart
Sessionstate InitialDPArg not CAP | Report featureCannotStart
Sessionstate CallType is null | Report featureCannotStart
No configured lookup party for call scenario | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureCannotStart | invalid or missing configuration
featureHasFinished | feature has finished

### Configuration

The Determine MNP Lookup Number configuration includes:

Parameters | Type | Description
--- | --- | ---
MobileOriginatingParty | LookupPartyEnum | The party to use for the subsequent ATI Lookup (via the MNP Lookup Feature) for mobile originating calls
MobileTerminatingParty | LookupPartyEnum | The party to use for the subsequent ATI Lookup (via the MNP Lookup Feature) for mobile terminating calls
MobileForwardedParty | LookupPartyEnum | The party to use for the subsequent ATI Lookup (via the MNP Lookup Feature) for mobile forwarded calls

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

Value name | Description
--- | ---
CallingPartyNumber | Indicates to set the MNP Lookup number from the InitialDP.CallingPartyNumber
CalledPartyNumber | Indicates to set the MNP Lookup number from the InitialDP.CalledPartyNumber
CalledPartyBCDNumber | Indicates to set MNP ATI Lookup number from the InitialDP.CalledPartyBCDNumber
SessionSubscriber | Indicates to set the MNP Lookup number from the sentinel session subscriber. Using this value requires a previous execution of the SS7 Subscriber Determination Feature

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
DetermineMNPLookupNumberConfigProfileTable | Feature configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

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

## Determine SRI Lookup Number Feature

### Description

Feature name | DetermineSRILookupNumber
Applicable contexts | SS7 service
SAS Support | No
Prerequisite features | Classify Call Scenario Feature SS7 Subscriber Determination Feature (Optional, based on feature configuration)

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |  | InitialDP which triggered this session, from which the lookup number will be read | Report featureCannotStart
CallType | com.opencloud.sentinel.common.CallType |  | Session type of this call for determining from configuration which party address to lookup | Report featureCannotStart

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
SRILookupNumber | String | MSISDN string | The subscriber address to perform the SRI Lookup for

### Error scenarios

Scenario | Handling
--- | ---
Missing entry in DetermineSRILookupNumberConfigProfileTable | Report featureCannotStart
Sessionstate InitialDPArg is null | Report featureCannotStart
Sessionstate InitialDPArg not CAP | Report featureCannotStart
Sessionstate CallType is null | Report featureCannotStart
No configured lookup party for call scenario | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureCannotStart | invalid or missing configuration
featureHasFinished | feature has finished

### Configuration

The Determine SRI Lookup Number configuration includes:

Parameters | Type | Description
--- | --- | ---
MobileOriginatingParty | LookupPartyEnum | The party to use for the subsequent SRI Lookup (via the SRI for Basic Call Routing Feature) for mobile originating calls.
MobileTerminatingParty | LookupPartyEnum | The party to use for the subsequent SRI Lookup (via the SRI for Basic Call Routing Feature) for mobile terminating calls.
MobileForwardedParty | LookupPartyEnum | The party to use for the subsequent SRI Lookup (via the SRI for Basic Call Routing Feature) for mobile forwarded calls.

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

Value name | Description
--- | ---
CallingPartyNumber | Indicates to set the SRI Lookup number from the InitialDP.CallingPartyNumber
CalledPartyNumber | Indicates to set the SRI Lookup number from the InitialDP.CalledPartyNumber
CalledPartyBCDNumber | Indicates to set the SRI Lookup number from the InitialDP.CalledPartyBCDNumber
SessionSubscriber | Indicates to set the SRI Lookup number from the Sentinel session subscriber. Using this value requires a previous execution of the SS7 Subscriber Determination Feature.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
DetermineSRILookupNumberConfigProfileTable | Feature configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

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

## Flash SMS Notification Feature

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

### Description

Feature name | FlashSms
Applicable contexts | SS7 service
SAS Support | No * Diameter service * SIP service
Prerequisite features | A feature to set the NotificationMessage and NotificationAddress session state variables

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

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

- Address in NotificationAddress session state variable (if set)

- Address in Subscriber session state variable.

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

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

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Increment SmsDeliveryFailures, return
IMSI | String | IMSI | The subscriber’s IMSI address, which may require an SRI lookup if null | Perform an SRI lookup
MSCAddress byte[] | SCCP address | The subscriber’s current MSC address, which may require an SRI lookup if null | Perform an SRI lookup | NotificationMessage
String | Arbitrary text | The textual content of the flash SMS | Increment SmsDeliveryFailures, return | NotificationAddress
String | MSISDN | The flash SMS destination address | Fall back to session state Subscriber address | Subscriber

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
IMSI | String | IMSI | Determined through SRI lookup if previously null
MSCAddress | byte[] | SCCP address | Determined from SRI lookup if previously null

### Error scenarios

This table applies if an SRI is required:

Scenario | Handling
--- | ---
Null sessionstate selection key | Increment SmsDeliveryFailures
Missing entry in FlashSmsFeatureConfigProfileTable | Increment SmsDeliveryFailures
No notification address or subscriber address | Increment SmsDeliveryFailures
Null TemplateHlrSccpAddress in FlashSMS config | Increment SmsDeliveryFailures
Exception sending SRI | Increment SmsDeliveryFailures
OpenRefuse from HLR | Increment HlrSS7ProviderErrors or HlrSS7UserErrors Increment SmsDeliveryFailures Close dialog Increment HlrSS7Errors
Abort from HLR | Increment HlrProviderAborts or HlrUserAborts Increment SmsDeliveryFailures Increment HlrAbortsReceived
Timeout waiting for HLR response | Increment HlrTimeouts Increment HlrSS7ProviderErrors or HlrSS7UserErrors Increment SmsDeliveryFailures Close dialog
Exception closing dialog in any HLR dialog failure scenario | Increment SmsDeliveryFailures Increment HlrSS7Errors

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

Scenario | Handling
--- | ---
No notification address or subscriber address in sessionstate | Increment SmsDeliveryFailures
Null sessionstate MSCAddress | Increment SmsDeliveryFailures
Null sessionstate IMSI | Increment SmsDeliveryFailures
Null sessionstate NotificationMessage | Increment SmsDeliveryFailures
Exception sending mtForwardSM request | Increment SmsDeliveryFailures
MessageEncodingFailure sending mtForwardSM request | Increment SmsDeliveryFailures Increment EncodingFailure
OpenRefuse from MSC | Increment MscSS7ProviderErrors or MscSS7UserErrors Increment SmsDeliveryFailures Close dialog Increment MscSS7Errors
Abort from MSC | Increment MscProviderAborts or MscUserAborts Increment SmsDeliveryFailures Increment MscAbortsReceived
Timeout waiting for MSC response | Increment MscTimeouts Increment MscSS7ProviderErrors or MscSS7UserErrors Increment SmsDeliveryFailures Close dialog

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

The Flash SMS Notification configuration includes:

Parameter | Type | Description
--- | --- | ---
SccpOriginatingAddress | SCCP address | Will be used as the TCAP Calling Party Address in dialogs initiated towards the HLR and MSC. May be null in which case the local SCCP address configured for the platform will be used. Example: `type=c7,ri=gt,digits=34607012345,nature=national,national=true`
InvokeTimeout | Long | SRIforSM and MTForwardSM invoke timeouts in milliseconds (for example, 5000). A 0 value results in CGIN RA defaults being used.
TemplateHlrSccpAddress | SCCP address | A template address that will be used to address the HLR. Global title digits in the template address will be replaced with the relevant notification address. The encoding scheme will also be updated, if relevant for the GT indicator type, to indicate BCD_ODD or BCD_EVEN, depending on the number of address digits.
TemplateMscSccpAddress | SCCP address | A template address that will be used to address the MSC. Global title digits in the template address will be replaced with the MSC address from session state. The encoding scheme will also be updated, if relevant for the GT indicator type, to indicate BCD_ODD or BCD_EVEN, depending on the number of address digits.
SMSAddressOriginatingAddress | SMSAddress | Local SCCP address (for example, `address=64600000002,nature=INTERNATIONAL,numberingPlan=ISDN`)
AddressStringServiceCentreAddress | AddressString | Service centre address (for example, `address=643434,nature=INTERNATIONAL,numberingPlan=ISDN`)
ShortMsgMTApplicationContext | TcapApplicationContext | The MAP application context to be used for the dialog towards the MSC. Must be one of: `shortMsgMT-RelayContext-v1-ac` `shortMsgMT-RelayContext-v2-ac` `shortMsgMT-RelayContext-v3-ac` `shortMsgMT-Relay-VGCS-Context-v3-ac`

### Call flow

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

1. Obtaining the routing information from the HLR.

2. Sending the MT SMS.

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

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

    hlrSccpAddress.address={SessionState.NotificationAddress or SessionState.Subscriber)
    hlrSccpAddress.nature=International
    hlrSccpAddress.numberingPlan=ISDN
    hlrSccpAddress.routingIndicator=(GT for extra/inter-PLMN, GT or SPC for intra-PLMN) default 0 (GT)
    hlrSccpAddress.GTI=0100 (Global title indicator = 0100 (Global title includes translation type, numbering plan, encoding scheme and nature of address indicator)
    hlrSccpAddress.type=C7
    hlrSccpAddress.ssnIndicator=1 (MAP SSN always included)
    hrlSccpAddress.ssn=(configured per network) default 6
    hrlSccpAddress.pc=(configured per network) default not set
    hlrSccpAddress.tt=0 (not used)

    imsi = RoutingInfoForSM-Res.imsi
    msc-number = RoutingInfoForSM-Res.locationInfoWithLMSI.networkNode-Number
    IF RoutingInfoForSM-Res.locationInfoWithLMSI.gprsNodeIndicator not present OR
       (RoutingInfoForSM-Res.locationInfoWithLMSI.gprsNodeIndicator present AND
        RoutingInfoForSM-Res.LocationInfoWithLMSI.additional-Number is sgsn-Number) THEN
        mscAddress = RoutingInfoForSM-Res.LocationInfoWithLMSI.networkNode-Number
    else
        mscAddress = RoutingInfoForSM-Res.LocationInfoWithLMSI.additional-Number

| RoutingInfoForSM-Res.locationInfoWithLMSI.networkNode-Number renamed from msc-Number between R96 and R97. The networkNode-number can also contain an sgsn-number or IP-SM-GW number or SMS Router number.

The second step is to send the MTForwardSM:

Field | Value
--- | ---
destination SCCP address | msc-number from the SRIforSM or MSCAddress session state field
sm-RP-DA.imsi | use the imsi from the SRIforSM or the IMSI session state field
sm-RP-OA.serviceCentreAddress | Sentinel address for response messages
sm-RP-UI | SMSDeliver as below
moreMessagesToSend | not set
extensionContainer | not set
smDeliveryTimer | not set
smDeliveryStartTime | not set

SMSDeliver:

Field | Value
--- | ---
onlyHeader | not set
replyPath | false
userDataHeaderIndicator | true
statusReportIndication | false
moreMessagesToSend | NONE
loopPrevention | false
originatingAddress | configurable address — probably some service number
protocolId | 0 (TelematicDevice.IMPLICIT)
dataCodingScheme | {MessageClass=SPARE_0, MessageCoding determined by encoded text, supports GSM_7BIT or UCS2}
serviceCentreTimeStamp | current time
userDataLength | length of encoded text based on data coding scheme
userData | encoded text

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

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
FlashSmsFeatureConfigProfileTable | Selection of database implementation and rating group for the feature. | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

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

MAP SPEC | Digital cellular telecommunications system (Phase 2+); Mobile Application Part (MAP) specification (3GPP TS 09.02 version 5.17.0 Release 1996) | ETSI/3GPP | 2002-03 | ETSI

## MNP Lookup Feature

### Description

Feature name | MNPLookup
Applicable contexts | SS7 service
SAS Support | No
Prerequisite features | Determine MNP Lookup Number Feature

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

The MNP response is saved in the sentinel session state.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Increment SendFailures stat Report featureFailedToExecute Return
MNPLookupNumber | String | MSISDN | Address to perform the MNP lookup for | Increment SendFailures stat Report eatureFailedToExecute Return

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
MNPInfo | com.opencloud.slee.resources.cgin.map.MAPMNPInfoRes | MAP-MS-DataTypes.MNPInfoRes | The MNP lookup result

### Error scenarios

Scenario | Handling
--- | ---
Missing entry in MNPLookupFeatureConfigProfileTable | Increment SendFailures stat Report featureFailedToExecute
Null sessionstate MNPLookupNumber | Increment SendFailures stat Report featureFailedToExecute
Error parsing MNPLookupNumber | Increment SendFailures stat Report featureFailedToExecute
Null MNPSRFSccpAddress configured in MNPLookupFeatureConfigProfileTable | Increment SendFailures stat Report featureFailedToExecute
Null GSMSCFAddressString configured in MNPLookupFeatureConfigProfileTable | Increment SendFailures stat Report featureFailedToExecute
Exception while trying to send ATIRequest | Increment SendFailures stat Report featureFailedToExecute
OpenRefuse from MNP SRF | Close dialog Increment SS7ProviderErrors or SS7UserErrors
Abort from MNP SRF | Close dialog Increment SS7Aborts
Timeout waiting for MNP SRF response | Close dialog Increment SS7Timeouts

### Feature responses

Response | Reason
--- | ---
featureFailedToExecute | Missing sessionstate or configuration data, exception while sending ATIRequest or error response from MNP SRF
featureHasFinished | feature has finished

### Configuration

The MNP Lookup configuration includes:

Parameters | Type | Description
--- | --- | ---
OriginatingSccpAddress | SCCP address | Will be used as the TCAP Calling Party Address in dialogs initiated towards the HLR and MSC. May be null in which case the local SCCP address configured for the platform will be used. Example: `type=c7,ri=gt,digits=34607012345,nature=national,national=true`
InvokeTimeout | Long | AnyTimeInterrogation invoke timeout in milliseconds (for example, 5000). A 0 value results in CGIN RA defaults being used.
GSMSCFAddress | AddressString | Return address for responses (for example, address of Sentinel)
MNPSRFSccpAddress | SCCP address | Static address of an MNP SRF.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
MNPLookupFeatureConfigProfileTable | Feature configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning Interfaces

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

## SRI for Basic Call Routing Feature

### Description

Feature name | SRIForBasicCallRouting
Applicable contexts | SS7 service
SAS Support | No
Prerequisite features | Determine SRI Lookup Number Feature

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

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Increment SendFailures stat Report featureFailedToExecute Report featureHasFinished Return
SRILookupNumber | String | MSISDN | Address for which to perform SRI lookup | Return

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
SendRoutingInfoRes | com.opencloud.slee.resources.cgin.map.MAPSendRoutingInfoRes_v3 | MAP-CH-DataTypes.SendRoutingInfoRes-v3 | The result of the SRI lookup

### Error scenarios

Scenario | Handling
--- | ---
Missing profile entry in SRIForBasicCallRoutingFeatureConfigProfileTable | Increment SendFailures stat Report featureFailedToExecute Report featureHasFinished
Exception creating MSISDN string using sessionstate SRILookupNumber | Report featureHasFinished
Null HLRAddress or GsmScfAddress in config profile | Increment SendFailures stat Report featureFailedToExecute Report featureHasFinished
Exception sending SRI request to HLR | Increment SendFailures stat Report featureFailedToExecute Report featureHasFinished
OpenRefuse from HLR | Close dialog Increment SS7ProviderErrors or SS7UserErrors if sriConfig.failOnError report featureFailedToExecute Report featureHasFinished
Abort from HLR | Close dialog Increment SS7Aborts if sriConfig.failOnError report featureFailedToExecute Report featureHasFinished
Timeout waiting for HLR response | Close dialog Increment SS7Timeouts if sriConfig.failOnError report featureFailedToExecute Report featureHasFinished

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished
featureFailedToExecute | unclassified

#### Session State interface

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

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

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

### Configuration

The SRI For Basic Call Routing configuration includes:

Parameters | Type | Description
--- | --- | ---
SccpOriginatingAddress | SCCP address | Will be used as the TCAP Calling Party Address in dialogs initiated towards the HLR and MSC. May be null in which case the local SCCP address configured for the platform will be used. Example: `type=c7,ri=gt,digits=34607012345,nature=national,national=true`
InvokeTimeout | Long | SendingRoutingInformation invoke timeout in milliseconds (for example, 5000). A 0 value results in CGIN RA defaults being used.
Map3Supported | Boolean | if ‘true’ will use `locationInfoRetrievalContextv3-ac`, if ‘false’ `locationInfoRetrievalContext-v2-ac`
HLRAddress | SCCP address | HLR address for the SRI
GSMSCFAddress | AddressString | Return address for responses (e.g. Sentinel address)
PrePagingSupported | Boolean | When true sets the Pre_pagingSupported flag in the SRI
FailOnError | Boolean | When true the feature will respond on error with a featureFailedToExecute to the Sentinel core, when false the feature will continue without reporting error to the core.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SRIForBasicCallRoutingFeatureConfigProfileTable | Feature configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

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

## USSD Push Notification Feature

### Description

Feature name | USSDNotification
Applicable contexts | SS7 service
SAS Support | No * Diameter Service * SIP Service
Prerequisite features | Optional: Any feature which sets NotificationMessage Optional: Any feature which sets NotificationAddress

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

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

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

- Address in NotificationAddress session state variable (if set)

- Address in Subscriber session state variable

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
Sentinel?SelectionKey | com.?opencloud.?sentinel.?common.?Sentinel?SelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Increment SendFailures Return
NotificationMessage | String | Arbitrary text | The text content of the outgoing USSD notification | Increment SendFailures Return
NotificationAddress | String | MSISDN | The destination address of the outgoing USSD notification | Fall back to Subscriber session state field
Subscriber | String | MSISDN | The destination address of the outgoing USSD notification if NotificationAddress is null | Increment SendFailures Return

#### Outputs

This feature does not write to session state.

#### Error scenarios

Scenario | Handling
--- | ---
Missing configuration profile in USSDNotificationFeatureConfigProfileTable | Increment SendFailures
Null sessionstate NotificationMessage | Increment SendFailures
Null sessionstate NotificationAddress | Increment SendFailures
Could not create destination MSISDN from NotificationAddress | Increment SendFailures
Could not create SccpAddress from NotificationAddress | Increment SendFailures
USSD message encoding failed | Increment EncodingFailures
Failed to send unstructured SS notify request | Increment SendFailures
OpenRefuse from HLR | Increment HlrProviderErrors or HlrUserErrors
Abort from HLR Increment | HlrAborts
Timeout waiting for HLR response | Increment HlrTimeouts

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

The USSD Push Notification configuration includes:

Parameters | Type | Description
--- | --- | ---
SccpOriginatingAddress | SCCP address | Will be used as the TCAP Calling Party Address in dialogs initiated towards the HLR and MSC. May be null in which case the local SCCP address configured for the platform will be used. Example: `type=c7,?ri=gt,?digits=34607012345,?nature=national,?national=true`
InvokeTimeout | Long | UnstructuredSS_Notify invoke timeout in milliseconds (for example, 5000). A 0 value results in CGIN RA defaults being used.
UssdDataEncodingScheme | Byte | USSD data encoding scheme. Currently must be 15 (coding scheme must be 0x0f (0000 1111) GSM 7 bit language unspecified)
WaitForConfirmation | Boolean | true/false, when true will wait for the response from the HLR, if false will proceed with feature execution immediately

### Call flow

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

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

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

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

  - the response is received

  - a MAP error is reported

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

  - the dialog is aborted.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
USSD?Notification?Feature?Config?Profile?Table | Feature configuration | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

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

MAP SPEC | Digital cellular telecommunications system (Phase 2+); Mobile Application Part (MAP) specification (3GPP TS 09.02 version 5.17.0 Release 1996) | ETSI/3GPP | 2002-03 | ETSI

## CAMEL Features

Sentinel includes many features for CAMEL networks:

- Accept Protocol Feature— 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 Reorigination 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
SAS Support | No
Prerequisite features | None

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

The acceptable application contexts are:

- cap_v1_gsmSSF_to_gsmSCF-AC

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

- capssf_scfGenericAC (CAP3)

- cap3_sms_AC

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

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Runtime exception handled by feature runner

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
SessionType | com.opencloud.sentinel.common.SessionType | One of: call, sms | Session type determined from application context
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>:<network>:<session type>::`) | Updated selection key including session type determined from application context
Protocol | com.opencloud.sentinel.common.SentinelProtocol | One of: cap_v1, cap_v2, cap_v3, cap_v4, etsi_inap_cs1, map_rel4, call_control | Session protocol determined from application context

### Error scenarios

Scenario | Handling
--- | ---
Trigger not instance of DialogOpenRequestEvent | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
refuseDialog | User ACN not supported
featureCannotStart | Trigger event is not a DialogOpenRequestEvent
markSessionType | mark the session type (one of: call, sms, diametermediation, sipcall, unset) in session state
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## Call Barring Feature

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

### Description

Feature name | CallBarring
Applicable contexts | SS7 service
SAS Support | No
Prerequisite features | Voice Call Normalization Feature Classify call scenario feature

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 | CAP-DataTypes.InitialDPArg | InitialDP which triggered this session, from which the CalledPartyBCDNumber will be read | Report featureCannotStart, featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Barring will only be performed for mobile originating calls | Report featureCannotStart, featureHasFinished

#### Outputs

This feature does not write to session state.

### Error scenarios

Scenario | Handling
--- | ---
Trigger not instance of DialogOpenRequestEvent | Report featureCannotStart
Null sessionstate SentinelSelectionKey | Report featureCannotStart
InitialDP not CAP | Report featureCannotStart
Null sessionstate CallType | Report featureCannotStart
InitialDP does not contain a CalledPartyBCDNumber | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureCannotStart | SessionState SentinelSelectionKey is not set, protocol is not CAP, session type has not been set, or InitialDP does not contain a CalledPartyBCDNumber
releaseCallAndCloseDialog | call is barred
featureHasFinished | feature has finished

### Determining if a call is to be barred

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

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

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

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

    do not barr call

### Triggers and application contexts

Application Contexts:

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

- capssf_scfGenericAC (CAP3).

The InitialDP will be triggered on DP2 (Collected_Info).

### Typical call flow

- MSC ---- OpenRequest -→ Sentinel

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

- MSC ←-- OpenAccept --- Sentinel

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

### Configuration

The CallBarring feature configuration profile includes the following attributes:

Parameters | Type | Description
--- | --- | ---
ReleaseCause | Integer | Release cause to be set for barred calls

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

- The black list defines numbers to be barred.

- The white list defines numbers to be allowed and overrides the black list.

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

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
CallBarringFeatureConfigProfileTable | CallBarring feature configuration parameters | SentinelSelectionKey (for example, `OpenCloud::::`)

### Black and White List configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable | Address list configuration | ${SELECTIONKEY}:CallBarring:BlackList or ${SELECTIONKEY}:CallBarring:WhiteList
${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable Feature specific | Address List entry table | ${SELECTIONKEY}:CallBarring:BlackList:${ADDRESS}, ${SELECTIONKEY}:CallBarring:WhiteList:${ADDRESS}

### Provisioning interfaces

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

## Call Forwarding Detection Feature

### Description

Feature script name | CallForwardingDetection
Applicable contexts | SS7 service
SAS Support | No
Prerequisite Features | ClassifyCallScenario

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

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

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
InitialDPArg | com.opencloud.slee.resources.cgin.callcontrol.CCInitialDPArg | InitialDP which triggered this session. | If CAP1, the call is not eligible for forwarding detection. If CAP2 or higher, it is eligible. | Report featureCannotStart, featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call — if MobileTerminating, the call is eligible for call forwarding detection | Assume eligibility for call forwarding detection

#### Outputs

This feature does not write to session state.

### Feature responses

Response | Reason
--- | ---
doNotMonitorSession | if call is a MT call and hasGsm_ForwardingPending is set
doNotChargeSession | if call is a MT call and hasGsm_ForwardingPending is set
featureHasFinished | feature has finished

### Interaction with call forwarding supplementary service

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

- unconditional call forwarding or conditional call forwarding not

- call forwarding not reachable — MS switched off

- call forwarding not reachable — no paging response.

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

### OCS interface

No interaction with OCS from this feature except via MFC.

### Triggers and application contexts

Application Contexts:

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

- capssf_scfGenericAC (CAP3)

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

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

NOLDUS | CAMEL INTELLIGENT NETWORKS FOR THE GSM, GPRS AND UMTS NETWORK | Rogier Noldus | 2006 | John Wiley & Sons, Ltd

## Classify Call Scenario Feature

### Description

Feature name | ClassifyCallScenario
Applicable contexts | SS7 service
SAS Support | No
Prerequisite Features | None

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

### Session type

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

- MobileOriginating

- MobileTerminating

- MobileForwarded.

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

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

    Function DetermineSessionType(initialDP)

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

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

        IF NOT isOriginatingEventTypeBCSM
        THEN
            return MobileTerminating
        ENDIF

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

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

        return Unknown

### Roaming indicator

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

- Roaming

- NotRoaming.

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

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

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

| In the case of an MT call, the location information may be reported; but this is dependent on an HLR setting (MAP PSI during MT processing). For MO calls, the LocationInformation relates to the calling party. For the MT case, it relates to the called party.

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

### Service type

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

- Voice

- Video

- Data

- Fax

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

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

    Function DetermineServiceType(initialDP)

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

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

        ENDIF

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

        /* assume voice if no match */
        return VOICE

### Session State inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP1InitialDPArg | InitialDP which triggered this session, which will be analysed to classify the session | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | The type of this session
RoamingIndicator | Boolean | true if roaming, false if non-roaming or indeterminate | Indicates whether this call is roaming or non-roaming
ServiceType | com.opencloud.sentinel.common.ServiceType | One of: Voice, Data, Fax, Video, Unknown | Indicates the service type of this session

### Error scenarios

Scenario | Handling
--- | ---
Null sessionstate InitialDPArg | Report featureCannotStart
Null sessionstate SentinelSelectionKey | Report featureCannotStart
InitialDPArg not CAP | Report featureCannotStart
Session type could not be determined | featureFailedToExecute
Roaming status could not be determined | featureFailedToExecute
Service type could not be determined | featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureCannotStart InitialDP has not been set in session state, SessionState Sentinel | SelectionKey is not set or InitialDP is not CAP
featureFailedToExecute | unclassified error
featureHasFinished | feature has finished

### Configuration

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

BearerService configuration

Parameter | Type | Description
--- | --- | ---
BearerServiceCode | Integer | The bearer service value
BearerService | ServiceType | The ServiceType associated with the bearer service value

TeleService configuration

Parameter | Type | Description
--- | --- | ---
TeleServiceCode | Integer | The tele service value
TeleService | ServiceType | The ServiceType associated with the tele service value

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

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

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable | Address list configuration | ${SELECTIONKEY}:ClassifyCallScenario:HomeVLR
${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable Feature specific | Address List entry table | ${SELECTIONKEY}:ClassifyCallScenario:HomeVLR:${ADDRESS}
BearerServiceConfigProfileTable | BearerService configuration | SentinelSelectionKey + ':' + BearerServiceCode (for example, `OpenCloud:::::32`)
TeleServiceConfigProfileTable | TeleService configuration | SentinelSelectionKey + ':' + TeleServiceCode (for example, `OpenCloud:::::45`)

### Provisioning interfaces

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

## Closed User Group Feature

### Description

Feature script name | ClosedUserGroup
Applicable contexts | SS7 service
SAS Support | No
Prerequisite features | Voice Call Normalization Feature Subscriber Data Lookup Feature Optional: Feature setting ClosedUserGroupToUse (overrides ClosedUserGroupPreferred)

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: Incoming Calls Barred Within A CUG (ICB) — an access restriction that prevents a CUG member from receiving calls from other members of that group Outgoing Calls Barred Within A CUG (OCB) — an access restriction that prevents a CUG member from placing calls to other members of that group. Outgoing access

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

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

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

    CUG for call is CUGList[CUGToUse]

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

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

The number to check include prefix matches:

Call type | Number to check against CUG list
--- | ---
MOC | CalledPartyBCDNumber
MFC | CalledPartyNumber
MTC | CallingPartyNumber
NetworkInitiated(Callback) | Leg #4 Address
Emergency | N/A
MOSMS | DestinationSubscriberNumber

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

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

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

### Session State inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | InitialDPArg which triggered this session if it is a call | Set ClosedUserGroupCall session state field to false (indicating that this is not a closed user group call) Increment ClosedUserGroupSubscriberDataError Report featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Determines how to perform CUG analysis | Report featureCannotStart, featureHasFinished
SessionType | com.opencloud.sentinel.common.SessionType | One of: call, sms | For mobile originating sessions, distinguish call or sms CUG analysis | Report featureCannotStart, featureHasFinished
CAP3InitialDPSMSArg | com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg | CAP-SMS-ops-args.InitialDPSMSArg | InitialDPSMSArg which triggered this session if it is an sms | Set ClosedUserGroupCallsession state field to false (indicating that this is not a closed user group call) Increment ClosedUserGroupSubscriberDataError Report featureHasFinished
ClosedUserGroupEnabled | Boolean | true or false | Whether the subscriber has closed user group support enabled | Equivalent behaviour if null or false Increment ClosedUserGroupNotEnabled Set ClosedUserGroupCall session state field to false Report featureHasFinished
ClosedUserGroupList | String[] | Array of closed user group names | The closed user groups this subscriber belongs to | Increment ClosedUserGroupNotEnabled Set ClosedUserGroupCall session state field to false Report featureHasFinished
ClosedUserGroupPreferred | Integer | Any integer from 0 — ClosedUserGroupList.length | Indexes this subscriber’s preferred closed user group in their ClosedUserGroupList | Set ClosedUserGroupCall session state field to false Report featureCannotStart Increment ClosedUserGroupSubscriberDataError Report releaseCallAndCloseDialog, featureHasFinished
ClosedUserGroupToUse | Integer | Null or any integer from 0 — ClosedUserGroupList.length | Index which overrides ClosedUserGroupPreferred if set | Set ClosedUserGroupSelectedGroupName session state field to ClosedUserGroupPreferred

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
ClosedUserGroupCall | Boolean | true or false | Indicates whether this session is a closed user group call
ClosedUserGroupSelectedGroupName | String | May be null if ClosedUserGroupCall is false or CUG analysis failed | Name of the selected closed user group
RatingGroup | Long | May be null if ClosedUserGroupCall is false or CUG analysis failed | ID of the selected rating group

### Error scenarios

Scenario | Handling
--- | ---
Null sessionstate SentinelSelectionKey | Report featureCannotStart
Null sessionstate CallType | Report featureCannotStart
Null sessionstate SessionType | Report featureCannotStart
Null sessionstate ClosedUserGroupPreferred | Report featureCannotStart Increment ClosedUserGroupSubscriberDataError Report releaseCallAndCloseDialog
SessionState: CUG preferred id is invalid | Set sessionstate ClosedUserGroupCall to false Report featureCannotStart Increment ClosedUserGroupSubscriberDataError Report releaseCallAndCloseDialog
OtherPartyAddress could not be set successfully | Set sessionstate ClosedUserGroupCall to false Increment ClosedUserGroupSubscriberDataError
No CUG Group was selected | Set sessionstate ClosedUserGroupCall to false Increment NonClosedUserGroupCall Report releaseCallAndCloseDialog No CUG Profile was found for group

### Feature responses

Response | Reason
--- | ---
featureCannotStart | Invalid session state or configuration
releaseCallAndCloseDialog | CUG preferred ID is null, CUG preferred ID is invalid, no CUG Group was selected, call not allowed, or no CUG Profile was found for group
featureIssuedWarning | OtherPartyAddress has not been set or no CUG Group was selected
featureHasFinished | feature has finished

### Configuration

Each ClosedUserGroup’s configuration includes:

a general configuration profile (1 entry):

Parameter | Type | Description
--- | --- | ---
Name | String | Name of the the CUG
Description | String | Description of the CUG
RatingGroup | Long | Rating group to associate with the CUG
RestrictIncomingAccess | Boolean | Global per-subscriber override to restrict incoming calls from non-CUG members
RestrictOutgoingAccess | Boolean | Global per-subscriber override to restrict outgoing calls to non-CUG members

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

Parameter | Values
--- | ---
Number | Normalized number

The CUG number list is provisioned in international format:

- 6421678956

- 6492324856

- 64800123456 (0800 123456)

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

Parameter | Type | Values
--- | --- | ---
CUGEnabled | Boolean | true/false
CUGPreferred | Integer | CUG Index (for example, 0)
CUGList | String[] | List of CUG names (for example, `CUG1`,`CUG17`,`CUG_OPENCLOUD`)
CUGIncomingAccessAllowed | Boolean | true/false
CUGOutgoingAccessAllowed | Boolean | true/false

### OCS interface

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

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

- the CUG name (SessionState.CUGName)

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

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

### Triggers and application contexts

Application Contexts:

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

- capssf_scfGenericAC (CAP3)

The InitialDP will be triggered on DP2 (Collected_Info).

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
ClosedUserGroupCUGsProfileTable | CUG general configuration | ${SELECTIONKEY}:${CUGName} (for example, OpenCloud:Opencloud::::CUG1Profile)
${PLATFORMOPERATOR}_Sentinel_AddressLisConfigurationTable | Address list configuration | ${SELECTIONKEY}:ClosedUserGroup:${CUGName} (for example, OpenCloud:Opencloud::::ClosedUserGroup:CUG1Profile)
${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable | Feature specific Address List entry table | ${SELECTIONKEY}:ClosedUserGroup:${CUGName}:${ADDRESS} (for example, OpenCloud:Opencloud::::ClosedUserGroup:CUG1Profile:34600000001)

### Provisioning interfaces

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

## Connect and Close Feature

### Description

Feature name | ConnectAndClose
Applicable contexts | SS7 Service
SAS Support | No
Prerequisite Features | None

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

### Session State inputs and outputs

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

### Error scenarios

This feature has no error conditions.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## Continue and Close Feature

### Description

Feature name | ContinueAndClose
Applicable contexts | SS7 Service
SAS Support | No
Prerequisite Features | None

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

### Session State inputs and outputs

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

### Error scenarios

This feature has no error conditions.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## Do Not Monitor Session Feature

### Description

Feature name | DoNotMonitorSession
Applicable contexts | SS7 Service
SAS Support | No
Prerequisite Features | None

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

### Session State inputs and outputs

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

### Error scenarios

This feature has no error conditions.

### Feature responses

Response | Reason
--- | ---
doNotMonitorSession | intended behaviour
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## Emergency And Special Number Feature

### Description

Feature name | EmergencyAndSpecialNumber
Applicable contexts | SS7 service
SAS Support | No
Prerequisite Features | None

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

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

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

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

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

### Session State inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | InitialDP which triggered this session | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Call type will be overwritten as EmergencyCall if the call is to a special or emergency number, otherwise it will be left as is

### Error scenarios

Scenario | Handling
--- | ---
InitialDPArg is not CAP | Report featureCannotStart
Null sessionstate SentinelSelectionKey | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureCannotStart | Protocol is not CAP or SessionState SentinelSelectionKey is not set
continueAndCloseDialog | is a call to a special or emergency number
featureHasFinished | feature has finished

### Configuration

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

### Error handling

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

### Call flow

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

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable | Address list configuration | ${SELECTIONKEY}:EmergencyAndSpecialNumber:AddressList
${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable | Feature specific Address List entry table | ${SELECTIONKEY}:EmergencyAndSpecialNumber:AddressList:${Address}

### Provisioning interfaces

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

## Friends and Family Feature

### Description

Feature name | FriendsAndFamily
Applicable contexts | SS7 service
SAS Support | No * Diameter Mediation Service
Prerequisite features | Voice Call Normalization Feature Subscriber Data Lookup Feature

### Subscriber Data Lookup Feature

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

Call type | Number to check against FnF list
--- | ---
MOC | CalledPartyBCDNumber
MTC | CallingPartyNumber
MFC | CalledPartyNumber
NetworkInitiated(Callback) | Leg #4 Address
Emergency | N/A
MOSMS | DestinationSubscriberNumber

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

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

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

### Session State inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Runtime exception handled by the feature runner
FriendsAndFamilyEnabled | Boolean | true or false | Indicates whether Friends and Family is enabled for this subscriber | Runtime exception handled by the feature runner
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | InitialDP which triggered this session if it is a call — may be null if sms | If SessionType is call, Report featureCannotStart, featureHasFinished
InitialDPSMSArg | com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg | CAP-SMS-ops-args.InitialDPSMSArg | InitialDPSMS which triggered this session if it is an sms — may be null if call | If SessionType is sms, Report featureCannotStart, featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Calltype used for determining which party number is the other party address | Report featureCannotStart, featureHasFinished
SessionType | com.opencloud.sentinel.common.SessionType | One of: call, sms | Decide whether to inspect InitialDPSMSArg or InitialDPArg session state field when determining other party address | Runtime exception handled by the feature runner
FriendsAndFamilyList | String[] | Array of addresses | List of friends and family numbers | Set IsFriendsAndFamilyCall session state field to false Increment NonFriendsAndFamilyCall Report featureHasFinished

### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
IsFriendsAndFamilyCall | Boolean | true or false | Indicates whether this session is a friends and family call
RatingGroup | Long | May be null if IsFriendsAndFamilyCall is false or FNF analysis failed | ID of the selected rating group

### Error scenarios

Scenario | Handling
--- | ---
Sessionstate CallType is null | Report featureCannotStart
Other Party address could not be determined | Report featureIssuedWarning

### Feature responses

Response | Reason
--- | ---
featureCannotStart | Call type is not set in the session state
featureIssuedWarning | OtherPartyAddress has not been set
featureHasFinished | feature has finished

### OCS interface

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

### Configuration

Friends and Family feature general configuration parameters

Parameter | Type | Description
--- | --- | ---
LookupMethod | LookupTypeEnum | The method to be used to lookup the zone; one of: [profile,dbQuery]
RatingGroup | Long | General Rating Group for FnF

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

Parameter | Type | Values
--- | --- | ---
FriendsAndFamilyEnabled | Boolean | true when HomeZone feature is activated for this subscriber. See Friends and Family Feature.
FriendsAndFamilyList | String[] | list of numbers in normalized format (for example, 6421678956,6421345444,6421343333)

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

- 6421678956

- 6492324856

- 64800123456 (0800 123456)

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
FriendsAndFamilyFeatureConfigProfileTable | Selection of database implementation and rating group for the feature | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

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

## Home Zone Feature

### Description

Feature script name | HomeZone
Applicable contexts | SS7 service
SAS Support | No
Prerequisite features | Voice Call Normalization Feature Subscriber Data Lookup Feature

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

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

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

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
HomeZoneEnabled | Boolean | true or false | Whether the subscriber has home zone support enabled | Runtime exception handled by the feature runner
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | InitialDP which triggered this session if it is a call | Report featureCannotStart, featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Only mobile originating calls eligible for home zone | Report featureCannotStart, featureHasFinished
HomeZoneList | String[] | Array of zone names | The subscriber’s home zones | Set InHomeZone session state field to false Report featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
InHomeZone | Boolean | true or false | Indicates whether the subscriber is calling from their home zone

### Error scenarios

Scenario | Handling
--- | ---
Sessionstate | CallType is null Set Sessionstate InHomeZone to false Report featureCannotStart
Sessionstate InitialDPArg is null | Set Sessionstate InHomeZone to false Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureCannotStart | Call type is not set in the session state or InitialDP Arg is not set in the session state
featureHasFinished | feature has finished

### Configuration

Home Zone has a single general configuration parameter:

Parameter | Type | Description
--- | --- | ---
LookupMethod | LookupTypeEnum | The method to be used to lookup the zone; one of: [profile,dbQuery]

The storage of zone information is as follows:

Field | Type | Description
--- | --- | ---
Name | String | Name of the zone referenced by subscriber specific zone configuration
LocationTypes | LocationTypeEnum[] | Each entry to be be one of: [SAI, CGI or LAI]
LocationDescriptions | String[] | Location descriptions
MCC | String[] | MCC may have values between 100 and 999
MNC | String[] | MNC may have values between 10 and 999
LAC | Integer[] | LAC may have values between 1 and 65533 (FFFD) and 65535 (FFFF) (excludes 0 and 65534 (FFFE) for which no valid LAI exists)
CIOrSAC | Integer[] | CI may have values between 0 and 65535 (FFFF); SAC may have values between 0 and 65535 (FFFF)

Example Zones Table

ZoneName | LocationType | MCC | MNC | LAC | CIorSAC | Location description
--- | --- | --- | --- | --- | --- | ---
WgtnCBD | SAI | 530 | 01 | 11 | 22 | Vodafone NZ location
WgtnCBD | CGI | 530 | 01 | 01 | 01 | Vodafone NZ location
WgtnCBD | LAI | 530 | 01 | 01 |  | Vodafone NZ location
AkldCBD | LAI | 530 | 02 | 02 |  | Vodafone NZ location

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

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

Subscriber Zones Table

Field | Description
--- | ---
HomeZoneEnabled | true or false
HomeZoneList | List of home zones from the zones table for this subscriber

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
HomeZoneFeatureConfigProfileTable | Feature configuration. Currently for the selection of database implementation for the zones table | SentinelSelectionKey (for example, `OpenCloud::::`)
HomeZoneFeatureSqlProfileTable | SQL statement configuration | SentinelSelectionKey (for example, `OpenCloud::::`)
HomeZoneFeatureZonesProfileTable | Zone table if profiles selected | SentinelSelectionKey:ZoneName (for example, `OpenCloud::::WgtnCBD`)

### Database schemas

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

### Provisioning interfaces

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

## Play Announcement Feature

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

### Description

Feature name | PlayAnnouncement
Applicable contexts | SS7 service
SAS Support | No
Prerequisite features | SIP Subscriber Determination Feature Classify Call Scenario Feature A feature setting the `AnnouncementID` session state field

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

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

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

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

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

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

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

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

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
AnnouncementID | Integer | Any integer | ID of the announcement that is to be played | Increment MissingAnnouncementIDs Report featureHasFinished
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
CanRelayDialog | boolean | true or false | True if the assisting dialog has not been accepted yet | Not nullable
ResponderSccpAddress | com.opencloud.slee.resources.cgin.SccpAddress | SccpAddress | The SCCP Address to use as the responding address in the Open Response instead of the address provided by the stack, or null to leave the address unchanged | Use the address provided by the stack
LatestEventReportBCSM | com.opencloud.slee.resources.cgin.callcontrol.CCEventReportBCSMArg | CC-DataTypes.EventReportBCSMArg | Once the first event report has been received abandon is no longer required | Abandon will be armed
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call for determining from configuration which party address to lookup | Report featureCannotStart, featureHasFinished
LatestOcsAnswer | org.jainslee.resources.diameter.ro.types.CreditControlAnswer | Credit-Control-Answer | Announcements can reference variables based on latest CCA see Configuration | No action

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
CanRelayDialog | boolean | true or false | True if the assisting dialog has not been accepted yet

### Error scenarios

Scenario | Handling
--- | ---
Null CorrelationProvider | Increment ConfigurationErrors Report featureFailedToExecute
Sessionstate SentinelSelectionKey is null | Increment InputParameterErrors Report featureFailedToExecute
ACI not provided to the announcement feature | Increment InputParameterErrors Report featureFailedToExecute
No profile for selection key and AnnouncementID in AnnouncementProfileTable | Increment InputParameterErrors Report featureFailedToExecute
No profile for selection key in AnnouncementConfigProfileTable | Increment InputParameterErrors Report featureFailedToExecute
Null TariMillis in AnnouncementConfigProfile | Increment InputParameterErrors Report featureFailedToExecute
Exception invoking RequestReportBCSM on dialog | Increment ErrorsArmingAbandon Report featureFailedToExecute
Dialog object not provided to the announcement feature in the activity context interface | Increment InputParameterErrors Report featureFailedToExecute
Invalid type configured for the announcement ID (Should be tone, message or messages) | Increment InputParameterErrors Report featureFailedToExecute
TooManyInvokesException or ProtocolException whiling sending CTR or PlayAnnouncement | Increment ErrorsSendingCTRAndPA Report featureFailedToExecute
Received SS7 Abort | Increment Ss7Aborts If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input Report featureFailedToExecute
Received SS7 Error | Increment Ss7Errors If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input Report featureFailedToExecute
Received Abandon or Disconnect | If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input Report featureFailedToExecute
Tari expiry | If not useAssistingDialog, Increment TariExpiries If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureFailedToExecute | ss7Error
featureHasFinished | feature has finished

### Configuration

#### Announcement configuration

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

Parameter | Type | Description
--- | --- | ---
Description | String | Description of the announcement
Id | Integer | Announcement ID
AnnouncementType | AnnouncementTypeEnum | The announcement type, one of [message, tone, messages]
Value | Integer[] | Value of the message/tone ID (or IDs if 'announcementType' is 'messages') to be played.
ToneDuration | Integer | Duration of a tone announcement in seconds. Valid values: not set, 0 - 65535. Note: 0 means infinite duration. (This is an Integer4 ASN.1 type).
VariableCcaPaths | String[] | An array of CCA xpath expressions
VariableTypes | String[] | An array of type names. Each entry has to be one of [integer, number, date, time, price]
AllowDisconnect | Boolean | Determines if automatic disconnect of the gsmSRF is allowed when the announcement is complete.
ResetTssf | Boolean | Indicates whether or not a ResetTimer operation will be sent before the announcement is played to reset the Tssf timer.
InvokeTimeout | Long | Invoke timeout in milliseconds. In conjunction with the Tssf Reset Margin it is used to set the invoke timeout of the PlayAnnouncement operation and to determine the value to reset the Tssf timer to via the ResetTimer operation before the announcement begins (if ResetTssf is true). 1000-3600000 milliseconds.
CtrConfig | String | Reference to resource configuration to use with ConnectToResource
IvrAddressCalledPartyNumber | CalledPartyNumber | The IVR address is only required if the announcement mode is CONNECT. It is specified in called party number string format, which includes comma-separated name value pairs with names one of: address, nature, numberingPlan, routingToInternalNetworkNumber. See CalledPartyNumber for more information.

Example announcement table configuration:

ID | Description | Type | Value | ToneDuration | AllowDisconnect | InvokeTimeout | CtrConfig | VariableCcaPaths | VariableTypes
--- | --- | --- | --- | --- | --- | --- | --- | --- | ---
1 | Play message "You have insufficient credit to make this call" | message | 123 |  | N | 10000 | srf1 |  |
2 | Play tone | tone | 23 | 250 | N | 1000 |  |  |
3 | Play messages "You have insufficient credit to make this call", and "Call the topup line" | messages | 123,124 |  | N | 10000 |  |  |
4 | Play message with variable 1 assigned time granted | message | 34 |  | N | 10000 |  | `[/MultipleServices CreditControl` `[ServiceId = 0]` `/Granted-Service-Unit/CCTime]` | [integer]

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

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

### Resource config

Parameter | Type | Description
--- | --- | ---
Name | String | Name of this CtrConfig. It is used by the announcement configuration profile to reference this configuration.
ResourceAddressCalledPartyNumber | CalledPartyNumber | The resource address in called party number string format, which includes comma-separated name value pairs with names one of: address, nature, numberingPlan, routingToInternalNetworkNumber. See CalledPartyNumber for more information. Example resource configuration profile:
Name | ResourceAddress | srf1

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

### Announcement mode

The announcement mode determines how the announcement will be played:

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

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

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

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

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

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

### Address lists

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

Address List Name | Default | Search Mode | Description
--- | --- | --- | ---
OriginatingSccpAddressList | longest prefix match | Uses the the global title digits of the the incoming dialog’s CallingPartyAddress. | MscAddressList
longest prefix match | Uses the address string of the MSCAddress parameter of the incoming InitialDP or InitialDPSMS. | SubscriberAddressList | exact match
Uses the subscriber address for the session. | SubscriberImsiList | exact match | Uses the subscriber IMSI for the session.

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

### Sentinel selection key configuration

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

Parameter | Type | Description
--- | --- | ---
AnnouncementLists | AnnouncementList[] | A list of Address List names specifying which address lists to search for the announcement mode. The address lists will be searched in the order given in this list.
Default Mode | AnnouncementMode | The announcement mode to use if address list lookup fails to find an announcement mode. One of [INTERNAL, ETC_COMBINED, ETC_SEPARATE, CONNECT]
Assisting SSP IP Routing Address Generic Number | GenericNumber | Address of the Assisting MSC. Only required if using an ETC announcement mode.
Combined Mode SCF ID | String | The SCF ID of Sentinel to use in ETC_COMBINED mode. Only required if using an ETC_COMBINED announcement mode.
Separate Mode SCF ID | Byte[] | The SCF ID of Sentinel to use in ETC_SEPARATE mode. Only required if using an ETC_SEPARATE announcement mode.
Use Correlation Delimiter | Boolean | Flag indicating if a delimiter digit (hex 'b') should be used between the assisting MSC address and the SCF ID when using the ETC_COMBINED mode. Only relevant if using this mode.
Tssf Reset Margin | Integer | The number of seconds added to the announcement duration used to reset the Tssf timer using the ResetTimer operation during announcement playing. This is just a safety margin.
Tari Millis | Long | The Tari timer value in milliseconds

### Announcement playing signalling flows

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

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

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

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

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

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

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

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

### Error handling

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

- required configuration state may be missing

- required configuration parameters may be invalid

- operation errors sent by the initiating or assisting MSC may be encountered

In all error cases the feature returns the `featureFailedToExecute` result and exits. A feature script can test for this condition and react accordingly, for example the script could allow the call to continue regardless, or could release the call instead.

Examples of some error call flows:

SRR expected but not received:

    MSC <---- CTR ---- Sentinel
    MSC <---- PA(requestAnnouncementComplete=true) ---- Sentinel
    Invoke timeout
    MSC ----> PE(NO_LINKED_RESPONSE) ---> Sentinel

This is the standard case when requestAnnouncementComplete=false (that is, no SRR expected but we still get the provider error due to the protocol definition)

    MSC <---- CTR ---- Sentinel
    MSC <---- PA(requestAnnouncementComplete=n) ---- Sentinel
    Invoke timeout
    MSC ----> PE(NO_LINKED_RESPONSE) ---> Sentinel

Reject:

    MSC <---- CTR ---- Sentinel
    MSC <---- PA ---- Sentinel
    MSC ----> PE(REMOTE_REJECT) ---> Sentinel

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
AnnouncementProfileTable | Announcement configuration profiles | SentinelSelectionKey:id (for example, `OpenCloud::::15`)
AnnouncementResourceConfigProfileTable | ConnectToResource resource configuration | SentinelSelectionKey:ctrConfigName (for example, `OpenCloud::::srf1`)
AnnouncementConfigProfileTable | Additional resource configuration | SentinelSelectionKey:configName (for example, `OpenCloud::::config`)
${PLATFORMOPERATOR}PlayAnnouncementAddressListConfigurationTable | Address list configuration | ${SELECTIONKEY}:PlayAnnouncement:${AddressListName}
${PLATFORMOPERATOR}PlayAnnouncementAddressListEntryTable | Feature specific Address List entry table | ${SELECTIONKEY}:PlayAnnouncement:${AddressListName}:${ADDRESS}

### Provisioning interfaces

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

## Prefix and Suffix Analysis Feature

Sentinel has a set of configurable prefix and suffix lists, scoped by Sentinel selection key, which are used for number analysis.

### Description

Feature name | PrefixAndSuffixAnalysis
Applicable contexts | SS7 service
SAS Support | No * Diameter Mediation Service
Prerequisite features | Classify Call Scenario Feature

If a prefix or suffix is matched, the directive associated with the prefix is used.

The directives are: strip prefix/suffix or retain prefix/suffix, and set session parameter with configured value.

Where the directive is strip, the new called party number will be sent in a connect.

| Subsequent features may make additional changes to the called party number, so the final address sent in the connect will be dependent on those features.

Parameter | Description
--- | ---
Address | Prefix or suffix to match
Description |
ListId | ${SELECTIONKEY}:PrefixAndSuffixAnalysis::SpecialPrefixList ${SELECTIONKEY}:PrefixAndSuffixAnalysis:SpecialSuffixList
ParameterName | Session state field to set (for example, AnnouncementID). Field name is in Java identifier format, and follows the rules of Java identifiers (such as not being a Java keyword).
ParameterType | boolean, integer, long, string
ParameterValue | Value to write to session state. Must be formatted correctly for the value specified in the Parameter Type field
PrefixDirective | strip, retain

Example of prefix analysis configuration:

Prefix/suffix address | Directive | Session Parameter | Parameter Type | Parameter Value | Description
--- | --- | --- | --- | --- | ---
1234 | STRIP | CLI | String | SUPPRESS |
555 | STRIP | TARIFF | String | Cheap-International-Calling |
*591 | STRIP | PROFILE | Integer | 1 | Profile selection
*592 | STRIP | PROFILE | Integer | 2 | Profile selection
*593 | STRIP | PROFILE | Integer | 3 | Profile selection
*594 | STRIP | PROFILE | Integer | 4 | Profile selection
. | STRIP |  |  |  | Strip ST (end of pulsing) digit

Prefix may contain the following characters: 0-9, *, #, a, b, c, and . (period) . The expected decoding of a network address is specific to the number.

CalledPartyBCDNumber (MO calls):

Decoded character | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | * | # | a | b | c
Encoded hexadecimal | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | A | B | C | D | E

CalledPartyNumber (MF/MT calls):

Decoded character | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |  | * | # |  |  | .
Encoded hexadecimal | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | A | B | C | D | E | F

### Session State inputs and outputs

### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1. | CAP1InitialDPArg | CAP-DataTypes.InitialDPArg InitialDP which triggered this session | Report featureCannotStart, featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call for determining which party address to analyse | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
DestinationHasChanged | boolean | true or false | True if the IDP CdPA number address has been modified
ServiceType | com.opencloud.sentinel.common.ServiceType | One of: Voice, Data, Fax, Video, Unknown | Indicates the service type of this session
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | Updated InitialDPArg if destination has changed

Other session state fields see Description see Description This feature can update other session state fields according to configuration data when a prefix or suffix match is found

### Error scenarios

Scenario | Handling
--- | ---
Sessionstate SentinelSelectionKey is null | Report featureCannotStart
Sessionstate InitialDPArg is null | Report featureCannotStart
Sessionstate InitialDPArg is not CAP | Report featureCannotStart
Attempt to set non-existent SessionState parameter | Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureCannotStart | SessionState SentinelSelectionKey is not set, InitialDP Arg is not set in session state or InitialDP Arg is not an instance of CAP1InitialDPArg
featureFailedToExecute | Attempt to set non-existent SessionState parameter
featureHasFinished | feature has finished

### Multiple subscriber profile selection

The Prefix and Suffix Analysis feature supports multiple subscriber profile selection. See Noldus​[1] pp.219 5.2.9 Multiple Subscriber Profile.

MSP uses suffixes with the following digit string for the called party number, for dynamic profile selection: <Directory Number>59n # SEND , where n identifies the profile.

### Configuration

Prefix and Suffix Analysis uses Sentinel AddressLists for configuration data. See Address Lists for how to provide the configuration data.

### Configuration profile naming

Configuration Profile Table Name
Description
Profile Naming
${PLATFORMOPERATOR}_PrefixAndSuffixAnalysisFeature_AddressListConfigurationTable
Address list configuration
${SELECTIONKEY}:PrefixAndSuffixAnalysis:SpecialPrefiList or ${SELECTIONKEY}:PrefixAndSuffixAnalysis:SpecialSuffixList
${PLATFORMOPERATOR}_PrefixAndSuffixAnalysisFeature_AddressListEntryTable
Feature specific Address List entry table
${SELECTIONKEY}:PrefixAndSuffixAnalysis:SpecialPrefixList:${ADDRESS}

### Provisioning interfaces

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

NOLDUS | CAMEL | INTELLIGENT NETWORKS FOR THE GSM, GPRS AND UMTS NETWORK | Rogier Noldus | 2006 | John Wiley & Sons, Ltd

## Relay Dialog During Dialog Analysis Feature

### Description

Feature name | RelayDialogDuringDialogAnalysis
Applicable contexts | SS7 service
SAS Support | No
Typical feature execution points | DirectAccess_SessionStart, DirectAccess_SessionAccept
Prerequisite features | None

The Relay Dialog During Dialog Analysis feature requests Sentinel core to relay the received dialog to another network element.

### Session state inputs and outputs

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

### Feature responses

Response | Reason
--- | ---
relayDialog | the dialog should be relayed
featureHasFinished | feature has finished

### Call flow

    MSC ---- OpenRequest --> Sentinel
    MSC ----- InitialDP ---> Sentinel
                             Sentinel ---- OpenRequest --> New Network Element
                             Sentinel ----- InitialDP ---> New Network Element
    MSC <----------------- OpenAccept -------------------- New Network Element

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## Relay Dialog During Initial Trigger Analysis Feature

### Description

Feature name | RelayDialogDuringInitialTriggerAnalysis
Applicable contexts | SS7 service
SAS Support | No
Typical feature execution points | Any of the initial trigger feature execution points such as `DirectAccess_SessionPreCreditCheck`
Prerequisite features | None

This feature requests Sentinel core to relay the received dialog to another network element.

### Session state inputs and outputs

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

### Error scenarios

This feature has no error conditions.

### Feature responses

Response | Reason
--- | ---
relayDialog | the dialog should be relayed
featureHasFinished | feature has finished

### Call flow

The InitialDP may have been altered by features. For example, the calling and called party numbers in the InitialDP may have been normalised to an international format. The InitalDP relayed to the new network element will contain any such changes.

    MSC ---- OpenRequest --> Sentinel
    MSC ----- InitialDP ---> Sentinel
                             Sentinel ---- OpenRequest --> New Network Element
                             Sentinel ----- InitialDP' --> New Network Element
    MSC <----------------- OpenAccept -------------------- New Network Element

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## Release Call and Close Dialog Feature

### Description

Feature name | ReleaseCallAndCloseDialog
Applicable contexts | SS7 service
SAS Support | No
Prerequisite Features | Optional: Any feature setting the UserReleaseCause session state field

The Release Call And Close Dialog feature is a very simple feature that instructs Sentinel to release the call or SMS and close the dialog with the MSC. The following release cause codes are used by default:

- for calls:

  - when used during Initial Trigger handling: CLASS_1_CALL_REJECTED (21)

  - when used during End Session handling: CLASS_1_NORMAL_CALL_CLEARING (16)

- for SMSes:

  - if the latest OCS reply (if any) indicates an unknown user, then: UNKNOWN_SUBSCRIBER (30)

  - otherwise: RESERVED (11)

If a different release cause code is needed, another feature can be run before the Release Call And Close Dialog feature to set the `CCUserReleaseCause` or `CCUserReleaseCause` session state variable. If this session state variable is set, the Release Call And Close Dialog feature uses the cause value it specifies instead of the default. If the value set is not within the valid range of cause codes, the default cause code as specified above will be used instead.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
CCUserReleaseCause | com.opencloud.slee.resources.in.datatypes.cc.Cause | CAP-DataTypes.Cause | Release Cause to use for call control session release | Report featureCannotStart, featureHasFinished
SMSUserReleaseCause | com.opencloud.slee.resources.in.datatypes.sms.RPCause | CAP-DataTypes.RPCause | Release Cause to use for SMS session release | Report featureCannotStart, featureHasFinished
LatestOcsAnswer | org.jainslee.resources.diameter.ro.types.CreditControlAnswer | Credit-Control-Answer | For determining release cause code if the UserReleaseCause is not set | Use default call release cause CLASS1_NORMAL_CALL_CLEARING
SessionType | One of: call, sms | Session type of this call for choosing how to determine cause code from LatestOcsAnswer | Runtime exception handled by the feature runner |

#### Outputs

This feature does not modify session state.

### Error scenarios

This feature has no error conditions.

### Feature responses

Response | Reason
--- | ---
releaseCallAndCloseDialog | intended behaviour
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

## Roaming Default Call Forwarding Feature

### Description

Feature name | RoamingDefaultCallForwarding
Applicable contexts | SS7 service
SAS Support | No
Prerequisite features | Classify Call Scenario Feature SIP Subscriber Determination Feature Subscriber Data Lookup Feature

Roaming Default Call Forwarding (RDCF) applies only to roaming MTC calls. It defines roaming-specific forwarding addresses for ‘Busy’, ‘No reply’ cases to prevent tromboning of forwarded calls to numbers in the subscriber’s HPLMN.

The ‘Busy’, ‘No Reply’ cases are triggered when the event report BCSM returns busy or no answer.

RDCF issues a ‘Connect’ to forward the call. The following parameters are set in the ‘Connect’:

Parameter | Value | Description
--- | --- | ---
destinationRoutingAddress | SessionState.{CfBusy,CfNoReply} | Set based on the forwarding case from session state
redirectingPartyID | SessionState.Subscriber | Sets to the address of the served subscriber
originalCalledPartyID |
    IF initialdp.originalCalledPartyID not set THEN
        set to initialdp.calledPartyBCDNumber
    ELSE
        do not set
    ENDIF
redirectionInformation.redirectingReason | USER_BUSY / NO_REPLY / UNCONDITIONAL / MOBILE_UNREACHABLE | Set based on reason for the forward.
redirectionInformation.RedirectionCounter | Set to Maximum Value (configurable) | Setting the counter to the maximum value has the effect of suppressing call forwarding in the VMSC, and preventing tromboning.
redirectionInformation.redirecting | CALL_DIVERTED |
oCSIApplicable | true | Needed to ensure that MF call is triggered.

In the case of a subscriber configuration error which causes the feature to be unable to forward the call, the feature will allow the Sentinel core to continue without affecting the call, but will report the error to the core.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Runtime exception handled by feature runner
LatestEventReportBCSM | com..opencloud..slee..resources..cgin..callcontrol..CCEventReportBCSMArg | CCEventReportBCSMArg | Argument of the latest event report BCSM received | Report featureCannotStart, featureHasFinished
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg | CAP-DataTypes.InitialDPArg | InitialDP which triggered this session | Runtime exception handled by feature runner
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call for determining which party address to lookup | Call is considered not eligible for call forwarding — report featureHasFinished
RoamingIndicator | Boolean | true or false | Indicates whether this session is roaming | Runtime exception handled by feature runner
CfBusy | String | MSISDN | Call forwarding destination address when subscriber line is busy | If CfNoReply also null, increment FeatureNotEnabledForSubscriber If EventTypeBCSM is tCalledPartyBusy, increment NoForwardingNumber and do not forward call
CfNoReply | String | MSISDN | Call forwarding destination address when subscriber does not answer | If CfBusy also null, increment FeatureNotEnabledForSubscriber If EventTypeBCSM is tNoAnswer, increment NoForwardingNumber and do not forward call
Subscriber | String | MSISDN | For recording RedirectingPartyNumber in the connect arg if call forwarding is triggered | Runtime exception handled by feature runner

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
CCConnectArg | com.opencloud.slee.resources.cgin.cap_v2.CAP2ConnectArg | CAP-DataTypes.ConnectArg | The connect arg Sentinel will use when forwarding the call. Not updated if RDCF fails or is disabled.

### Error scenarios

Scenario | Handling
--- | ---
MappingException while mapping destination routing address to connect arg | Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureCannotStart | latestEventReportBCSM is not set or Initial DP Arg is missing the CdPA BCD number
featureFailedToExecute | Error while forwarding a roaming MT call
connectAndCloseDialog | successful attempt to forward the call
featureHasFinished | feature has finished

### Interaction with call-forwarding supplementary service

See ETSI TS 100 543/GSM 03.82 Call Forwarding (CF) supplementary services.

RDCF will suppress the call forwarding supplementary service for the subscriber (if configured) in the busy and no answer cases. Unconditional and not reachable cases which do not cause tromboning are not affected by this feature.

| Please see Call Forwarding Detection Feature for detection and handling of the early call forwarding case, where the idp is received and call forwarding is pending.

### OCS interface

No interaction with OCS from this feature except via MFC.

### Triggers and application contexts

Application Contexts:

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

- capssf_scfGenericAC (CAP3).

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

### Configuration

RDCF feature-wide configuration parameters

Parameter | Type | Description
--- | --- | ---
MaxRedirectionCounter | Integer | The maximum value for use in connect.redirectionInformation.RedirectionCounter

Subscriber RDCF Table

Parameter | Type
--- | ---
CfBusy | CalledPartyNumber
CfNoReply | CalledPartyNumber

The the RDCF list is provisioned in international format, such as:

- 6421678956

- 6492324856

- 64800123456 (0800 123456)

The subscriber forwarding numbers will be provisioned using a text format, such as that used for CalledPartyNumber; for example:

`address=641234567,NATURE=INTERNATIONAL,numberingplan=isdn,routingToInternalNetworkNumber=allowed`

The internal format used by Sentinel will be the binary encoding.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
RoamingDefaultCallForwardingFeatureConfigProfileTable | Configuration properties | SentinelSelectionKey (for example, `OpenCloud::::`)

### Provisioning interfaces

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

## Roaming Reorigination Feature

The Reorigination feature is used as a way of handling triggers from roaming subscribers on networks that use CAPv1, or networks that use CAPv2 or CAPv3 but are otherwise determined to be unsupported for direct call control from the VPLMN.

### Description

Feature name | Reorigination
Applicable contexts | SS7 service
SAS Support | No
Prerequisite Features | Classify Call Scenario Feature

The reorigination capability is needed when:

- Roaming partners are triggering calls with CAMELv1.

- Roaming partners are triggering calls with CAPv2, and cannot send the ERB(disconnect) in the same TCAP message as the ACR)(see CAMEL2 issue).

- The calling party number is lost in the ISUP signalling when traversing an international carrier. In this case Sentinel must store the calling party number and set it in the connect. As setting the calling party number is not supported in CAMEL, this capability requires INAP CS1, CS2, or a proprietary variant. See Noldus​[2] section 3.6.3 Short Number Dialling with CLI Guarantee pp.82. Currently not supported in Sentinel.

In these cases, the call is reoriginated to the HPLMN using a pool of special routing numbers. The reoriginated call is re-triggered from the HPLMN MSC.

The Reorigination feature should run at one of the pre credit check feature execution points for both the original `InitialDP` and the reoriginated `InitialDP`. The Reorigination feature uses the reorigination-correlation-ra to choose the special routing number, and to store data from the original `InitialDP` that should be correlated with the reoriginated `InitialDP`.

| See Correlation Resource Adaptor to understand how the reorigination-correlation-ra works and how it can be configured

| If the dialog should not be reoriginated, or represent a reoriginated dialog, then the Reorigination feature will silently end to allow subsequent features to process the `InitialDP`.

The two phases of roaming reorigination

- Reoriginating a session. The Reorigination feature analyses the `InitialDP` stored in session state to decide if it should be reoriginated. If the dialog should be reoriginated, then it chooses a free special routing address and routes the call to this special routing address. The reoriginated call may then be re-triggered from the HPLMN MSC

- Receiving a reoriginated trigger.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | InitialDP which triggered this session — CalledPartyBCDNumber may be used in identifying reoriginated calls and may be modified | Runtime exception to be handled by feature runner
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call | Call will not be reoriginated or identified as reoriginated
RoamingIndicator | Boolean | true or false | Indicates whether this is a roaming call | Reorigination will not be attempted

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | CalledPartyBCDNumber be restored or replaced if the call has or will be reoriginated
RoamingIndicator | Boolean | true or false | Will be set to true if this call is a reoriginated request, otherwise unchanged
CCConnectArg | com.opencloud.slee.resources.cgin.cap_v2.CAP2ConnectArg | CAP-DataTypes.ConnectArg | The connect arg Sentinel will use if the call is to be reoriginated — not modified otherwise

### Error scenarios

Scenario | Handling
--- | ---
Sessionstate SentinelSelectionKey is null | Report featureCannotStart
Invoked for a non CAP dialog | Report featureIssuedWarning
No available correlation entries | Report releaseCallAndCloseDialog
Could not find a mapper to build the ConnectArg | Report featureFailedToExecute
Error retrieving the correlated data to restore InitialDP | Report releaseCallAndCloseDialog

### Feature responses

Response | Reason
--- | ---
featureCannotStart SessionState | SentinelSelectionKey is not set
featureIssuedWarning | non CAP dialog
releaseCallAndCloseDialog | Error while restoring the original Called Party Address address, error while reoriginating: unsupported network, could not find a mapper to build the ConnectArg
connectAndCloseDialog | Attempt to trigger reorigination
featureHasFinished | feature has finished

Below are details of the two phases, followed by Call Flow, Configuration, Configuration Profile Naming, and Provisioning Interfaces.

### Phase one: reoriginating a session

Reoriginating a session includes these steps:

- Determining if a dialog should be reoriginated

- Processing a reoriginated session

#### Determining if a dialog should be reoriginated

The Reorigination feature analyses the `InitialDP` to determine if the dialog should be reoriginated. The Reorigination feature checks:

1. if the dialog is for originating treatment. The first `InitialDP` will be triggered on DP2 (Collected Info). Terminating and forwarded dialogs are not reoriginated.

2. if the application context is supported. Supported application contexts are:

   - cap_v1_gsmSSF_to_gsmSCF-AC

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

   - capssf_scfGenericAC (CAP3).

3. if the `InitialDP VLR address` is for a roaming party for which reorigination is supported. Roaming partners that do not support the `ERB(Disconnect)` + `ACH` guarantee are listed in a reorigination configuration table which includes the VLR addresses of the operator. The Reorigination service determines if the VLR address is present in the table, and if so triggers reorigination.

#### Processing a reoriginated session

If a session is to be reoriginated, the feature uses the Correlation RA to:

- get an ID that is used to route the call to

- associate some data with the correlation ID that can be used when the dialog is reoriginated.

The important steps are:

1. Create the address we will use to select an id-pool.

2. Create the data that we will associate with the correlation ID.

3. Get a new correlation entry (passing the address and correlation data).

4. Construct the outgoing connect arg.

Step one is achieved with a Mapper. The Reorigination feature looks for a mapper:

    // a mapper that takes an {{InitialDP}} and generates a String.
    final Mapper mapper = mapperLibrary.findMapper(selectionKey, initialDpArg.getClass(), String.class);

Sentinel includes a Mapper for this purpose —`CAPInitialDPToCorrelationIdPoolAddress`— that returns the MCC from location information in the InitialDP.

| An alternative mapper that uses a different method for choosing an address to choose the id-pool can be written using the Sentinel SDK.

Step two is achieved with a Mapper. The Reorigination feature looks for a mapper:

    // a mapper that takes an {{InitialDP}} and generates a {{byte\[\]}}.
    final Mapper mapper = mapperLibrary.findMapper(selectionKey, cap1IdpArg.getClass(), byte[].class);

Sentinel includes a Mapper for this purpose, (CAPInitialDPArgToCorrelationData), that:

- creates a new `CAP1InitialDPArg` object

- copies the called party bcd number to the new cap 1 `InitialDP`

- copies the bearer capability (if present) to the new cap 1 `InitialDP`

- copies the redirecting party ID (if present) to the new cap 1 `InitialDP`

- copies the redirection information (if present) to the new cap 1 `InitialDP`

- copies the location information (if present) to the new cap 1 `InitialDP`

- copies the extensions (if present) to the new cap 1 `InitialDP`

- uses CGIN persist factory to turn this `CAP1InitialDP → byte[]`.

| An alternative mapper that uses a different method for building the correlated data to be associated with the correlation ID can be written using the Sentinel SDK. Step four uses a configuration profile selected from the `ReoriginationConfigProfileTable` to construct a new DRA, and a Mapper from the trigger class (for example, Cap2InitialDPArg) to a ConnectArg, to map it to an outgoing connect arg.

### Phase two: receiving a reoriginated trigger

Receiving a reoriginated trigger includes these steps:

- Determining if a dialog has been reoriginated

- Processing a reoriginated trigger

- Determining service type in reoriginated dialogs

#### Determining if a dialog has been reoriginated

The reorigination feature analyses the `InitialDP` to determine whether the dialog is a reoriginated dialog; if:

1. The reoriginated InitialDP will be triggered on DP3 (Analyzed Info).

2. The application context is supported. Supported application contexts are:

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

   - capssf_scfGenericAC (CAP3).

3. The called party is a special routing number.

| See Correlation Resource Adaptor to understand how the Correlation resource adaptor works and how it can be queried to see if the called party is a special routing number.

#### Processing a reoriginated trigger

If this session corresponds is a reoriginated trigger:

- use the correlation ID (the called party number) to get the correlated data from the Correlation RA

- restore fields from the original `InitialDP` (that is stored in the correlation data) into the reoriginated InitialDP.

This is achieved with a mapper. The reorigination feature looks for a mapper:

    // a mapper that takes a {{byte\[\]}} and returns a {{CAP1InitialDPArg}}
    final Mapper mapper = mapperLibrary.findMapper(selectionKey, byte[].class, CAP1InitialDPArg.class);

Sentinel core bundles a mapper for this purpose (CorrelationDataToCAPInitialDP) that:

- uses CGIN persist factory to turn this byte[] into a `CAP1InitialDPArg` object

- copies the cap 1 `InitialDP` called party bcd number to the reoriginated `InitialDP`

- copies the cap 1 `InitialDP` bearer capability (if present) to the reoriginated `InitialDP`

- copies the cap 1 `InitialDP` redirecting party ID (if present) to the reoriginated `InitialDP`

- copies the cap 1 `InitialDP` redirection information (if present) to the reoriginated `InitialDP`

- copies the cap 1 `InitialDP` location information (if present) to the reoriginated `InitialDP`

- copies the cap 1 `InitialDP` extensions (if present) to the reoriginated `InitialDP`

- sets the `InitialDP` session state field with the updated reoriginated `InitialDP`.

| 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 reoriginated InitialDP should be thought of as the mirror to the mapper used in step two for processing the original InitialDP. If a custom method for choosing the data to associate with the correlation ID is built with the Sentinel SDK, then two new mappers are needed that: take an InitialDP and generate a byte[] take a byte[] and return a CAP1InitialDPArg.

#### Determining service type in reoriginated dialogs

The Classify Call Scenario Feature may not be able to correctly determine that a reoriginated dialog is roaming. To ensure that the roaming indicator is set correctly, the Reorigination service must set the service type to isRoaming.

### Call flow

### 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 | CalledPartyNumber.Nature | The address nature
NumberingPlan | CalledPartyNumber.NumberingPlan | The numbering plan of the address
RoutingToInternalNetworkNumber | CalledPartyNumber.RoutingToInternalNetworkNumber | either ALLOWED or NOT_ALLOWED

Address list configuration

A VLR address list table is maintained, for the service to identify roaming partners requiring reorigination. A VLR address entry is an extension of the standard Address list entry, the addition being a listing of the set of supported application contexts:

Parameter | Type | Description
--- | --- | ---
OriginatingContextNames | String[] | Array of context names: cap_v1_gsmSSF_to_gsmSCF_AC, cap_v2_gsmSSF_to_gsmSCF_AC, capssf_scfGenericAC

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
${PLATFORMOPERATOR}_Reorigination_AddressListConfigurationTable | Address list configuration | ${SELECTIONKEY}:Reorigination:VLRAddressList
${PLATFORMOPERATOR}_Reorigination_AddressListEntryProfileTable | Feature specific Address List entry table | ${SELECTIONKEY}:Reorigination:VLRAddressList:${ADDRESS}
ReoriginationConfigProfileTable | new DRA parameters | ${SELECTIONKEY} (for example, `OpenCloud::::`)
ReoriginationCorrelationIdPools | Sets of reorigination numbers | Arbitrary eg Pool-1, however must include at least one profile named DEFAULT
CorrelationConfigTable | reorigination-correlation-ra configuration | ReoriginationCorrelationConfigProfile — can be redefined in the reorigination-correlation-ra configuration properties

### Provisioning interfaces

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

## SMS Normalization Feature

### Description

Feature script name | SMSNormalization
Applicable contexts | SS7 service MO SMS
SAS Support | No
Prerequisite features | Prefix And Suffix Analysis— where required

Uses the Normalization Component component to normalize the:

- idp.CallingPartyNumber (MOSMS)

- idp.DestinationSubscriberNumber (MOSMS)

The idp in session state is updated. All features executed after this feature will access the normalized numbers when accessing the idp in session state.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
CAP3InitialDPSMSArg | com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg | CAP-DataTypes.InitialDPSMSArg | InitialDPSMS which triggered this session, to which address normalization will be applied | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
DestinationHasChanged | boolean | true or false | Set to true only if InitialDPSMS is modified as a result of address normalization
CAP3InitialDPSMSArg | com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg | CAP-DataTypes.InitialDPSMSArg | Updated only if InitialDPSMS is modified as a result of address normalization

### Error scenarios

Scenario | Handling
--- | ---
Sessionstate CAP3InitialDPSMSArg is | null Report featureCannotStart
Initial DP SMS Arg is missing the CallingPartyNumber address | Report featureCannotStart
Initial DP SMS Arg is missing the DestinationSubscriberNumber address | Report featureCannotStart
Exception during number normalization | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureCannotStart | InitialDP SMS Arg is not set in the session state or Initial DP SMS Arg is missing the CallingPartyNumber address
featureHasFinished | feature has finished

### Configuration

See Normalization Component.

### Configuration profile naming

See Normalization Component.

### Provisioning interfaces

See Normalization Component.

## SS7 Determine Network Operator Feature

### Description

Feature name | SS7DetermineNetworkOperator
Applicable contexts | SS7 service
SAS Support | No
Prerequisite features | None

The SS7 Determine Network Operator Feature sets the network operator element of the Sentinel selection key for use in the selection of:

- feature execution scripts

- mappers

- address lists.

The feature will set the Network Operator element of the Sentinel selection key, based on the value returned by the DetermineNetworkOperator function below.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data and updating network operator field | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>:<network>:::`) | Only updated if network operator is determined
OriginatingSccpAddress | com.opencloud.slee.resources.cgin.SccpAddress | SccpAddress | Set to triggering DialogOpenRequestEvent originating address
ResponderSccpAddress | com.opencloud.slee.resources.cgin.SccpAddress | SccpAddress | Set to an address configured in Determine Network Operator address list

### Error scenarios

Scenario | Handling
--- | ---
Trigger event not a DialogOpenRequestEvent | Report featureCannotStart
Sessionstate SentinelSelectionKey is null | Report featureCannotStart
Trigger is null | Report featureCannotStart
DestinationAddress in DialogOpenRequestEvent is null | Report featureCannotStart
Could not match DestinationAddress in SS7DetermineNetworkOperatorGlobalTitleAddress | Increment CouldNotDetermineNetworkOperator Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureCannotStart | Trigger event must be DialogOpenRequestEvent, SessionState SentinelSelectionKey is not set, unsupported trigger, destination SCCP address not present in DialogOpenRequestEvent or destination SCCP GT address does not match and no default available
featureHasFinished | feature has finished

### Selection

    Function DetermineNetworkOperator(destinationSccpAddress.GT)

        IF destinationSccpAddress.GT not available THEN
            return default network operator value
        ENDIF

        IF destinationSccpAddress.GT address found in network operator selection table THEN
            RETURN network operator value from the matched selection table record match
        ELSE
            RETURN default network operator value
        ENDIF

The use of the destinationSccpAddress GT information is dependent on the subscriber’s HPLMN network configuration. It is possible that some networks may not pass the GT information set in the subscriber’s o-CSI or t-CSI.

Here is an example of SCCP address routing which includes the GT information:

    application context: CAP-v2-gsmSSF-to-gsmSCF-AC
    CAP OpenService Type: request/indication bitmask=0x1
    CapOpenArg:
    {
        applicationContext: 0 4 0 0 1 0 50 1
        nextBlockOpCode: not present
        originatingAddress:
        {
            P=C7, NI=0, RI=PCSSN, GTI=0,
                  PC=5900, SSN=146
        }
        destinationAddress:
        {
            P=C7, NI=0, RI=PCSSN, GTI=4,
                  SSN=146, TT=0, NP=1 (isdn), ES=2 (even),
                  NAI=4 (international num), DIG=420603059300
        }
        gprsOriginatingReference: not present
        gprsDestinationReference: not present
        user information length: not present

    }

For subscribers who are configured for intra-PLMN only, it is possible that the CSI may contain a gsmSCP address containing only PC/SSN. In this case, the feature cannot operate, as no GT information will be available.

### Configuration

Network Operator Destination Global Title SCCP Address List Selection Table:

Parameter | Type | Example Values
--- | --- | ---
Address | GT Address | 642100000012
NetworkOperator | String | MVNO1

Example table:

Address | NetworkOperator
--- | ---
642100000001 | OpenCloud
642100000011 | OpenNet
642100000022 | CloudNet

The default network operator is stored in the Sentinel configuration table.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
${PLATFORMOPERATOR}_SS7DetermineNetworkOperator_AddressListConfigurationTable | Address list configuration | ${SELECTIONKEY}:SS7DetermineNetworkOperator:GlobalTitleAddress
${PLATFORMOPERATOR}_SS7DetermineNetworkOperator_AddressListEntryTable | Feature-specific Address List entry table | ${SELECTIONKEY}:SS7DetermineNetworkOperator:GlobalTitleAddress:${ADDRESS}
SentinelConfigurationTable | Sentinel configuration table (contains DefaultNetworkOperator) | SentinelConfiguration

### Provisioning interfaces

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

## SS7 Subscriber Determination Feature

### Description

Feature name | SubscriberDetermination
Applicable contexts | SS7 Service
SAS Support | No
Prerequisite features | Classify Call Scenario Feature

The Subscriber Determination Feature is used to determine the subscriber address, based on parameters from the InitialDP and session state.

For the prefix and exact match of MSISDNs, the following matching will be performed:

Call Type | Subscriber number
--- | ---
MOC (Voice, Video, Fax, Data) | initialDP.callingPartyNumber
MFC (Voice, Video, Fax, Data) | initialDP.redirectingPartyID
MTC (Voice, Video, Fax, Data) | initialDP.calledPartyNumber
MOSMS | initialDPSMS.callingPartyNumber

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | InitialDP which triggered this session | Fall back to CAP3InitialDPSMSArg
CAP3InitialDPSMArg | com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg | CAP-DataTypes.InitialDPSMSArg | InitialDPSMS which triggered this session, to which address normalization will be applied | Irrelevant if InitialDPArg set, otherwise report featureFailedToExecute, featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call | Report featureFailedToExecute, featureHasFinished
Subscriber | String | MSISDN | The subscriber for this session | Proceed with subscriber determination

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
Subscriber | String | MSISDN | The subscriber address identified for this session

### Error scenarios

Scenario | Handling
--- | ---
InitialDPArg and InitialDPSMSArg not present or do not contain subscriber address | Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureFailedToExecute | InitialDPArg and InitialDPSMSArg not present or do not contain subscriber address
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## SS7 Unconditional Reject Session Feature

### Description

Feature name | UnconditionalRejectSession
Applicable contexts | Diameter Mediation Service
SAS Support | No
Prerequisite features | None

Unconditionally refuses the dialog with refuse reason set to USER_NO_REASON_GIVEN.

### Session state inputs and outputs

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

### Error scenarios

This feature always succeeds.

### Feature responses

Response | Reason
--- | ---
refuseDialog | intended behaviour
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## Set User Release Cause From Latest Event Report Feature

### Description

Feature name | SetUserReleaseCauseFromLatestEventReport
Applicable contexts | SS7 service
SAS Support | No
Prerequisite features | None

The Set User Release Cause From Latest Event Report feature inspects the latest `EventReportBCSM` received by Sentinel and if possible sets the `UserReleaseCause` integer session state variable to a cause code value appropriate for that event report. This feature can then be followed by the Release Call and Close Dialog Feature to have that cause code included in the `ReleaseCall` operation sent to the MSC.

The `UserReleaseCause` session state variable is set depending on the `eventTypeBCSM` field of the latest `EventReportBCSM` argument:

- for Route Select Failure:

  - if the `EventReportBCSM` contains event-specific information, then the release cause is obtained from the event-specific information;

  - otherwise a default of CLASS0_NO_ROUTE_TO_DESTINATION (3) is used.

- for Called Party Busy:

  - if the `EventReportBCSM` contains event-specific information, then the release cause is obtained from the event-specific information;

  - otherwise a default of CLASS1_USER_BUSY (17) is used.

- for No Answer:

  - a default of CLASS1_NO_ANSWER (19) is used.

- for Disconnect

  - if the `EventReportBCSM` contains event-specific information, then the release cause is obtained from the event-specific information;

  - otherwise a default of CLASS1_NORMAL_CALL_CLEARING (16) is used.

For any other case, including the absence of an EventReportBCSM operation to inspect, the UserReleaseCause session state variable is left untouched.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
LatestEventReportBCSM | com.opencloud.slee.resources.cgin.callcontrol.CCEventReportBCSMArg | CC-DataTypes.EventReportBCSMArg | Latest event report | Do not set release cause report featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
UserReleaseCause | Integer | Any cause value, such as Cause.CauseValue.CLASS0_NO_ROUTE_TODESTINATION, Cause.CauseValue.CLASS1USER_BUSY, Cause.CauseValue.CLASS1_NO_ANSWER, Cause.CauseValue.CLASS1_NORMAL_CALL_CLEARING | The cause value extracted from the latest event report

### Error scenarios

This feature always succeeds.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## Short Code Feature

The Short Code feature is a pre-credit check feature early in the feature list (but always after the emergency number feature), to perform number translation on a set of short codes configured for the network.

### Description

Feature name | ShortCode
Applicable contexts | SS7 service
SAS Support | No
Prerequisite features | Classify Call Scenario Feature

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, <platform>::::) | For selecting configuration data | Report featureCannotStart, featureHasFinished
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg \ | CAP-DataTypes.InitialDPArg | InitialDP which triggered this session | Report featureCannotStart, featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | If short code matched and translation was successful
DestinationHasChanged | boolean | true or false | If short code matched and translation was successful

### Error scenarios

Scenario | Handling
Sessionstate SentinelSelectionKey is null | Report featureCannotStart
Sessionstate InitialDPArg is null | Report featureCannotStart
InitialDP Arg is not CAP | Report featureCannotStart
Sessionstate CallType is null | Report featureCannotStart
InitialDP missing CalledPartyBCDNumber address | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureCannotStart | SessionState SentinelSelectionKey is not set, InitialDP Arg is not set in session state, InitialDP Arg is not an instance of CAP1InitialDPArg, Session Type is not set in the session state or Initial DP Arg is missing the CdPA BCD number
featureHasFinished | feature has finished

### Configuration

Short Code feature configuration:

Parameters | Type | Description
--- | --- | ---
MinLength | Integer | Minimum short code length
MaxLength | Integer | Maximum short code length

Example configuration:

MinLength | MaxLength
3 | 3

Short Code address list configuration:

The ShortCode address list entry is an extension of the standard Address list entry, the addition being the 'translatedAddress' field which is used for number translation:

Parameter | Type | Description
--- | --- | ---
…​ | …​ | …​
TranslatedAddress | String | the value of the short code translated address (in international format)

Example configuration:

Address | TranslatedAddress
100 | 6422987654
200 | 6422123456

The shortCode address is a digit string which can contain any digits valid for the network.

TranslatedAddress is a digit string in international format.

The short code list applies to all subscribers scoped to Sentinel selection key.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
ShortCodeFeatureConfigProfileTable | Short code feature configuration | SentinelSelectionKey (for example, `OpenCloud::::`)
${PLATFORMOPERATOR}_ShortCode_AddressListConfigurationTable | Address list configuration | ${SELECTIONKEY}:ShortCode:AddressList
${PLATFORMOPERATOR}_ShortCode_AddressListEntryTable | Feature specific Address List entry table | ${SELECTIONKEY}:ShortCode:AddressList:${ADDRESS}

### Provisioning interfaces

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

## Validate InitialDP Feature

### Description

Feature name | ValidateInitialDP
Applicable contexts | SS7 service
SAS Support | No
Typical feature execution points | DirectAccess_SessionPreCreditCheck
Prerequisite features | Classify Call Scenario Feature

The Validate InitialDP feature performs validation checks to ensure that the InitialDP has sufficient parameters to be handled correctly by Sentinel.

If the InitialDP is not valid, then the Valdiate InitialDP feature returns either `continueAndClose` or `releaseAndClose` to the Sentinel core. The choices of response and release cause are configurable. In the absence of configuration data, the default behaviour is `releaseCallAndClose(Call-Rejected)`.

The validation performed includes:

- check that InitialDP is present in session state

- check that InitialDP is CAP

- check that CallingPartyNumber is present in the `InitialDP`

- if session type is mobile originating, check for presence of `CalledPartyBCDNumber`

- if session type is mobile terminating or mobile forwarded, check for presence of `CalledPartyNumber`.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data for ValidationFailedAction if InitialDP fails validation | Runtime exception handled by feature runner
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | InitialDPArg which triggered this session | Report featureCannotStart, featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call for determining which party numbers should be present in InitialDPArg | Report featureCannotStart, featureHasFinished

#### Outputs

This feature does not modify session state.

### Error scenarios

Scenario | Handling
--- | ---
Sessionstate InitialDPArg is null | Report featureCannotStart
InitialDPArg is not CAP | Report featureCannotStart
Sessionstate CallType is null | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureCannotStart | InitialDP is not set in session state, InitialDP is not CAP or Session Type is not set in the session state
releaseCallAndCloseDialog | Configured to release on invalid InitialDP
continueAndCloseDialog | Configured to continue on invalid InitialDP
featureHasFinished | feature has finished

### Configuration

The configuration allows two options on validation failure: releaseAndClose or continueAndClose. The release cause code may be configured.

Parameter | Type | Description
--- | --- | ---
Action | String | one of: releaseAndClose or continueAndClose
ReleaseCause | Integer | cause code

### Call flow

    MSC ----- OpenRequest ----> Sentinel
    MSC ------ InitialDP -----> Sentinel
    MSC <----- OpenAccept ----- Sentinel
    MSC <--- Release(cause) --- Sentinel

The release cause will be configurable (see cause values). The default will be a cause value of CLASS1_CALL_REJECTED.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
ValidateInitialDPFeatureConfigProfileTable | Configuration of behaviour on validation failure | SentinelSelectionKey (for example, `OpenCloud:OpenCloud:call::`)

### Provisioning interfaces

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

## Validate Third Party Call Request Feature SS7

### Description

Feature name | Validate3rdPartyCallRequest
Applicable contexts | SS7 service
SAS Support | No
Typical feature execution points | This feature should run early in `ThirdPartyAccess_SessionAccept`
Prerequisite Features | None

The Validate 3rd Party Call Request Feature checks the received HTTP request to see if it is well formed. The SS7 service accepts HTTP requests in the following format:

    http://<host>:<port>/sentinel-ss7?cgpa=642200001&cdpa=642200002

This feature checks for the presence of the cgpa and cdpa request parameters.

| The SS7 service only accepts the HTTP request for processing if the path contains sentinel-ss7

### Session state inputs and outputs

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

### Error scenarios

Scenario | Handling
--- | ---
IOException while retrieving HttpRequest content | Increment CouldNotProcessHttpRequest
Report | refuseDialog

### Feature responses

Response | Reason
--- | ---
refuseDialog | the request to set up a 3rd party call should be refused
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## Voice Call Normalization Feature

### Description

Feature script name | Normalization
Applicable contexts | SS7 service voice call
SAS Support | No
Prerequisite features | Prefix and Suffix Analysis— where required

Uses the Normalization Component component to normalize the:

- idp.CallingPartyNumber (MOC, MTC, MFC)

- idp.CalledPartyBCDNumber (MOC)

- idp.CalledPartyNumber (MTC, MFC)

The idp in session state is updated. All features executed after this feature will access the normalized numbers when accessing the idp in session state.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For configuring normalizer | Runtime exception handled by feature runner
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | InitialDPArg which triggered this session, to which address normalization will be applied | Report featureCannotStart, featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
InitialDPArg | com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg | CAP-DataTypes.InitialDPArg | Updated only if InitialDPArg is modified as a result of address normalization
DestinationHasChanged | boolean | true or false | Set to true only if InitialDPSMS is modified as a result of address normalization

### Error scenarios

Scenario | Handling
--- | ---
Sessionstate InitialDPArg is null | Report featureCannotStart
InitialDPArg is not CAP | Report featureCannotStart
Sessionstate CallType is null | Report featureCannotStart
Initial DP Arg is missing the CalledPartyNumber address | Report featureCannotStart
Initial DP Arg is missing the CalledPartyBCDNumber address | Report featureCannotStart
Initial DP Arg is missing the CallingPartyNumber address | Report featureCannotStart
Error during number normalization | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureCannotStart | InitialDP has not been set in session state, InitialDP is not CAP, Session type is not set in session state, error during number normalization or Initial DP Arg is missing a required CallingPartyNumber, CalledPartyNumber or CalledPartyBCDNumber address
featureHasFinished | feature has finished

### Configuration

See Normalization Component.

### Configuration profile naming

See Normalization Component.

### Provisioning interfaces

See Normalization Component.

## SIP Features

Sentinel includes many features for SIP networks, including:

- SIP System Features— features that make up most of the default Sentinel behaviour, and can be used in feature execution pre and post scripts

- SIP User Features— features that can be used in feature execution user scripts

These features provide the behaviour of a third party Registrar:

- 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
SAS Support | No
Prerequisite features | RegistrarDetermineNetworkOperator or PlatformOperatorIsNetworkOperator
Feature execution points | Pre SipRegistration_NetworkCheck

### Session state inputs and outputs

#### Inputs

Name | Format | Description
--- | --- | ---
SentinelSelectionKey `com.opencloud.sentinel.common.SentinelSelectionKey` | selection key for example, `<platform_operator>::::` | For selecting a mapper that maps third party REGISTER request to session state fields

#### Outputs

Name | Format | Description
--- | --- | ---
RouteHeaderMode `com.opencloud.sentinel.state.RouteHeaderMode` |  | One of: not_present (no mode parameter in the route header), mmtel (mmtel scenario), scc (scc scenario) or mmtel_scc (mixed, mmtel and scc scenario)
EncapsulatedRegisterRequest `javax.sip.message.Request` | A `Request` Java object | The 1st party REGISTER request
EncapsulatedRegisterResponse `javax.sip.message.Response` | A `Response` Java object | The 1st party REGISTER response
RejectRegisterRequest `boolean` |  | Set to true if the third party REGISTER request should be rejected.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | Feature has finished.
featureFailedToExecute | Feature encountered a fatal error and was unable to continue.

### Statistics

Statistic | When incremented
--- | ---
MappingFailureExtractingRegisterRequestAndResponse | There was a failure whilst parsing the 1st party REGISTER and response from the body of the third party REGISTER
FailedToStart | The feature fails to start.
IssuedWarning | The feature encounters a non-fatal error and alerts the core.
FailedDuringExecution | The feature encounters any fatal error and alerts the core.
TimedOut | The feature fails to complete execution within the allowable time frame.

## Extract Public and Private Identities

The `ExtractPublicAndPrivateIdentities` feature analyses the 1st party REGISTER request and response and stores public and private indentities in session state.

| This feature is a critical system feature. The Registrar cannot function without this feature executing successfully. See Sentinel SIP Feature Execution Points for more about running critical features.

### Details

Feature script name | ExtractPublicAndPrivateIdentities
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | ExtractEncapsulatedRegisterRequestAndResponse
Feature execution points | Pre SipRegistration_SessionCheck

### Session state inputs and outputs

#### Inputs

Name | Format | Description
--- | --- | ---
SentinelSelectionKey `com.opencloud.sentinel.common.SentinelSelectionKey` | selection key for example, `<platform_operator>::::` | For selecting a mapper that maps 1st party REGISTER and response to public and private ids in session state fields.
EncapsulatedRegisterRequest `javax.sip.message.Request` |  | The 1st party REGISTER request
EncapsulatedRegisterResponse `javax.sip.message.Response` |  | The 1st party REGISTER response

#### Outputs

Name | Format | Description
--- | --- | ---
CallId `String` | The value of the `Call-ID` header | The call id of the 1st party REGISTER request
PrivateId `String` | The username parameter of the `Authorization` header | The private id of the subscriber, taken from the 1st party REGISTER request
PublicIds `String[]` | The value of a `P-Associated-Uri` with surrounding `<` and `>` removed | Public ids of the subscriber, taken from `P-Associated-Uri` headers in the 1st party REGISTER response
RegisteredContact `String[]` | Array of Strings, where each element is value of one `Contact` header | All the `Contact` headers, from the 1st party REGISTER response
RegisteredContactUris `String[]` | Array of Strings, where each element is `URI` part of the address in one `Contact` header | The `URI`s of the address for each `Contact` header in 1st party REGISTER response
PubGruu `String` | A SIP URI, as a String | The public GRUU (Globally Routable User Agent) from the first `Contact` header in the 1st party REGISTER response (if present)
TempGruu `String` | A SIP URI, as a String | The temporary GRUU (Globally Routable User Agent) from the first `Contact` header in the 1st party REGISTER response (if present)
RejectRegisterRequest `boolean` |  | Set to true if the third party REGISTER request should be rejected.

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

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

- 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

The `AcceptRegisterRequest` feature creates and sends a `200 OK` SIP response on the SIP leg for the triggering REGISTER request.

### Details

Feature script name | AcceptRegisterRequest
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | None

### Feature responses

featureFailedToExecute() | If there is an error creating the 200 OK response, or if the calling SIP leg is not associated with a REGISTER request.
featureHasFinished() | Once the feature finishes

## Determine Public Identities

### Description

This feature checks and retrieves Public ID information for a registration.

### Prerequisite features

- DetermineRegistrationActionType

- FetchPreviousRegistrationData

### Session state inputs and outputs

#### Inputs

SentinelSelectionKey | A selection key with the platform operator, network operator, session type and plan-id set (such as OpenCloud:OpenCloud:eSRVCCRegistration:register:)
PreviousRegistrationData | A list of registration records including all preexisting, active registrations associated with the subscriber and call ID.
PublicIds | A list of public IDs that have already been extracted from encapsulated first-party registration data.

#### Outputs

PublicIds | The list of public IDs for the registration.

### Feature responses

rejectRegisterRequest() | If the list of public IDs for the registration is empty once the feature has completed its analysis.
featureHasFinished() | Once the feature has finished

### Statistics

DeterminePublicIdentities statistics are tracked by the DeterminePublicIdentities feature and can be found under the following parameter set:
SLEE-Usage ▶ sentinel.registrar service ID ▶ sentinel.registrar SBB ID ▶ DeterminePublicIdentities.

Name | Type | Description
--- | --- | ---
    Started
| Counter | Incremented when the feature runs.
    FailedToStart
| Counter | Incremented when Sentinel Registrar encounters an error while attempting to start the feature.
    IssuedWarning
| Counter | Incremented when a non-fatal problem is encountered and the feature and issues a warning.
    FailedDuringExecution
| Counter | Incremented when a fatal problem is encountered and the feature cannot execute correctly.
    TimedOut
| Counter | Incremented when the feature takes too long to complete and Sentinel Registrar aborts execution.
    RetrievedIdsFromPAssociatedUris
| Counter | Incremented when a mapper has already successfully retrieved the public identities from encapsulated data.
    RetrievedIdsFromPreviousRegistration
| Counter | Incremented when the feature is able to retrieve public identities from previous registration data.
    FailedToRetrieveIds
| Counter | Incremented when no public identities can be determined.

### Behaviour

This feature is responsible for ensuring that the public identities for the served user are present in session state. It is also responsible for refusing a `REGISTER` request when public identities cannot be determined.

Under normal circumstances the public identities are pulled into session state by extracting them from the P-Associated-URI header on the encapsulated first-party registration message within the third-party REGISTER request. This is done by a mapper prior to this feature running.

Initially this feature will check if the mapper was successful in extracting the public identities. If it was successful the feature will increment a statistic and complete execution with no further changes. If the mapper was unsuccessful, the feature will do one of the following:

1. If the `REGISTER` request is for de-registration and third-party registration data is currently stored in a Cassandra database, then the feature will attempt to retrieve public identities from the most recent active registration for the served user. If this is successful the feature will populate session state with the retrieved identities and complete execution. If it is unsuccessful the feature will reject the `REGISTER` request.

2. If the `REGISTER` request is for registration or re-registration, or third-party registration data is currently stored in the HSS; then the feature will immediately reject the `REGISTER` request.

## Determine Registration Action Type

This feature classifies a REGISTER request according its type (register, re-register, or de-register).

### Classifying a REGISTER request

The `DetermineRegistrationActionType` feature examines the Contact headers of the first-party REGISTER request received in the body of the third-party REGISTER request.

A register is present if for any contact header:

- the contact header expires parameter is present and is not zero

- the contact header expires parameter is not present, but the request expires header is present and is not zero

A de-register is present if for any contact header:

- the contact header expires parameter is present and zero

- the contact header address is a wildcard and the request expires header is present and zero

- the request expires header is present and zero and the contact header expires parameter is not present

The action that should be taken is based on the following table:

Table 1. Actions
register is present | de-register is present | have previous registration data | action
--- | --- | --- | ---
false | true | - | de-register
true | true | - | re-register
- | false | true | re-register
- | false | false | register

### Details

Feature script name | DetermineRegistrationActionType
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | RegistrarPlatformOperatorIsNetworkOperator or RegistrarDetermineNetworkOperator DetermineRegistrationSessionType FetchPreviousRegistrationData

### Session state inputs and outputs

#### Inputs

SentinelSelectionKey | A selection key with the platform operator, network operator and session type set (such as OpenCloud:OpenCloud:eSRVCCRegistration::)
EncapsulatedRegisterRequest | The first-party REGISTER request that was in the body of the third-party REGISTER request received by the registrar.
PreviousRegistrationData | A list of registration records including all pre-existing, active registrations associated with the subscriber and call ID.

#### Outputs

SentinelSelectionKey | A selection key with the platform operator, network operator, session type and plan-id set (such as OpenCloud:OpenCloud:eSRVCCRegistration:de-register:)
RejectRegisterRequest | Set to true, if the first-party REGISTER request could not be analysed. For example, if the REGISTER request has a Contact with a wildcard address, while its Expires header is absent, or not equal to zero

### Feature responses

featureHasfinished() | Once the feature has finished

## Determine Registration Session Type

This feature classifies a REGISTER request according to how it should be handled.

### Determining the Registration type

The `DetermineRegistrationSessionType` classifies the session as Regular3rdPartyRegistration.

### Details

Feature script name | DetermineRegistrationSessionType
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | RegistrarPlatformOperatorIsNetworkOperator or RegistrarDetermineNetworkOperator

### Session state inputs and outputs

#### Inputs

SentinelSelectionKey | A selection key with the platform operator and network operator set (such as OpenCloud:OpenCloud:::)
EncapsulatedRegisterRequest | The first-party REGISTER request that was in the body of the third-party REGISTER request received by the registrar

#### Outputs

SentinelSelectionKey | A selection key with the platform operator, network operator, and session type set (such as OpenCloud:OpenCloud:Regular3rdPartyRegistration::)

### Feature responses

featureCannotStart() | If the first-party REGISTER request does not contain a Feature-Caps header
featureHasfinished() | Once the feature has finished

### Statistics

Parameter | …​ incremented if …​
--- | ---
Regular3rdPartyRegistration | The session is a regular third-party registration scenario

## Determine Visited Network

This feature extracts a value from the p-visited-network-id header(s) that is to be included in registration data.

| The p-visited-network-id header is defined in http://www.ietf.org/rfc/rfc3455.txt The P-Visited-Network-ID header field is used to convey to the registrar or home proxy in the home network the identifier of a visited network. The identifier is a text string or token that is known by both the registrar or the home proxy at the home network and the proxies in the visited network.

This feature uses the value of the first p-visited-network-id header. If the value is a string then the " characters are removed.

### Details

Feature script name | DetermineVisitedNetwork
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | RegistrarPlatformOperatorIsNetworkOperator or RegistrarDetermineNetworkOperator

### Session state inputs and outputs

#### Inputs

SentinelSelectionKey | A selection key with the platform operator and network operator set (such as OpenCloud:OpenCloud:::)
EncapsulatedRegisterRequest | The first-party REGISTER request that was in the body of the third-party REGISTER request received by the registrar

#### Outputs

VisitedNetwork | The value of the visited network id the registrar should store in registration data related to the current REGISTER request

### Feature responses

featureHasfinished() | Once the feature has finished

## Fetch Previous Registration Data

This feature retrieves any pre-existing active registrations associated with the incoming `REGISTER` request, and places it in a session state field where it can be accessed and used by other features. It will ignore expired registrations.

### Details

Feature script name | FetchPreviousRegistrationData
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | RegistrarPlatformOperatorIsNetworkOperator or RegistrarDetermineNetworkOperator

### Session state inputs and outputs

#### Inputs

NetworkOperator | The network operator, used for looking up registration data.
CallId | The call ID for the registration, used for looking up registration data.
PublicIds | The public IDs for the subscriber, used for looking up registration data.

#### Outputs

PreviousRegistrationData | A list of registration records including all pre-existing, active registrations associated with the subscriber and call ID.

### Feature responses

featureHasfinished() | Once the feature has finished

## Registrar Determine Network Operator

:toclevels:4 :toc-title: On this page…​

This feature determines which network operator a REGISTER request is related to.

### Determining the network operator

This feature adopts three techniques to determine the network operator:

- Special header in the third-party REGISTER request

- Lookup the network operator in feature configuration data

- 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
SAS Support | No
Prerequisite features | None

### Session state inputs and outputs

#### Inputs

SentinelSelectionKey | A selection key with the platform operator set (such as `OpenCloud::::`)

#### Outputs

SentinelSelectionKey | A selection key with the platform operator and network operator set (such as `OpenCloud:HomeOneNet:::`)

### Mappers

This feature uses a mapper that conforms to:

Mapping | Mapper Execution Point
--- | ---
IncomingSipRequest.class → String.class | RegistrarMappingPoint.DetermineNetworkOperator

### Feature responses

featureFailedToExecute() | `FeatureError.Cause.invalidConfiguration`— Could not determine Network Operator, and no default is configured.
featureHasFinished() | Once the feature has finished execution.

### Statistics

Stats interface | DetermineNetworkOperatorStats
Parameter set to monitor | `SLEE-Usage.Services.ServiceID\[RegistrarStg:name=sentinel.registrar,vendor=OpenCloud,version=1.0].SbbID\[RegistrarStg:name=sentinel.registrar,vendor=OpenCloud,version=1.0].(default)`

Parameter | …​ incremented if …​
--- | ---
CouldNotDetermineNetworkOperator | If the network operator cannot be inferred by analysis of the REGISTER request and there is no platform-level default network operator configured.

### Error scenarios

Error | Scenario for error
--- | ---
This feature signals an error to the registrar core, and increments a statistic | If it could not determine network operator, and there is no platform-level default network operator configured

### Configuration

- A profile table called `SentinelRegistrarNetworkOperatorProfileTable`.

  Each profile in the table:

  Parameter | Type
  --- | ---
  LookupKey | java.lang.String
  NetworkOperator | java.lang.String

  For example:

    [Rhino@localhost (#3)] listprofileattributes SentinelRegistrarNetworkOperatorProfileTable home1.net
    LookupKey=home1.net
    NetworkOperator=HomeOneNet

- The default network operator, which is in the Sentinel configuration table.

### Provisioning interfaces

The feature is provisioned using the 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.

### Details

Feature script name | RegistrarPlatformOperatorIsNetworkOperator
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | None

### Session state inputs and outputs

Interface | SentinelRegistrarSessionState

#### Inputs

SentinelSelectionKey | A selection key with the platform operator set (such as `OpenCloud::::`).

#### Outputs

SentinelSelectionKey | A selection key with the network operator set to the value of the platform operator (such as `OpenCloud:OpenCloud:::`).

### Feature responses

This feature always succeeds and responds to the registrar core with `featureHasFinished()`.

## Reject REGISTER Request

The `RejectRegisterRequest` feature issues a SIP error response on the triggering REGISTER leg.

### Choosing the SIP error response code

The `RejectRegisterRequest` uses the `RejectRegisterResponseCode` session state field if it is set. Otherwise the error response code is derived from the `RouteHeaderMode` session state field in the following way:

`RouteHeaderMode` | SIP Error response code
--- | ---
`mmtel` | `SipResponse.SC_OK`
`scc` or `mmtel_scc` | `SipResponse.SC_REQUEST_TERMINATED`
`not_present` | `SipResponse.SC_REQUEST_TERMINATED`

### Details

Feature script name | RejectRegisterRequest
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | None

### Session state inputs and outputs

#### Inputs

Name | Format | Description
--- | --- | ---
RouteHeaderMode `com.opencloud.sentinel.state.RouteHeaderMode` |  | One of: not_present (no mode parameter in the route header), mmtel (mmtel scenario), scc (scc scenario) or mmtel_scc (mixed, mmtel and scc scenario)
RejectRegisterResponseCode `Integer` | An `Integer` Java object | The SIP error response code to use when rejecting the third party REGISTER request

### Feature responses

This feature always responds featureHasFinished().

## Remove Registration

This feature removes all third party registration-related state associated with the Registration from the persistent storage mechanism. It is similar to the Store Subscriber Data feature in the sense that it uses the same storage mechanisms.

This feature is intended for use upon De-Registration.

### Details

Feature script name | RemoveRegistration
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | RegistrarPlatformOperatorIsNetworkOperator or RegistrarDetermineNetworkOperator DetermineRegistrationSessionType DetermineRegistrationActionType

### Session state inputs and outputs

#### Inputs

SentinelSelectionKey | A selection key with the platform operator, network operator, session type, and plan-id set. The plan-id must be set to `de-register` (such as `OpenCloud:OpenCloud:ESRVCCRegistration:de-register:`)
CallId | The call-id associate with the activation session
PrivateId | The private-id of the UE

### Feature responses

featureFailedToExecute() | If the request made by the registrar core to remove registration information is rejected by the data store sub-system
featureHasFinished() | Once the feature finishes

## Schedule Reject REGISTER Request

The `ScheduleRejectRegisterRequest` feature sets the `RejectRegisterRequest` session state field to `true`. This session state field can be tested in feature execution scripts to decide what features should run (for example `RejectRegisterRequest`).

### Details

Feature script name | ScheduleRejectRegisterRequest
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | None

### Feature responses

featureHasFinished() | Once the feature finishes

## Store Subscriber Data

The feature stores third party registration data from session state fields into the configured Data Storage. This feature is intended for use upon Initial Registration and Re-Registration. It is an extensible feature that supports multiple storage models. The default storage model is:

- Cassandra storage

The property `SubscriberDataFacadeType` in the Registrar Configuration Table indicates the Data Storage to be used.

### Details

Feature script name | StoreSubscriberData
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | RegistrarPlatformOperatorIsNetworkOperator or RegistrarDetermineNetworkOperator DetermineVisitedNetwork DetermineRegistrationSessionType DetermineRegistrationActionType

### Session state inputs and outputs

#### Inputs

SentinelSelectionKey | A selection key with the platform operator, network operator, session type, and plan-id set. The plan-id must be set to `register` or `re-register` (such as `OpenCloud:OpenCloud:ESRVCCRegistration:register:`)
CallId | The call-id associate with the activation session
PrivateId | The private-id of the UE
PublicIds | The list of public IDs provided in the 3rd party registrar message
TemporaryGruu | The temporary Gruu provided in the 3rd party registrar message
Gruu | The Gruu provided in the 3rd party registrar message
CMSISDN | The CMSISDN fetched from HSS
MSRN | The MSRN fetched from HLR
VisitedNetwork | The visited network fetched from the sip message
STNSR | The Session Transfer Number for SRVCC
CurrentATUSTI | The ATU-STI configured for the SCC AS
AtcfMgmtUri | The ATCF Management URI from Feature-Caps header in the initial first-party REGISTER request
AtcfPathUri | The ATCF Path URI from Feature-Caps header in the initial first-party REGISTER request

### Feature responses

featureFailedToExecute() | If the request made by the registrar core to store registration information is rejected by the data store sub-system
featureHasFinished() | Once the feature finishes

## Write Registrar Audit CDR

The `WriteRegistrarAuditCdr` feature writes an audit Call Detail Record (CDR) that summarises the action taken on the triggered REGISTER request. The behaviour of the `WriteRegistrarAuditCdr` feature can be influenced by the platform level registrar configuration (Registrar Configuration Table). In particular:

Field Name | Description
--- | ---
WriteAuditCdr | This property is true if audit CDRs should be written. The default value is false.
AuditCdrPrivateIdFilter | A private-id for which an audit CDR should be written. This setting has the highest priority and over-rides 'WriteAuditCdr'. Values of null or "" are ignored. If the private-id that the registrar has extracted from the 1st party REGISTER request and response is equal to the value of `AuditCdrPrivateIdFilter` then an audit CDR is written.
CdrStreamName | The cdr stream where audit CDRs are written

If there is a failure of any kind the `WriteRegistrarAuditCdr` feature will attempt to write the CDR as a warning trace message and increment relevant statistics.

### Details

Feature script name | WriteRegistrarAuditCDR
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | None

### Feature responses

featureFailedToExecute() | If the CDR resource adaptor is not operational, there was a failure creating a Call Detail Record, or there was a failure to write the Call Detail Record.
featureHasFinished() | Once the feature finishes

### Statistics

Statistic | When incremented
--- | ---
MappingFailureCreatingCdr | There was a failure whilst creating the CDR
FailedToWriteCdr | Either the CDR resource adaptor was not operational, or there was a failure whilst writing the CDR.
FailedDuringExecution | The feature encounters any fatal error and alerts the core.

## SIP System Features

Sentinel includes many system features for SIP networks which handles default system behaviour. These features are run using system pre and post execution scripts, before and after the user features on the same execution point with the same triggering event.

- 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, and ends the call once the max duration is reached.

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

- AVP CDR Feature— Writes a Call Detail Record in AVP format when the session ends.

- SIP Do Not Charge Feature— Disables charging of the current session.

- Diameter Service Info Feature— Constructs `IMS-Information` and `PS-Information` AVPs for CDRs and Credit-Control-Requests.

- Determine Cause Code Feature— Determines the value to be used for the `Cause-Code` AVP in the `IMS-Information` AVP

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

- External Session Tracking— Creates and maintains records in the Rhino Session Ownership Facility for all SIP legs that have been flagged for tracking.

- Determine Session Replication—  Sets up triggers in the Sentinel SIP service, that cause session replication to begin at certain points in a call.

- Max Call Duration Feature— Monitors the call duration and terminate the call if the maximum time has exceeded. (DEPRECATED)

## Determine Session Replication

This feature reads configuration and sets up triggers in the Sentinel SIP service, that will cause session replication to begin at certain points in a call.

### Details

Feature Script Name | DetermineSessionReplication
Applicable Contexts | SIP service
Call-Type | All
Session Plan | All
Execution Point | SipAccess_SessionStart and SubscriptionStart (in system pre-scripts)
Network Operator Config | Yes
Subscriber Config | None
POJO or SBB | POJO
Feature FSMs | None
Feature Parameters | None
SAS Support | No
Prerequisite features | None

### Feature Statistics

`DetermineSessionReplication` statistics are tracked by the `sentinel.sip` SBB and can be found under the following parameter set:
SLEE-Usage → sentinel.sip service ID → sentinel.sip SBB ID → feature.DetermineSessionReplication

Name | Type | Description
--- | --- | ---
    Started
| Counter | Incremented when the feature is triggered.
    FailedToStart
| Counter | Incremented when the feature fails to start.
    FailedDuringExecution
| Counter | Incremented when the feature fails while executing.
    IssuedWarning
| Counter | Incremented when the feature issues a warning.
    TimedOut
| Counter | Incremented when the feature times out during execution.
    SessionReplicationDisabledForSession
| Counter | Incremented when the feature determines that replication will never be enabled for the current session.
    ArmedReplicationTriggerOnSubscriptionUASLegs
| Counter | Incremented when the feature sets up a replication trigger for subscription user-agent-server legs.
    ArmedReplicationTriggerOnSubscriptionUACLegs
| Counter | Incremented when the feature sets up a replication trigger for subscription user-agent-client legs.
    ArmedReplicationTriggerOnInviteUASLegs
| Counter | Incremented when the feature sets up a replication trigger for invite user-agent-server legs.
    ArmedReplicationTriggerOnInviteUACLegs
| Counter | Incremented when the feature sets up a replication trigger for invite user-agent-client legs.
    ImmediateSessionReplicationEnableTriggered
| Counter | Incremented when the feature immediately enables session replication for a session.

### Configuration

This feature reads configuration from the `SipSessionReplicationConfigProfileTable` profile table. Profiles in this table are named based on the Sentinel selection key that they should be applied to.

The profile specification for this table is `sentinel-sip-session-replication-profile`. Each profile in this table has four fields that are used to indicate the point in a call that session replication should begin. Each of the four fields corresponds to a different type of leg. The fields use Enums to define the points in the call that session replication can begin. There are two different Enum types, one for legs initiated by SIP `REFER` or `SUBSCRIBE` requests, and one for legs initiated by `INVITE` requests.

The four fields on the profiles are:

Field Name | Enum Type | Purpose
--- | --- | ---
    InviteUASLegReplicationTrigger
    InviteReplicationTrigger
| Determines the point in the signalling on a `INVITE` user-agent-server leg at which replication will be enabled.
    InviteUACLegReplicationTrigger
    InviteReplicationTrigger
| Determines the point in the signalling on a `INVITE` user-agent-client leg at which replication will be enabled.
    SubscriptionUASLegReplicationTrigger
    SubscriptionReplicationTrigger
| Determines the point in the signalling on a `SUBSCRIBE` or `REFER` user-agent-server leg at which replication will be enabled.
    SubscriptionUASLegReplicationTrigger
    SubscriptionReplicationTrigger
| Determines the point in the signalling on a `SUBSCRIBE` or `REFER` user-agent-client leg at which replication will be enabled.

The possible values for each of the two different Enum types are outlined below.

InviteReplicationTrigger Enum

Enum Value | Description
--- | ---
    DISABLED
| Replication is prevented for this leg. All upstream and downstream legs in the same session are also excluded from replication.
    NOOP
| No replication decision will be made by this leg, see partner trigger (UAC/UAS) for subsequent replication behaviour.
    INITIAL_REQUEST
| Replication will begin as soon an initial INVITE request is seen on a leg of this type.
    PROVISIONAL_RESPONSE
| Replication will begin as a 18x response for the initial INVITE request is seen on a leg of this type.
    RINGING_RESPONSE
| Replication will begin when a 180 response for the initial INVITE request is seen on a leg of this type.
    SUCCESS_RESPONSE
| Replication will begin when a 2xx response for the initial INVITE request is seen on a leg of this type.
    ACK
| Replication will begin when an ACK for a 2xx response for the initial INVITE request is seen on a leg of this type.

SubscriptionReplicationTrigger Enum

Enum Value | Description
--- | ---
    DISABLED
| Replication is prevented for this leg. All upstream and downstream legs in the same session are also excluded from replication.
    NOOP
| No replication decision will be made by this leg, see partner trigger (UAC/UAS) for subsequent replication behaviour.
    INITIAL_REQUEST
| Replication will begin as soon an initial SUBSCRIBE or REFER request is seen on a leg of this type.
    SUCCESS_RESPONSE
| Replication will begin when a 2xx response for the initial SUBSCRIBE or REFER request is seen on a leg of this type.

### Behaviour

This feature reads configuration data from the `SipSessionReplicationConfigProfileTable` profile table, and uses it to set up triggers in the SIP service that will initiate session replication. When reading from the profile table, the feature will select the profile that best matches the current Sentinel selection key.

The feature sets the triggers by setting special session state fields that are checked by the Sentinel SIP service when it hits key points in a call flow. If the service decides it has reached or passed the point in the call the the trigger corresponds to, it will instruct the Sentinel SIP Leg Manager to begin session tracking on all current and future legs (See External Session Tracking for details of how legs are tracked).

If all legs in a session are configured `NOOP` Rhino will initiate persistence automatically after the session reaches `maxPersistDeferredTransactionAge`.

If the feature is unable to find any suitable profile for the current session, it will not set any triggers. This effectively disables session replication for the session.

| If either UAC or UAS legs are set to `DISABLED`, a later execution point cannot then enable replication. IE. it is an error to set `InviteUACLegReplicationTrigger` to `DISABLED` and `InviteUASLegReplicationTrigger` to `ACK`

#### Special Handling for Initial Request Triggers

There is special handling in the feature for user-agent-server legs that have an `INITIAL_REQUEST` trigger. If `InviteUASLegReplicationTrigger` config is set to `INITIAL_REQUEST` and the feature was triggered on an `INVITE` request, or `SubscriptionUASLegReplicationTrigger` config is set to `INITIAL_REQUEST` and the feature was triggered on an `SUBSCRIBER` or `REFER` request, then the feature itself will immediately instruct the Leg Manager to begin session tracking, bypassing the need to wait for the service to do it.

#### Session Ownership Facility Availability

Before it attempts to read any configuration the feature will check whether the Rhino Session Ownership Facility is available on the node. If the feature determines that the session ownership facility is not available, it will skip loading config, and disable session replication for the session.

## External Session Tracking

This feature creates and maintains records in the Rhino Session Ownership Facility for all SIP legs that have been flagged for tracking.

### Details

Feature Script Name | ExternalSessionTracking
Applicable Contexts | SIP service
Call-Type | All
Session Plan | All
Execution Point | Most SipAccess, SipMidSession, Subscription, and EndSession system post-scripts
Network Operator Config | None
Subscriber Config | None
POJO or SBB | POJO
Feature FSMs | None
Feature Parameters | None
SAS Support | No
Prerequisite features | None

### Feature Statistics

`ExternalSessionTracking` statistics are tracked by the `sentinel.sip` SBB and can be found under the following parameter set:
SLEE-Usage → sentinel.sip service ID → sentinel.sip SBB ID → feature.ExternalSessionTracking

Name | Type | Description
--- | --- | ---
    Started
| Counter | Incremented when the feature is triggered.
    FailedToStart
| Counter | Incremented when the feature fails to start.
    FailedDuringExecution
| Counter | Incremented when the feature fails while executing.
    IssuedWarning
| Counter | Incremented when the feature issues a warning.
    TimedOut
| Counter | Incremented when the feature times out during execution.
    RequestedStore
| Counter | Incremented when the feature attempts to store a record in the session ownership facility.
    StoreSuccess
| Counter | Incremented when the Session Ownership Facility successfully stores a full record.
    StorePartialFailure
| Counter | Incremented when the Session Ownership Facility fails to store some parts of a record.
    StoreFailure
| Counter | Incremented when the Session Ownership Facility fails to store any parts of a record.
    RequestedDelete
| Counter | Incremented when the feature attempts to remove a record from the session ownership facility.
    DeleteSuccess
| Counter | Incremented when the Session Ownership Facility successfully deletes a full record.
    DeletePartialFailure
| Counter | Incremented when the Session Ownership Facility fails to delete some parts of a record.
    DeleteFailure
| Counter | Incremented when the Session Ownership Facility fails to delete any part a record.
    StartedSessionOwnershipActivity
| Counter | Incremented when the feature starts a new session ownership activity.
    EndedSessionOwnershipActivity
| Counter | Incremented when the feature ends its session ownership activity.
    FoundNewDialogIdThatRequiresTracking
| Counter | Incremented when the feature detects that a new leg needs to be tracked, or that an existing tracked leg’s dialog ID has changed.
    FoundDialogIdRequiringUpdate
| Counter | Incremented when the feature detects that a leg has new information that needs to be tracked on its session ownership record.
    FoundDialogIdDueForRefresh
| Counter | Incremented when the feature detects that a leg’s session ownership record is approaching its TTL expiration, and needs to be refreshed.
    ChangedOwnershipOfLeg
| Counter | Incremented when the feature changes the owner of a session (SIP Dialog) from one node to a different node.
    ChangedOwnershipOfCharging
| Counter | Incremented when the feature changes the owner of a Charging Instance (Ro Dialog) from one node to a different node.
    SuccessfulQueryTime
| Sample | Samples the time taken for a success response to be received from the session ownership facility for any given request.
    PartiallyFailedQueryTime
| Sample | Samples the time taken for a partial failure response to be received from the session ownership facility for any given request.
    FailedQueryTime
| Sample | Samples the time taken for a failure response to be received from the session ownership facility for any given request.

### Behaviour

This feature monitors all legs in a session, regularly checking if any of the legs require a session ownership record, and if so, what information should be stored in that record. The feature maintains its own list of which legs currently have records in the session ownership facility, and when those records were last updated.

The exact behaviour of the feature differs based on how it is invoked:

- If the feature is invoked at the `SipEndSession` feature execution point, it will execute End Session Clean-Up behaviour.

- If it is invoked at any other feature execution point, it will execute Leg Tracking behaviour, followed by Charging Instance Tracking behaviour.

- If the feature is invoked with a `SessionOwnershipWriteResultEvent` via the Session Ownership Event Handler, it will execute Result Processing behaviour.

#### Session Ownership Records for protocol dialogs

Session ownership records are used to track information about specific sessions across multiple Rhino nodes. Their main purpose it to indicate which node is currently responsible for processing a session, but they can also be used for other information that Sentinel features might need to keep track of across nodes. They are stored the in Rhino Session Ownership Facility.

Sentinel SIP has the capability to maintain zero or one session ownership records for a SIP leg, and zero or one session ownership records for an Ro Dialog. Session ownership records are not maintained for all legs at all times, instead individual legs can be flagged for tracking in the session ownership facility. When that flag is seen by this feature, it will create a session ownership record for the leg. The flag can be set by the Sentinel SIP service when session replication is triggered, or by user features that need a leg to be tracked for their own purposes.

If the Sentinel Session has an Ro dialog, and at least one SIP leg is tracked, then the Ro session is tracked.

All protocol dialog session ownership records created, or updated by this feature are linked to the Sentinel Session’s Convergence Name Session Ownership Record. This ensures that after a fail-over, any simultaneous signalling will resolve to a single node.

##### Fields on a SIP Dialog Session Ownership Record

Certain fields on the Sentinel SIP `Leg` API are used to populate associated fields on a session ownership record. The following table outlines the relationship between data stored using the `Leg` API, and data stored on a session ownership record.

Session Ownership Record Field | Corresponding Leg API Getter | Corresponding Leg API Setter | Notes
--- | --- | --- | ---
PrimaryKey |
    getDialogID().toTrackingKey()
    N/A
| The primary key cannot be modified and is always based on the SIP Dialog ID associated with the leg.
OwnerURI |
    getOwner()
    setOwner()
| While the owner can be modified by other features, it should generally be left to this feature to set it.
AdditionalKeys |
    getAdditionalTrackingKeys()
    setAdditionalTrackingKeys()
| -
Attributes |
    getAdditionalTrackedAttributes()
    setAdditionalTrackedAttributes()
| -

The dialog ID of a leg is used as the primary key for the session ownership record. This means that if the dialog ID changes (e.g. when the dialog is confirmed by the remote party) a new record is created and the old one is deleted.

There are a few other SIP `Leg` API calls that relate to Session Ownership Records: - `setTrackingEnabled()` and `isTrackingEnabled()` are used set and read the flag that determines whether a session ownership record will be created for a leg. - `setWaitForTrackingResultEnabled() and `isWaitForTrackingResultEnabled()` are used to set and read a flag that affects how this feature manages asynchronous queries to the session ownership facility (see below). - `getLastTrackingDataChangeTime()` provides the timestamp of the last time that a call to any of: `setTrackingEnabled()`, `setOwner()`, `setAdditionalTrackingKeys()`, or `setAdditionalTrackedAttributes()` on the `Leg` API actually resulted in a meaningful change in the leg’s tracked state.

##### Fields on a Ro Dialog Session Ownership Record

Certain fields on the Sentinel SIP `ChargingInstance` API are used to populate associated fields on a session ownership record. The following table outlines the relationship between data stored using the `ChargingInstance` API, and data stored on a session ownership record.

Session Ownership Record Field | Corresponding ChargingInstance API Getter | Corresponding CharingInstance API Setter | Notes
--- | --- | --- | ---
PrimaryKey |
    getTrackingKey()
    N/A
| The primary key cannot be modified and always includes the Ro session identifer.
OwnerURI |
    getOwner()
    setOwner()
| While the owner can be modified by other features, it should generally be left to this feature to set it.

#### Leg Tracking

When the feature is invoked to do standard tracking behaviour, it will get the set of current legs from the leg manager and iterate over it. For each leg in the set, the feature will go through the following steps:

1. Check if the leg is flagged for tracking.

   - If it is not it will skip the remaining steps and move on to the next leg.

   - If it is flagged for tracking, the feature will move on to the next step.

2. Check if there is already a session ownership record stored under the leg’s Dialog ID.

   - If not, the feature will create a new record and write it into the session ownership facility. The remaining steps will then be skipped and the feature will move on to the next leg.

   - If so, it will move on to the next step.

3. Check if the owner node in the record matches the node currently executing the feature.

   - If not, a fail-over has occurred and the feature will take ownership of the leg (using `Leg.setOwner()`), and write an updated record into the session ownership facility (indicating that the owning node is the currently executing node). Then skip the remaining steps and move on to the next leg.

4. Check when the tracked data on the leg was last modified against the last time that the session ownership record was updated.

   - If the leg’s tracked data has been modified since the last time the session ownership record was updated, then the feature will create and write an updated record into the session ownership facility. It will then skip the remaining step and move on to the next leg.

5. Check whether the record’s TTL could expire before the feature is next invoked.

   - If so, then the existing record will be rewritten into the session ownership facility with a refreshed TTL.

   - Otherwise the feature will move on to the next leg.

After processing all of the legs, the feature will look for any records it has stored under Dialog IDs that no longer correspond to any leg that has tracking enabled. If it finds any such records, it will delete them from the facility.

All store and delete requests sent to the session ownership facility are executed asynchronously. The value of `isWaitForTrackingResultEnabled()` on the Leg API will affect the feature’s behaviour while it waits for the result for requests relating to that leg’s session ownership record. If any leg that has an outstanding store request to session ownership facility returns true for that API call, the feature will enter a `featureWaiting` state while it has nothing to do. This will prevent the session plan advancing to the next feature while the session ownership request is in progress. This is useful if further down the session plan, there is a feature that requires the session ownership record to be in place. If all legs with outstanding requests return false, then the feature will enter the `featureHasFinished` state while it waits, and session processing will continue in the mean time. The feature will not normally enter the `featureWaiting` state for delete requests.

This means that the feature can block further SIP signalling progress until a write has either succeeded, failed or timed out on a per-leg basis. There are several application specific use-cases where the database state (behind the session ownership facility) must be visible before further SIP signalling proceeds.

#### Charging Instance Tracking

When the feature is invoked to do standard tracking behaviour, it first checks if any SIP legs are tracked and if so it checks if a Charging instance exists and is not in the Final state. This essentially means that if Diameter Ro charging is in-use, and Session Replication is enabled, then the Ro session is tracked.

The feature goes through the following steps to determine if the Charging Instance (Ro Session) should be tracked:

1. Check if there is already a session ownership record stored under the Ro Dialog’s tracking key (this is a value that includes the Ro session identifier)

   - If not, the feature will create a new record and write it into the session ownership facility, and further steps are skipped

2. Check if the owning node in the record matches the node currently executing the feature.

   - If not, a fail-over has occurred, and the feature writes an updated record indicating that the owning node is the currently executing node. Further steps are skipped.

3. Check when the tracked data on the Charging Instance was last modified against the last time that the session ownership record was updated. If an update is needed the feature updates the record in the session ownership facility and skips the remaining steps.

4. Check whether the record’s TTL could expire before the feature is next invoked. If so the existing record is rewritten into the session ownership facility with a refreshed TTL.

All store and delete requests sent to the session ownership facility are executed asynchronously. The feature does not enter a waiting state for a Charging Instance’s session tracking write response (success, failure or timeout).

#### Result Processing

When a result is received from the session ownership facility, the feature simply records statistics and logs messages based on whether the result is successful, partially successful, or unsuccessful. After processing the result, the feature will decide to enter a `featureWaiting` or `featureHasFinished` state based on the same criteria used in Leg Tracking behaviour.

#### End Session Clean-Up

When the feature is triggered at session end, it create delete requests for all remaining session ownership records associated with the session. While under normal circumstances, the feature would not enter the `featureWaiting` state for delete requests, during end session behaviour the feature will keep going into the `featureWaiting` state until ALL outstanding requests are answered. This prevents to session from ending until all records have been handled.

## AVP CDR Feature

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

`SipAvpCdr` runs once when a session is ending and creates a CDR based on information gathered from session state, and then writes it out using the `cdr-ra`.

| By default, Sentinel runs `SipAvpCdr` as the very last feature in the `post` SIP end session feature execution script. For example:
    featurescript PostEndSession {
        run DetermineCauseCode
        run DiameterServiceInfo
        run SipAvpCdr
    }

### Details

Feature script name | SipAvpCdr
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | None, but information from various features is used if available

### Session state inputs and outputs

#### Inputs

If any of these fields are unset the feature will skip writing them to the CDR file.

Name | Type | Description | Where set
--- | --- | --- | ---
CalledPartyAddress | String | The address of the called party | CallPartiesAddressDetermination feature
CallId | String | The unique ID of the call | DiameterServiceInfo feature
CallingPartyAddress | String | The address of the calling party | CallPartiesAddressDetermination feature
CallType | Enumerated | The type of the call. One of `MobileOriginating`, `MobileTerminating`, `MobileForwarded`, `NetworkInitiated`, or `EmergencyCall` | DetermineCallType feature, SipThirdPartyHttpTrigger feature
ChargingResult | int | The result code of the Diameter session | Sentinel SIP service
DiameterServiceContextId | String | The Diameter context ID of the relevant service | AcceptSip feature, SipThirdPartyHttpTrigger feature
EndSessionCause | Integer | The end session cause code | LegManager
EventId | String | For `SUBSCRIBE` and `NOTIFY` events, the main value and `id` parameter of the `Event` header. For `REFER` events, the string `refer` and the sequence number. | DiameterServiceInfo feature
ImsInformation | org.jainslee.resources.diameter .ro.types.vcb0.ImsInformation | The IMS-Information Diameter AVP | DiameterServiceInfo feature
LatestOcsAnswer | org.jainslee.resources.diameter .ro.types.vcb0.CreditControlAnswer | The latest OCS response message | Sentinel SIP service
PlayedAnnouncementIDs | int[] | IDs of the played announcements | SipPlayAnnouncement feature, SipMidCallPlayAnnouncement feature
OcsSessionIds | String[] | An array of all the OCS session IDs for the call | Various features
OcsSessionTerminationCause | Integer | The OCS session termination cause | Sentinel SIP service
SentinelSelectionKey | com.opencloud.sentinel .common.SentinelSelectionKey | The selection key (for example, `<platform>::::`) for selecting configuration data | Various features
SessionEnded | long | The date and time when the session ended |
SessionEstablished | long | The date and time when the session was established |
SessionInitiated | long | The date and time when the session was initiated | Sentinel SIP service
SipServiceType | Enumerated | The type of service Sentinel is processing. One of `Message`, `Subscription`, `SipCall`, or `Unknown`. | AcceptSip feature
Subscriber | String | The subscriber associated with the session | SipSubscriberDetermination feature

### Statistics

Name | Description
--- | ---
CDRWritten | Number of times a CDR was successfully written
CDRnotWritten | Number of times a CDR was not successfuly written

### Functionality

This features uses the information from the session state fields mentioned above and constructs a protobuf message out of it for output. See AVP CDR Format for the format of these messages.

Also see Charging Information for general information about the contents of CDRs and CCRs.

| This feature only supports writing binary CDRs. If the `cdr-ra` is configured to write text CDRs the feature will fail to execute.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

## B2BUA ECUR Features

The B2BUA ECUR charging features define event charging with unit reservation behaviour for Sentinel SIP as a B2BUA.

### Details

Feature script name | B2BUAEcurpre-feature, B2BUAEcurpost-feature
Applicable contexts | SIP service
SAS Support | Yes
Prerequisite features | B2BUA
Feature execution points | Pre SipAccess_ChargingReauth SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_OCSFailurePostCC SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReachedPostCC SipMidSession_OCSFailurePostCC SipMidSession_ChargingReauth SubscriptionSubscriberCheck SubscriptionSipRequest SubscriptionSipResponse CreditFinalised SipTransaction_Response SipTransaction_SubscriberCheck Post SipAccess_ChargingReauth SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_OCSFailurePostCC SipAccess_PartyResponse SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReachedPostCC SipMidSession_OCSFailurePostCC SipMidSession_ChargingReauth SubscriptionSubscriberCheck SubscriptionSipRequest SubscriptionSipResponse SipLegEnd SipTransaction_Response SipTransaction_SubscriberCheck

### Pre- and post-features

The B2BUA ECUR pre- and post-features cover event charging using a reserve/confirm model. The features are responsible for:

- creating the reservation charging instance (`B2BUAChargingFeatureUtil.DEFAULT_ECUR_CHARGING_INSTANCE`) and default session counter on an initial SUBSCRIBE, MESSAGE, OPTIONS, or PUBLISH request

- performing the initial credit check

- detection of message delivery or nondelivery conditions and credit finalisation.

The general use case is that a message will be B2BUA’d through Sentinel. The ECUR pre-feature will request a credit check, then allow delivery of the message. When a response to the B2BUA’d message is received, the credit reservation will be confirmed (or refunded).

| During any credit check, Sentinel automatically ensures all incoming messages are queued in the SLEE until the CCA (or a timeout) is received; in other words, no further network events will be delivered to Sentinel and processed until the credit check is complete. Currently, Sentinel for SIP only supports one charging instance per Sentinel session, though this instance may have multiple session counters.

| All of Sentinel for SIP’s charging features make use of Sentinel’s comprehensive charging API. See Using the SIP Charging Manager. For a high level overview of Sentinel charging see Sentinel SIP Charging Architecture.

### Session state inputs and outputs

#### Inputs

Name | Format | Description | Behaviour if null/invalid
--- | --- | --- | ---
SentinelSelectionKey com.opencloud.sentinel.common.SentinelSelectionKey | Selection key (for example, `<platform_operator>::::`) | For selecting mappers | Increment InputParameterErrors Common cleanup actions
CurrentSipFeatureExecutionPoint com.opencloud.sentinel.feature.spi.SipFeatureScriptExecutionPoint | Enum value | Used to classify the triggering event | N/A
B2BUAChargingCounterAddress com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress | Key/value pairs identifying the session charged service | Determines which counter the feature will update with charging data (the ECUR features only treat one counter as the session charging counter at a time). Also see Outputs. | No-op unless initial request
LatestOcsAnswer org.jainslee.resources.diameter.ro.types.vcb0.CreditControlAnswer | Last received CCA | Passed through to a charging mapper to generate the session counter values | Exception thrown, if the feature is expecting a response from the OCS. Otherwise ignored.
RequestUnitsServiceSpecific java.lang.Long | Non-negative long | The number of pending requested units, or the number of reported used units, depending on state. | N/A

#### Outputs

Name | Format | Description
--- | --- | ---
B2BUAChargingCounterAddress com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress | Key/value pairs identifying the session charged service | Mapped from initial incoming chargeable event request in SIP-initiated sessions to determine the default session counter against which the units will be charged.

### Charging API interactions

The charging API interactions fall under the following categories:

- charging instructions issued on the `B2BUAChargingFeatureUtil.DEFAULT_ECUR_CHARGING_INSTANCE` itself

- updates made to all counters on the charging instance, mainly limited to updates from CCAs and credit finalisation

- complete implementation of event based charging on the default counter.

#### Interaction with the default charging instance

Interaction with the default charging instance includes bxref#:initialisation[initialisation], bxref#initial-and-update-credit-checks[checks for initialisation and updates], and bxref#:finalisation[finalisation].

##### Initialisation

When the pre-feature is first triggered on an incoming event request, it creates the default ECUR charging instance, under the name `B2BUAChargingFeatureUtil.B2BUA_ECUR_CHARGING_INSTANCE`. It then maps the initial request to a session counter address written to the session state field B2BUAChargingCounterAddress. This is the default session counter on which all ECUR based charging is performed.

##### Initial and update credit checks

On any trigger other than an incoming chargeable event request, both features check whether the B2BUAChargingFeatureUtil.DEFAULT_ECUR_CHARGING_INSTANCE has been initialised. The first step is to check the instance exists in the ChargingManager, then that the instance has a session counter with the address specified in session state B2BUAChargingCounterAddress. If either check fails, the feature ends immediately on the assumption that ECUR is not enabled.

The pre-feature will issue a credit reservation for an incoming chargeable event request. The called party leg is suspended until the OCS authorises the call.

##### Finalisation

Any feature can issue credit finalisation, however if the post-feature detects zero remaining legs or it receives an AbortSessionRequest, it issues credit finalisation itself.

#### Interaction with all session counters

When a CCA is received, all counters on the ChargingInstance will be processed according to the algorithm outlined in Counter Update Algorithm Pseudo Code.

If a credit finalisation is raised, the post-feature will clear the pending requested units on all session counters.

When charging using a non-default counter, another feature will need to set reported used and pending requested units on the counters as needed.

#### Interaction with the default session counter

The default ECUR session counter is fully managed by the ECUR pre- and post-features. Generally speaking, user features need not interact directly with this counter.

##### Setting pending requested units on the default counter

When the pre-feature is triggered on a chargable event, the pending requested units will be set to the value of RequestUnitsServiceSpecific in session state.

##### Setting reported used units on the default counter

When the pre-feature is triggered on the response to a chargable event, the reported used units will be set to the value of RequestUnitsServiceSpecific in session state.

### Mappers

This feature uses two mappers:

- The first converts the initial SIP request to SessionCounterAddress.
  The default implementation is SipRequestToSessionCounterAddress:

      // a mapper that takes a {{SipRequest}} and generates a {{SessionCounterAddress}}.
      final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
              getSessionState().getSentinelSelectionKey(),
              SipRequest.class,
              SessionCounterAddress.class,
              mappingPoint);

- The second mapper converts a CCA into a list of session counters.
  The default implementation is CCAtoSessionCounterList:

      // a mapper that takes a {{CreditControlAnswer}} and generates a {{List<SessionCounter>}}.
      final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
              getSessionState().getSentinelSelectionKey(),
              CreditControlAnswer.class,
              List.class
              mappingPoint);

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

## B2BUA Feature

The B2BUA feature provides back-to-back user agent functionality to Sentinel.

### Details

Feature script name | B2BUA
Applicable contexts | SIP service
Call-Type | All
Feature execution points | SipAccess_SessionAccept SipAccess_PartyRequest SipAccess_PartyResponse SipMidSession_PartyRequest SipMidSession_PartyResponse SubscriptionAccept SubscriptionSipRequest SubscriptionSipResponse SipTransaction_Accept SipTransaction_Request SipTransaction_Response
SAS Support | Yes
Prerequisite features | None
Network Operator Config | Yes
Subscriber Config | None
POJO or SBB | POJO
Feature FSMs | None
Feature Parameters | None
RA Entity Links | None

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | N/A

### Network Operator Data

B2BUA feature configuration is stored on a profile table called `SipB2BUAConfigProfileTable`.

Data is scoped according to a Sentinel selection key.

Attribute Name | Type | Default | Description
--- | --- | --- | ---
    PreserveCallIdOverB2BUA
| boolean | false | If true, the outgoing dialog will use the same SIP Call-ID as the incoming dialog.
    SendEarlyInitialInviteACK
| boolean | false | If true, on receiving a 2xx Response to an Initial INVITE request, an ACK will be sent on the dialog, and the incoming ACK will not be sent on the linked leg.

### Statistics

`B2BUA` feature statistics are tracked by the `sentinel.sip` SBB and can be found under the following parameter set:
SLEE-Usage → sentinel.sip service ID → sentinel.sip SBB ID → feature.B2BUA

Statistic | Type | Description
--- | --- | ---
    Started
| Counter | Incremented when the feature is invoked.
    FailedToStart
| Counter | Incremented when Sentinel encounters an error while attempting to start the feature.
    IssuedWarning
| Counter | Incremented when a non-fatal problem is encountered and the feature issues a warning.
    FailedDuringExecution
| Counter | Incremented when a fatal problem is encountered and the feature cannot execute correctly.
    TimedOut
| Counter | Incremented when the feature takes too long to complete and Sentinel aborts execution.
    FailedToCreateOutgoingLeg
| Counter | Incremented when an error occurs while attempting to create a new SIP leg.
    FailedToCreateOutgoingMessage
| Counter | Incremented when an error occurs while attempting to create a new SIP message.
    FailedToForwardMessage
| Counter | Incremented when the feature fails to forward a message for any reason.
    FailedToLinkLegs
| Counter | Incremented when the feature fails to link the triggering leg to a newly created B2BUA leg.
    FailedToSendNewErrorResponse
| Counter | Incremented when an error occurs while the feature is attempting to directly respond to an inbound request with an error response.
    LegAlreadyLinkedOnInitialRequest
| Counter | Incremented when the feature detects that the leg an inbound initial request was received on already has a linked leg.
    SessionEndingOnInitialRequest
| Counter | Incremented when the feature detects that the session is already ending while processing an initial request.
    LegsNotLinkedOnNonInitialMessage
| Counter | Incremented when the feature detects that the leg a non-initial request or response was received on is not linked to another leg.
    ForwardedResponse
| Counter | Incremented when a SIP response is successfully forwarded across the B2BUA.
    ForwardedRequest
| Counter | Incremented when a SIP request is successfully forwarded across the B2BUA.
    SentErrorResponse
| Counter | Incremented when the feature directly answers an incoming request with an error response.
    SentEarlyAck
| Counter | Incremented when the feature generates an immediate ACK to an incoming INVITE-2XX response.
    SuppressedAckAfterEarlyAck
| Counter | Incremented when the feature does not forward an inbound ACK due to it having already sent one on the linked leg.

### Behaviour

#### Basic Behaviour

The B2BUA feature divides the communication channel into two legs and mediates all SIP signaling between both ends of the session.

On receipt of an initial SIP request (i.e. a request without a To tag), the feature creates an outgoing leg, links it to the triggering leg, and forwards an equivalent request on the new leg. The forwarded request will have a new call ID unless the feature has been specifically configured to preserve the call ID across the B2BUA. If the initial request is received on a leg that is already linked to another leg, the feature will not create a new leg or attempt to forward the message on the existing leg. If another feature ends the session before the B2BUA feature processes the initial request, a new leg will not be created and the request will not be forwarded.

For all other incoming SIP messages the feature adds an equivalent outgoing SIP message to the linked leg’s message queue. If there in no leg linked to the triggering leg, the feature will not attempt to forward the message.

| This feature is a critical system feature, many features rely on the functionality and success of this feature, including the B2BUA SCUR, B2BUA ECUR, B2BUA IEC, and SDP Comparison features. See Sentinel SIP Feature Execution Points for more about running critical features.

#### Early ACKs

If configured to do so, on an incoming success response to an initial INVITE, the feature will send an early ACK on the triggering leg, and will subsequently not forward the ACK received on the linked leg. An early ACK will not be sent if SDP negotiation has not been completed (offer & answer).

#### Error Responses

There are a number of cases where the feature will generate and send an error response for an inbound request instead of forwarding the request:

- When the feature forwards a request on a linked leg, it will decrement the value of the `Max-Forwards` header on the outbound request. If the value reaches 0, the feature will generate and send a 483 (Too Many Hops) response.

- If the feature receives a request and is unable to forward it on the linked leg due a to a SIP transaction already being in progress on that leg, it will send a 491 (Request Pending) response.

- If an internal error occurs that prevents the request from being forwarded, the feature will send a 500 (Server Internal Error) response.

## B2BUA IEC Features

The B2BUA IEC charging features define immediate event charging for Sentinel SIP as a B2BUA.

### Description

Feature script name | B2BUAIECPreFeature, B2BUAIECPostFeature
Applicable contexts | SIP service
SAS Support | Yes
Prerequisite features | B2BUA
Feature execution points | Pre SipAccess_ChargingReauth SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_OCSFailurePostCC SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReachedPostCC SipMidSession_OCSFailurePostCC SipMidSession_ChargingReauth SubscriptionSubscriberCheck SubscriptionSipRequest SubscriptionSipResponse CreditFinalised SipTransaction_Response SipTransaction_SubscriberCheck Post SipAccess_ChargingReauth SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_OCSFailurePostCC SipAccess_PartyResponse SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReachedPostCC SipMidSession_OCSFailurePostCC SipMidSession_ChargingReauth SubscriptionSubscriberCheck SubscriptionSipRequest SubscriptionSipResponse SipLegEnd SipTransaction_Response SipTransaction_SubscriberCheck

The B2BUA IEC pre and post features cover event charging using a charge/refund model. The features are responsible for:

- creating the reservation charging instance (`B2BUAChargingFeatureUtil.DEFAULT_IEC_CHARGING_INSTANCE`) and default session counter on an initial SUBSCRIBE, MESSAGE, OPTIONS, or PUBLISH request

- instructing the charging manager to send a direct debit to the OCS

- detection of message nondelivery conditions and refunding as necessary

The general use case is that a chargeable message — a SUBSCRIBE, MESSAGE, OPTIONS, or PUBLISH — will be B2BUA’d through Sentinel. The IEC post feature will trigger a direct debit, then allow delivery of the message. If a response to the B2BUA’d message is received which indicates non-delivery, the amount debited will be refunded.

For a high level overview of Sentinel charging see Sentinel SIP Charging Architecture

| 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 com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform_operator>::::` ) | For selecting mappers | Increment InputParameterErrors Common cleanup actions
CurrentSipFeatureExecutionPoint com.opencloud.sentinel.feature.spi.SipFeatureScriptExecutionPoint | Enum value | Used to classify the triggering event | N/A
B2BUAChargingCounterAddress com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress | key/value pairs identifying the session charged service | Determines which counter the feature will update with charging data (the IEC features only treat one counter as the session charging counter at a time). Also see Outputs. | No-op unless initial request
LatestOcsAnswer org.jainslee.resources.diameter.ro.types.vcb0.CreditControlAnswer | Last received CCA | Passed through to a charging mapper to generate the session counter values | Exception thrown, if the feature is expecting a response from the OCS. Otherwise ignored.
RequestUnitsServiceSpecific java.lang.Long | Non-negative long | The number of pending requested units | N/A

#### Outputs

Name | Format | Description
--- | --- | ---
B2BUAChargingCounterAddress com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress | key/value pairs identifying the session charged service | Mapped from initial incoming chargeable event request in SIP initiated sessions to determine the default session counter against which the units will be charged.

### Charging API interactions

The charging API interactions fall under the following categories:

- charging instructions issued on the `B2BUAChargingFeatureUtil.DEFAULT_IEC_CHARGING_INSTANCE` itself

- updates made to all counters on the charging instance, mainly limited to updates from CCAs.

- complete implementation of event based charging on the default counter.

#### Interaction with the default charging instance

##### Initialisation

When the pre-feature is first triggered on an incoming event request, it creates the default IEC charging instance, under the name `B2BUAChargingFeatureUtil.B2BUA_IEC_CHARGING_INSTANCE`. It then maps the initial event request to a session counter address written to the session state field B2BUAChargingCounterAddress. This is the default session counter on which all IEC based charging is performed.

##### Initial debit

On any trigger other than an incoming chargeable event request, both features check whether the `B2BUAChargingFeatureUtil.DEFAULT_IEC_CHARGING_INSTANCE` has been initialised. The first step is to check the instance exists in the ChargingManager, then that the instance has a session counter with the address specified in session state B2BUAChargingCounterAddress. If either check fails, the feature ends immediately on the assumption that IEC is not enabled.

The pre feature will instruct the charging instance to send a direct debit message to the OCS.

The post feature will set the pending requested units and suspend the called party leg until the OCS authorises the call.

##### Refund

If the feature is triggered on a non-success response to a chargeable event, the pre feature will instruct the charging instance to refund the amount that was initially debited.

#### Interaction with all session counters

When a CCA is received, all counters on the ChargingInstance will be processed according to the algorithm outlined in Counter Update Algorithm Pseudo Code. The pre feature will clear the pending requested units on all session counters.

When charging using a non-default counter, another feature will need to set reported used and pending requested units on the counters as needed.

#### Interaction with the default session counter

The default IEC session counter is fully managed by the IEC pre and post features. Generally speaking, user features need not interact directly with this counter.

##### Setting pending requested units on the default counter

When the post feature is triggered on a chargable event, the pending requested units will be set to the value of RequestUnitsServiceSpecific in session state, unless they have already been set to a non-zero value. If the pending requested units value is non-zero, it will not be overwritten.

### Mappers

This feature uses two mappers:

- The first converts the initial SIP request to a SessionCounterAddress.
  The default implementation is SipRequestToSessionCounterAddress:

      // a mapper that takes a {{SipRequest}} and generates a {{SessionCounterAddress}}.
      final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
              getSessionState().getSentinelSelectionKey(),
              SipRequest.class,
              SessionCounterAddress.class,
              mappingPoint);

- The second mapper converts a CCA into a list of session counters.
  The default implementation is CCAtoSessionCounterList:

      // a mapper that takes a {{CreditControlAnswer}} and generates a {{List<SessionCounter>}}.
      final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
              getSessionState().getSentinelSelectionKey(),
              CreditControlAnswer.class,
              List.class
              mappingPoint);

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

## B2BUA SCUR Features

The SIP B2BUA SCUR Pre and Post features define default session charging behaviour for Sentinel SIP as a B2BUA.

### Overview

At a high level, the supported behaviour covers time-based session charging:

- creating the reservation charging instance (`B2BUAChargingFeatureUtil.DEFAULT_SCUR_CHARGING_INSTANCE`) and default session counter on an initial request

- initial credit check

- recurring credit re-authorisation and used unit reporting at regular intervals

- responding to `ReAuthRequests` from an OCS or the Sentinel Diameter Mediation layer

- detection of session end conditions and credit finalisation.

The SCUR features can also be used in conjunction with other reservation charging features such as SDP Comparison and MMTel Adhoc Conference. The SCUR features automatically handle accounting by updating session counters and the charging timer. The charging timer is armed redundantly if the session is replicated.

User features wishing to enhance Sentinel’s SCUR behaviour might be concerned with:

- requesting a credit reservation (for example, on a material SDP change)

- inspecting and reacting to specific CCA result codes

- temporarily suspending the sending of outgoing SIP messages scheduled on one or more legs during a credit check (already done for called party leg on initial credit check)

- creating purpose-specific session counters (see the section on Charging API interactions)

- temporarily suspending charging, for example during an announcement,

| During any credit check, Sentinel automatically ensures all incoming messages are queued in the SLEE until the CCA (or a timeout) is received; that is, no further network events will be delivered to Sentinel and processed until the credit check is complete. Currently, Sentinel SIP only supports one charging instance per Sentinel session, though this instance may have multiple session counters.

All Sentinel SIP’s charging features make use of the Sentinel SIP Charging Architecture.

### Details

Feature script name | B2BUAScurPreFeature and B2BUAScurPostFeature
Applicable contexts | SIP service (INVITE dialog)
SAS Support | Yes
Requisite features | B2BUA
Feature execution points | Pre SipAccess_SubscriberCheck SipAccess_PartyRequest [SipAccess/SipMidSession]_CreditAllocatedPostCC [SipAccess/SipMidSession]_CreditLimitReachedPostCC [SipAccess/SipMidSession]_OcsFailurePostCC [SipAccess/SipMidSession]_ControlNotRequiredPostCC CreditFinalised SipAccess_ServiceTimer SipMidSession_ChargingReauth SipAccess_ChargingReauth Post [SipAccess/SipMidSession/SipThirdPartyAccess]_SubscriberCheck [SipAccess/SipMidSession]_PartyRequest [SipAccess/SipMidSession]_PartyResponse [SipAccess/SipMidSession]_CreditAllocatedPostCC [SipAccess/SipMidSession]_CreditLimitReachedPostCC [SipAccess/SipMidSession]_OcsFailurePostCC [SipAccess/SipMidSession]_ControlNotRequiredPostCC CreditFinalised SipAccess_ServiceTimer SipMidSession_ChargingReauth [SipAccess/SipMidSession]_ChargingReauth [SipAccess/SipMidSession]_ChargingAbort SubscriptionSipRequest SubscriptionSipResponse SipTransaction_Request SipTransaction_Response
Timer usage | Execution-point targeted timer will trigger the feature at the SipAccess_ServiceTimer execution point on expiry.

### Session state inputs and outputs

#### Inputs

Name | Format | Description | Behaviour if null/invalid
--- | --- | --- | ---
SentinelSelectionKey com.opencloud.sentinel.common.SentinelSelectionKey | selection key for example, `<platform_operator>::::` | For selecting mappers | Increment InputParameterErrors Common cleanup actions
CurrentSipFeatureExecutionPoint com.opencloud.sentinel.feature.spi.SipFeatureScriptExecutionPoint | Enum value | Used to classify the triggering event; for example, the initial invite ACK may occur on SipAccess_PartyRequest. | N/A
B2BUAChargingCounterAddress com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress | key/value pairs identifying the session charged service | Determines which counter the feature will update with timing data (the SCUR features only treat one counter as the session charging counter at a time — concurrent time counters would need to be managed in part by other features, while tariff changes would require updating this field with the address of a new counter). Also see Outputs. | No-op unless initial request
LatestOcsAnswer org.jainslee.resources.diameter.ro.types.vcb0.CreditControlAnswer | Last received CCA | When the feature is triggered on an RAR or QUOTA_EXHAUSTION the feature checks if the Final-Units-Indication AVP was present in the last CCA before proceeding with pending credit reservation. If present it instead calls legManager.endSession(). | Proceed with reservation
CallEstablished java.lang.Boolean | Alternative to an incoming initial invite ACK | Indicates when to set the session start time and the initial charging timer in third party setup calls. | Assumed false
RequestUnitsSeconds java.lang.Long | Non-negative long | Number of seconds the post feature will request on the default session counter on any credit reservation if not already set. | N/A - defaults to 60

#### Outputs

Name | Format | Description
--- | --- | ---
B2BUAChargingCounterAddress com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress | key/value pairs identifying the session charged service | Mapped from initial incoming request in SIP-initiated sessions to determine the default session counter against which time will be charged.

### Charging API interactions

The charging API interactions fall under the following categories:

- charging instructions issued on the `B2BUAChargingFeatureUtil.DEFAULT_SCUR_CHARGING_INSTANCE` itself

- updates made to all counters (which may or may not be time-based) on the charging instance, mainly limited to updates from CCAs and credit finalisation

- complete implementation of time-based charging on the default counter.

#### Interaction with the default charging instance

##### Initialisation

When the pre feature is first triggered on an initial incoming request, it creates the default SCUR charging instance, under the name `B2BUAChargingFeatureUtil.B2BUA_SCUR_CHARGING_INSTANCE`. It then maps the initial request to a session counter address written to the session state field B2BUAChargingCounterAddress. This is the default session counter on which all time-based charging is performed.

In a scenario with no initial incoming request, it is necessary for some user feature, such as the SIP Third Party Charging Feature, to initialize the charging instance and default session counter.

##### Initial and update credit checks

On any trigger other than an initial incoming request, both features check whether the `B2BUAChargingFeatureUtil.DEFAULT_SCUR_CHARGING_INSTANCE` has been initialised. The first step is to check the instance exists in the ChargingManager, and then that the instance has a session counter with the address specified in session state B2BUAChargingCounterAddress. If either check fails, the feature ends immediately on the assumption that SCUR is not enabled.

The pre feature will issue a credit reservation:

- On an initial SIP request

- On expiry of the charging timer (`QUOTA_EXHAUSTED`)

- Or receipt of an RAR

If the `Final-Units-Indicator` AVP was present in the previous CCA then a credit reservation will not occur, legManager.endSession() is called and a CCR-T is sent.

If a reservation was requested on the charging instance and there are no previous SIP requests on the calling party linked leg (in other words, the called party), the post feature treats it as an initial credit check. Therefore, the called party leg is suspended until the OCS authorises the call.

##### Finalisation

Any feature can issue credit finalisation; however if the post feature detects zero remaining legs or it receives an AbortSessionRequest, it issues credit finalisation itself.

#### Interaction with all session counters

When a CCA is received, all counters on the ChargingInstance will be processed according to the algorithm outlined in Counter Update Algorithm Pseudo Code.

If a credit finalisation is raised, the post feature will clear the pending requested units on all session counters.

When charging using a non-default counter, another feature will need to set reported used and pending requested units on the counters as needed.

#### Interaction with the default session counter

The default SCUR session counter is fully managed by the SCUR pre and post features. Generally speaking, user features need not interact directly with this counter.

##### Setting end time on the default counter

When the post feature detects credit finalisation is raised, it sets the default counter’s end time to the current system time.

##### Setting reported units on the default counter

If either charging instruction is raised, the reported used units will be set on the default counter and the SCUR charging timer will be cancelled.

##### Setting start time on the default counter

On an incoming initial invite ACK, the pre feature records the current time as the start time on the default counter. In a third-party scenario the initial invite ACK is outgoing, so the start time is recorded when the CallEstablished session state field is true and the charging timer ID is null.

##### Setting pending requested units on the default counter

If a reservation instruction was issued by the user or pre features, and pending requested is 0, it will be set to the value of RequestUnitsSeconds in session state.

##### Setting reported used units on the default counter

If a finalisation or reservation instruction is issued, the post feature sets reported used units on the default counter. It uses the utility method in `B2BUAChargingFeatureUtil.setReportedUsedMillis`, which simply deducts the cumulative committed units from the current chargeable time.

##### Calculating chargeable time from the default counter

Chargeable time is the time since the default counter’s session start time minus any uncharged time (in which the charging instance was suspended).

### LegManager outputs

Instruction | Parameter | Description
--- | --- | ---
suspend | N/A | Suspend the outgoing request leg on an initial credit check if it is not already suspended
resume | N/A | Resume the leg suspended by the post feature on an initial CCA
endSession | SipResponse.SC_PAYMENT_REQUIRED | Called when final units have been consumed

### Mappers

This feature uses two mappers:

- The first converts the initial SIP request to SessionCounterAddress. The default implementation is SipRequestToSessionCounterAddress

      // a mapper that takes a {{SipRequest}} and generates a {{SessionCounterAddress}}.
      final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
              getSessionState().getSentinelSelectionKey(),
              SipRequest.class,
              SessionCounterAddress.class,
              mappingPoint);

- The second mapper converts a CCA into a list of session counters. The default implementation is CCAtoSessionCounterList:

      // a mapper that takes a {{CreditControlAnswer}} and generates a {{List<SessionCounter>}}.
      final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
              getSessionState().getSentinelSelectionKey(),
              CreditControlAnswer.class,
              List.class
              mappingPoint);

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

## Determine Cause Code Feature

The Determine Cause Code feature is responsible for determining an appropriate value for the `Cause-Code` AVP in the `IMS-Information` AVP used in Diameter charging. It does this by monitoring an ongoing dialog looking for any event that could bring the dialog to an end. It selects an appropriate code based on what kind of dialog ending event it finds.

### Details

Feature script name | DetermineCauseCode
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | N/A
Feature execution points | All
Timer usage | N/A

### Source Code

This feature’s source code is available in the Sentinel SDK in the `sentinel-sip-service-information-modules` module pack. It can be viewed by using the `create-module` command in the SDK with that module pack. This command will prompt you for information needed to create the new modules, once completed the original source for the feature can be found in the new modules.

The module-pack includes the following modules relevant to this feature:

Module Name | Description
--- | ---
sentinel-sip-service-information-modules | Group module for all service information features, including the modules listed below.
sentinel-sip-service-information-session-state-library | Contains the session state interface for the feature.
sentinel-sip-determine-cause-code-feature | Contains the feature itself.

### Session state inputs and outputs

#### Inputs

Name | Type | Purpose
--- | --- | ---
CurrentSipFeatureExecutionPoint | Enum | Used to classify a dialog’s type and status.
EndSessionCause | Integer | Used to detect end-of-dialog triggered by an explicit call to the session ender.

#### Outputs

Name | Type | Description
--- | --- | ---
DiameterCauseCode | Integer | The value to be used in the `Cause-Code` AVP

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Statistics

This feature does not provide any usage statistics.

### Behaviour

The DetermineCauseCode feature detects and classifies conditions that would bring about the end of a dialog. The feature runs at the end of every execution point to allow it detect any end of dialog cause. When it executes, the feature will start by determining the type of dialog based on what SIP Request method was used to initiate the dialog. From there, the feature will look for all possible conditions that could bring the dialog to an end. Finally, if the dialog is determined to be ending, a cause code value will be selected based on what condition triggered it and that value will be set in the `DiameterCauseCode` session state field.

This table summarises the possible cause code values, details of how they are determined follow on below.

Code | Meaning
--- | ---
`-3xx` | Dialog was terminated with a SIP 3xx response. The actual value of the code will match the response status.
`-2xx` | Dialog was terminated with a SIP 2xx response. The actual value of the code will match the response status.
`-2` | Subscription dialog ended normally.
`-1` | Transaction dialog ended normally.
`0` | Invite session ended normally.
`2` | Invite session setup failed.
`3` | There was an internal error in Sentinel and no other code can be determined.
`4xx` | Dialog was terminated with a SIP 4xx response. The actual value of the code will match the response status.
`5xx` | Dialog was terminated with a SIP 5xx response. The actual value of the code will match the response status.
`6xx` | Dialog was terminated with a SIP 6xx response. The actual value of the code will match the response status.

#### Dialog Classification

The feature classifies the dialog into one of three categories: subscriptions, transactions, and invite sessions. It does this classification by examining the initial execution point that the feature was triggered on, which corresponds to the method of the SIP request the initiated the SIP dialog, as follows:

Execution Point | Type | Initial Request Method
--- | --- | ---
`SipAccess_SessionAccept` | Invite Session | `INVITE`
`SipThirdPartyAccess_SessionAccept` | Invite Session | `INVITE` (Triggered by an HTTP `GET`)
`SubscriptionAccept` | Subscription | `SUBSCRIBE` or `REFER`
`SipTransaction_Accept` | Transaction | `MESSAGE`, `PUBLISH`, OR `OPTIONS`

Note that the feature does not support `REGISTER` dialogs.

#### End of Dialog Detection

The procedures for detecting an ending dialog depends on the dialog type. The detailed procedures for each dialog type are laid out below. Note that a cause code value of `3` will occur any time an internal error prevents the feature from determining a more accurate code.

##### Transaction Dialogs

When evaluating a transaction dialog, the feature will proceed through the following checks until one results in a cause code value being found and stored in the `DiameterCauseCode` session state field. If none of the checks produce a cause code then the dialog is considered to be still in progress and session state will not be modified.

1. Check if the session ender was explicitly invoked to terminate the dialog. If this is the case, then the cause code will match the SIP response status code that was provided to the session ender.

2. Check if the calling leg has already been released by the leg manager. If this has happened, one of two things can happen:

   1. If a cause code had previously been determined in an earlier run of the feature, that code will be preserved.

   2. If no cause code has been determined, then `-1` (Successful transaction) will be used.

3. Check for a pending final response queued to be sent on the calling leg, if one is found a code will be selected as follows:

   1. If the response status is `200 OK` then a code of `-1` (Successful transaction) will be used.

   2. For any other final response, the response status will be used.

##### Subscription Dialogs

When evaluating a subscription dialog, the feature will proceed through the following checks until one results in a cause code value being found and stored in the `DiameterCauseCode` session state field. If none of the checks produce a cause code then the dialog is considered to be still in progress and session state will not be modified.

1. Check if the session ender was explicitly invoked to terminate the dialog. If this is the case, then the cause code will match the SIP response status code that was provided to the session ender.

2. Check if the calling leg has already been released by the leg manager. If this has happened, one of two things can happen:

   1. If a cause code had previously been determined in an earlier run of the feature, that code will be preserved.

   2. If no cause code has been determined, then `-2` (End of subscribe dialog) will be used.

3. Check if the most recently received `SUBSCRIBE` request has a `Expires` header with the value `0`. If this is the case, then `-2` (End of subscribe dialog) will be used.

4. Check for a final response the most recent `SUBSCRIBE` request (regardless of whether it has been sent or is queued) that has a status that is greater than or equal to `300`. If one is found then the response status will be used as the cause code.

##### Invite Sessions

For invite sessions, the feature does an additional classification to determine what state the session is in: setup, mid-session, or ending. This classification is made based on the current execution point, and on whether an `ACK` for the initial `INVITE`/`200` transaction has been sent or received by Sentinel.

For sessions in the setup phase, the feature will proceed through the following checks until one results in a cause code value being found and stored in the `DiameterCauseCode` session state field. If none of the checks produce a cause code then the dialog is considered to be still in progress and session state will not be modified.

1. Check if the session ender was explicitly invoked to terminate the dialog. If this is the case, then the cause code will match the SIP response status code that was provided to the session ender.

2. Check if the calling leg has already been released by the leg manager. If this has happened, one of two things can happen:

   1. If a cause code had previously been determined in an earlier run of the feature, that code will be preserved.

   2. If no cause code has been determined, then `2` (Unsuccessful session setup) will be used.

3. Check if a SIP `BYE` request has been sent or received, or is queued to be sent on the calling party leg. If this is the case, then `2` (Unsuccessful session setup) will be used.

4. Check for a final response to the initial `INVITE` request (regardless of whether it has been sent or is queued) that has a status that is greater than or equal to `300`. If one is found then the response status will be used as the cause code.

For sessions in the mid-session phase, the `DiameterCauseCode` session state field will be immediately set to `0` (Normal end of session) as this is guaranteed from this point.

For session in the ending phase will check if a cause code has been determined in an earlier run of the feature. If one has been, nothing will change. If there is no cause code, then `0` (Normal end of session) will be set in the `DiameterCauseCode` session state field.

## Diameter Per Leg Info Feature

This feature constructs `IMS-Information` AVPs that record leg-specific information about the call, for use in CDRs and Diameter Ro Credit-Control-Requests.

The feature name is `DiameterPerLegInfo`, as it is based on 3GPP TS 32.299 v12.11.0 (vcb0).

### Description

Feature script name | DiameterPerLegInfo
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | DetermineCauseCode, DetermineCallType, StoreHeaderInfo, RecordTimestamps
Feature execution points | All

### Session state inputs and outputs

#### Inputs

Name | Type | Purpose
--- | --- | ---
PerLegInitialRequestTimeMillis | Map<String, Long> | Holds the time when the initial INVITE request was seen on each leg. Used for the `SIP-Request-Timestamp` AVP in the `Time-Stamps` AVP. Set by the RecordTimestamps feature.
PerLegFinalResponseTimeMillis | long | Holds the time when the initial INVITE final response arrived on each leg. Used for the `SIP-Response-Timestamp` AVP in the `Time-Stamps` AVP. Set by the RecordTimestamps feature.
ChargingIdentifier | String | Used for the `3GPP-Charging-Id` or `Access-Network-Charging-Identifier-Value` AVPs. Set by the StoreHeaderInfo feature.

#### Outputs

Name | Type | Description
--- | --- | ---
ImsInformation | org.jainslee.resources.diameter.ro.types.vcb0.ImsInformation | The `IMS-Information` AVP that will be written to a CDR, or sent in a Credit-Control-Request. This AVP is defined in 3GPP TS 32.299 v12.11.0 §7.2.77.
PerLegEventType | Map<String, org.jainslee.resources.diameter.ro.types.vcb0.EventType> | The table of leg names mapped to their corresponding `Event-Type` AVP data
PerLegEarlyMediaDescription | Map<String, org.jainslee.resources.diameter.ro.types.vcb0.EarlyMediaDescription> | The table of leg names mapped to their corresponding `Early-Media-Description` AVP data
PerLegSdpMediaComponents | Map<String, org.jainslee.resources.diameter.ro.types.vcb0.SdpMediaComponent> | The table of leg names mapped to their corresponding `SDP-Media-Component` AVP data
PerLegTimeStamps | Map<String, org.jainslee.resources.diameter.ro.types.vcb0.TimeStamps> | The table of leg names mapped to their corresponding `Time-Stamps` AVP data
PerLegCallingPartyAddress | MultiMap<String, String> | The table of leg names mapped to their corresponding `Calling-Party-Address` AVP data, of which there may be several per leg
PerLegCalledPartyAddress | MultiMap<String, String> | The table of leg names mapped to their corresponding `Called-Party-Address` AVP data, of which there may be several per leg
PerLegRequestedPartyAddress | Map<String, String> | The table of leg names mapped to their corresponding `Requested-Party-Address` AVP data
PerLegInitialCallingPartyRequestURIString | Map<String, String> | The table of leg names mapped to IntialCallingPartyRequestURI - used for the `Requested-Party-Address` AVP. Obtained from the incoming Request-URI.

### Behaviour

The DiameterPerLegInfo feature populates the Diameter Ro `IMS-Information` AVPs with information about the call which is specific to each leg. Information about the call as a whole is populated by the Diameter Service Info feature. The information is gathered on a per-leg basis where it is specific to a given SIP leg. Such values are recorded into session state maps keyed by leg name. The feature needs to be run in two separate modes at different phases of each execution point. The `inbound` mode should be invoked in the SIP system pre scripts to process the incoming trigger leg, while the `outbound` mode should be invoked in the `post` scripts to monitor outgoing messages on all SIP legs. The feature stores the `IMS-Information` AVPs in session state, and updates it at various feature execution points when other features have run. The resulting AVPs are used by the AVP CDR Feature feature when writing a CDR. The AVPs are also sent in Credit-Control-Requests to the OCS.

## Diameter Service Info Feature

This feature constructs `IMS-Information` AVPs that record information about the call, for use in CDRs and Diameter Ro Credit-Control-Requests.

The feature name is `DiameterServiceInfo`, as it is based on 3GPP TS 32.299 v12.11.0 (vcb0).

### Description

Feature script name | DiameterServiceInfo
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | DetermineCauseCode, DetermineCallType, StoreHeaderInfo, RecordTimestamps
Feature execution points | All

### Session state inputs and outputs

#### Inputs

Name | Type | Purpose
--- | --- | ---
OriginatingInterOperatorIdentifier | String | Used for the `Originating-IOI` AVP in the `Inter-Operator-Identifier` AVP. Set by the StoreHeaderInfo feature.
TerminatingInterOperatorIdentifier | String | Used for the `Terminating-IOI` AVP in the `Inter-Operator-Identifier` AVP. Set by the StoreHeaderInfo feature.
IMEI | String | Used as the `User-Equipment-Info-Value` AVP in the `User-Equipment-Info` Grouped AVP. Set by the StoreHeaderInfo feature.
UserSessionId | String | The session’s Call-ID, used for the `User-Session-Id` AVP. Set by the StoreHeaderInfo feature.
IMSChargingId | String | The `icid-value` parameter of the SIP "P-Charging-Vector" header, used as the `IMS-Charging-Identifier` AVP. Set by the StoreHeaderInfo feature.
CallType | Enum | Used to set the `Subscriber-Role` AVP. Set by the DetermineCallType feature.
AccessNetworkInfo | String | Used for the `Access-Network-Information` AVP. Set by the StoreHeaderInfo feature.
DiscoveredAccessNetworkInformation | String | Used for the `Access-Network-Information` AVP if the AccessNetworkInfo isn’t set. Set by application level features.
DiameterCauseCode | int | Used for the `Cause-Code` AVP, indicating how the session ended. Set by the DetermineCauseCode feature.
ChargingIdentifier | String | Used for the `3GPP-Charging-Id` or `Access-Network-Charging-Identifier-Value` AVPs. Set by the StoreHeaderInfo feature.

#### Outputs

Name | Type | Description
--- | --- | ---
ImsInformation | org.jainslee.resources.diameter.ro.types.vcb0.ImsInformation | The `IMS-Information` AVP that will be written to a CDR, or sent in a Credit-Control-Request. This AVP is defined in 3GPP TS 32.299 v12.11.0 §7.2.77.
CallId | String | The SIP Call-ID of the current session.
EventId | String | The subscribed event ID, if present.

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

- AvpCdrFeature

- Interim CDR Feature

- MMTel Determine International and Roaming Status

### Description

Feature Script Name | ExtractNetworkInfo
Call-Type | Orig or Term
Prerequisite features | N/A
Session Plan | all
Execution points | For Sentinel Express: Post_SipAccess_SubscriberCheck, Post_SubscriptionSubscriberCheck, Post_SipTransaction_SubscriberCheck, Post_SipThirdPartyAccess_SubscriberCheck. For Sentinel VoLTE: Post_SipAccess_SessionCheck, Post_SubscriptionSessionCheck, Post_SipTransaction_SessionCheck.
Network Operator Config | Yes
Subscriber Config | No
POJO or SBB | POJO
Feature FSMs | None
Feature Parameters | None
SAS Support | Yes
RA Entity Links | None

### Prerequisite features

- DetermineCallType

### Session State Inputs and Outputs

#### Inputs

Name | Type | Purpose
--- | --- | ---
PvniMccMnc | com.opencloud.sentinel.common.MccMnc | If set, the feature will not attempt to do `PVNI` header analysis. See Outputs below.
PaniMccsMncs | List<com.opencloud.sentinel.common.MccMnc> | If set, the feature will not attempt to do `PANI` header analysis again. See Outputs below.
IsoCountryCode | String | If set, the feature will not update the `IsoCountryCode`. See Outputs below.
RegistrationRecords | RegistrationRecord | `PANI` and `PVNI` headers from registration records are used if the initial SIP request did not contain the corresponding header with `MCC` and `MNC` data. The `MCC` and `MNC` are parsed from the header and stored in the PvniMccMnc session state field. The RegistrationRecord field is normally set by IMSIDLookup in VoLTE.

#### Outputs

Name | Type | Description
--- | --- | ---
PvniMccMnc | com.opencloud.sentinel.common.MccMnc | The `MCC` and `MNC` data that was retrieved from a `PVNI` header found either on the request itself or in registration records.
PaniMccsMncs | List<com.opencloud.sentinel.common.MccMnc> | A list of `MCC` and `MNC` data retrieved from the `PANI` headers found either on the request itself or in registration records.
IsoCountryCode | String | The ISO Country Code found from the `PANI` headers found either on the request itself or in registration records.

### Behaviour

#### MCC and MNC

The ExtractNetworkInfo feature parses P-Access-Network-Info (PANI) and P-Visited-Network-Identifier (PVNI) headers found in the SIP trigger or Registration Records to determine the Mobile Country Code (MCC) and Mobile Network Code (MNC) for the subscriber. The following OpenCloud extension AVPs are used to communicate MCC and MNC information in CDRs and CCRs:

- `OC-ACCESS-NETWORK-MCC-MNC`

- `OC-VISITED-NETWORK-MCC-MNC`

- `OC-IMSI-NETWORK-MCC-MNC`

Priority is given to any headers present in the SIP trigger, if they are able to be parsed. In Mobile Terminating cases `OC-Term-P-Access-Network` and `OC-Term-P-Visited-Network` headers added by SCC during reorigination are used if present. For any given header type, if it is missing or invalid in the SIP trigger, the feature will then check registration records. When an MNC cannot be determined, but the MCC was able to be extracted, a value of "000" will be used in place of the missing MNC.

For information on Sentinel AVP definitions, please refer to Sentinel AVPs in the Sentinel Administration guide.

#### ISO Country Code

The ExtractNetworkInfo feature parses P-Access-Network-Info (PANI) and P-Visited-Network-Identifier (PVNI) headers found in the SIP trigger or Registration Records to determine the ISO Country Code for the subscriber and populates the `IsoCountryCode` session state field. The section below explains precedence:

##### Originating

- Look for a `country` parameter in the trigger’s P-Access-Network-Info headers

- Look for an `MCC` in the trigger’s P-Access-Network-Info headers and find the `ISOCountryCode` for that MCC in the corresponding `MobileCountryCodeInformation` profile

- Look for an `MCC` in the Cellular-Network-Info headers and find the `ISOCountryCode` for that MCC in the corresponding `MobileCountryCodeInformation` profile

- Look for an `MCC` in the P-Cellular-Network-Info headers and find the `ISOCountryCode` for that MCC in the corresponding `MobileCountryCodeInformation` profile

- Look for a `country` parameter in the registration data P-Access-Network-Info headers

- Look for an `MCC` in the registration P-Access-Network-Info headers and find the `ISOCountryCode` for the corresponding `MobileCountryCodeInformation` profile

##### Terminating

- Look for a `country` parameter in the registration data P-Access-Network-Info headers

If a `country` parameter is not found in stored P-Access-Network-Info headers:

- Look at available `MCC` information from the registration P-Visited-Network-Info header to determine if the subscriber is roaming

- Look at available `MCC` information from the registration P-Access-Network-Info headers to determine if the subscriber is roaming and determine the subscribers Access-Network type (WLAN or EUTRAN)

Store the `ISOCountryCode` associated with the first available `MCC` found in the subscriber’s P-Access-Network-Info headers

### Statistics

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

Name | Type | Description
--- | --- | ---
    Started
| Counter | Incremented when the feature is triggered.
    FailedToStart
| Counter | Incremented when the feature fails to start.
    FailedDuringExecution
| Counter | Incremented when the feature fails while executing.
    IssuedWarning
| Counter | Incremented when the feature issues a warning.
    TimedOut
| Counter | Incremented when the feature times out during execution.
    AccessNetworkMccMncFoundInTrigger
| Counter | Incremented when access network MCCs and MNCs are found in the triggering message.
    AccessNetworkMccMncFoundInRegistrationData
| Counter | Incremented when access network MCCs and MNCs are found in registration data.
    CellularNetworkMccMncFoundInTrigger
| Counter | Incremented when access network MCCs and MNCs are determined from a Cellular-Network header on the triggering message.
    UnableToDetermineAccessNetworkMccMnc
| Counter | Incremented when access network MCCs and MNCs cannot be determined.
    VisitedNetworkMccMncFoundInRegistrationData
| Counter | Incremented when the visited network MCC and MNC are found in registration data.
    VisitedNetworkMccMncFoundInTrigger
| Counter | Incremented when the visited network MCC and MNC are found in trigger.
    UnableToDetermineVisitedNetworkMccMnc
| Counter | Incremented when the visited network MCC and MNC cannot be determined.
    IsoCountryCodeFoundFromHeader
| Counter | Incremented when an ISO country code is extracted directly from an access network info header.
    IsoCountryCodeFoundFromMccMnc
| Counter | Incremented when an ISO country code is determined from an MCC and MNC value.
    IsoCountryCodeFoundFromHomeNetworkConfig
| Counter | Incremented when an ISO country code is determined from home network configuration in Sentinel.
    UnableToDetermineAccessNetworkIsoCountryCode
| Counter | Incremented when an ISO country code cannot be determined.

### Configuration

When parsing MNC’s from digit strings (such as an IMSI), the `MobileCountryCodeInformation` profile table is used to determine whether the MNC is two or three digits. The table maps an MCC to a list of that country’s MNC’s which are then compared against the digit string to determine length. At present, other fields are for administrative use only.

Parameter | Type | Description
--- | --- | ---
MCC | String | The three digit Mobile Country Code each profile represents.
MNCs | String[] | An ordered list of the two or three digit Mobile Network Codes for this MCC.
Country | String | The name of the country the MCC belongs to (for documentation purposes only.)
CountryDialCode | String | A digit string representing the actual dial code for this country.
ISOCountryCode | String[] | An ordered list of two-character strings representing the ISOCountryCode - each entry corresponds to an MNC. Use "UNKNOWN" for missing values.
Brands | String[] | An ordered list of brand names corresponding to each MNC. Use "UNKNOWN" for missing values.
Operators | String[] | An ordered list of operator names corresponding to each MNC. Use "UKNOWN" for missing values.

The ExtractNetworkInfo feature also relies on configuration from the `SipSentinelConfigurationTable`. The data is scoped by selection key.

Parameter | Type | Description
ISOCode | String | A two-character string representing the ISOCountryCode for the home network
MCC | String | The three digit Mobile Country Code for the home network

An example `MobileCountryCodeInformation` profile:

                MCC: "530"
                Country: "New Zealand"
                ISOCountryCode: "nz"
                CountryDialCode: "64"
                MNCs: !array
                    type: java.lang.String
                    values:
                       - "00"
                       - "01"
                ...
                Brands: !array
                    type: java.lang.String
                    values:
                       - "Telecom"
                       - "Vodafone"
                ...
                Operators: !array
                    type: java.lang.String
                    values:
                       - "Telecom New Zealand"
                       - "Vodafone New Zealand"
                ...

The value at at a given index of each of the following array attributes corresponds to the value at the same index of any other:

- `MNC` (01)

- `Brands` (Vodafone)

- `Operators` (Vodafone New Zealand)

### Configuration Profile Naming

Table Name | Description | Profile Naming
--- | --- | ---
MobileCountryCodeInformation | The Mobile Network Codes associated with a given Mobile Country Code. | SentinelSelectionKey with three digit Mobile Country Code suffix (for example, `metaswitch::::722`.)

The ExtractNetworkInfo feature also relies on configuration from the `SipSentinelConfigurationTable`. The data is scoped by selection key.

Table Name | Description | Profile Naming
--- | --- | ---
SipSentinelConfigurationTable |  | SentinelSelectionKey (for example, `metaswitch::::`.)

### Provisioning Interfaces

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

## Interim CDR Feature

`SipInterimCdr` is a system feature that is responsible for writing interim Call Detail Records and/or Diameter Accounting Requests (ACRs) throughout the session.

`SipInterimCdr` runs at various key points throughout a session and if any of its write conditions are met it writes either or both of:

1. an interim AVP CDR using the `cdr-ra`

2. an ACR using the `rf-control-ra`

Interim AVP CDRs and Diameter Accounting Records (ACRs) have substantially similar content and the same triggering logic hence both are supported by this feature.

The feature maintains a timer for the interim CDR period. This timer may be adjusted according to the Rf accounting interval provided by the CDF. The interim CDR timer is armed redundantly if session replication is enabled.

| By default, Sentinel runs `SipInterimCdr` as the very last feature in the `post` phase of almost every Sip or Charging related feature execution script and EndSession. For example:
    featurescript OnPostSubscriberCheck {
        if not session.MonitorCallOnly { run B2BUAScurPostFeature }
        run SDPMonitor mode "post"
        run DetermineCauseCode
        run DiameterServiceInfo
        run SipInterimCdr
    }

### Details

Feature script name | SipInterimCdr
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | None, but information from various features is used if available

### Session state inputs and outputs

#### Control flags indicating that an interim CDR should be written

Name | Type | Description | Where set
--- | --- | --- | ---
WriteCdrOnSDPChange | boolean | Indicates that a meaningful SDP change occurred on a monitored leg | SDP Comparison feature
LegForCdrs | String | Name of the leg for which CDRs and/or ACRs should be written | Defaults to `callingParty`, can be set by another feature during call setup.

#### Inputs

If any of these fields are unset the feature will skip writing the current CDR and/or ACR.

Name | Type | Description | Where set
--- | --- | --- | ---
CallId | String | The unique ID of the call | DiameterServiceInfo feature
CallType | Enumerated | The type of the call. One of `MobileOriginating`, `MobileTerminating`, `MobileForwarded`, `NetworkInitiated`, or `EmergencyCall` | DetermineCallType feature, SipThirdPartyHttpTrigger feature
ChargingResult | int | The result code of the Diameter session | Sentinel SIP service
DiameterServiceContextId | String | The Diameter context ID of the relevant service | AcceptSip feature, SipThirdPartyHttpTrigger feature
EndSessionCause | Integer | The end session cause code | LegManager
EventId | String | For `SUBSCRIBE` and `NOTIFY` events, the main value and `id` parameter of the `Event` header. For `REFER` events, the string `refer` and the sequence number. | DiameterServiceInfo feature
ImsInformation | org.jainslee.resources.diameter .ro.types.vcb0.ImsInformation | The IMS-Information Diameter AVP | DiameterServiceInfo feature
LatestOcsAnswer | org.jainslee.resources.diameter .ro.types.vcb0.CreditControlAnswer | The latest OCS response message | Sentinel SIP service
PlayedAnnouncementIDs | int[] | IDs of the played announcements | SipPlayAnnouncement feature, SipMidCallPlayAnnouncement feature
OcsSessionIds | String[] | An array of all the OCS session IDs for the call | Various features
OcsSessionTerminationCause | Integer | The OCS session termination cause | Sentinel SIP service
SentinelSelectionKey | com.opencloud.sentinel .common.SentinelSelectionKey | The selection key (for example, `<platform>::::`) for selecting configuration data | Various features
SipServiceType | Enumerated | The type of service Sentinel is processing. One of `Message`, `Subscription`, `SipCall`, or `Unknown`. | AcceptSip feature
Subscriber | String | The subscriber associated with the session | SipSubscriberDetermination feature

### Statistics

Name | Description
--- | ---
CDRWritten | Number of times a CDR or ACR was successfully written
CDRWriteError | Number of times a CDR or ACR was not successfully written
EventCDRWritten | Number of times an Event CDR or ACR was successfully written
StartCDRWritten | Number of times a Start CDR or ACR was successfully written
InterimCDRWritten | Number of times a Interim CDR or ACR was successfully written
StopCDRWritten | Number of times a Stop CDR or ACR was successfully written
TriggeredOnSDPChange | Number of times the feature was triggered due to SDP change
TriggeredOnInterimCdrTimer | Number of times the 'InterimCdrTimer' fired
NoLegForCdr | Number of times the feature ran with no leg for CDRs configured
RfControlActivityLost | Number of times rfControlActivity was lost from session state so a CDR or ACR was not successfully written

### Functionality

This feature can be configured to:

- write CDRs to the local filesystem (through the `cdr-ra`), and/or

- write ACRs using the Diameter Rf protocol (through the `rf-control-ra`)

This feature uses the information from the session state fields mentioned above and constructs a CDR and/or ACR for output. See AVP CDR Format for the format of the CDRs.

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

An interim CDR and/or ACR will be written under any of the following conditions:

- On the initial SIP request on the 'LegForCdrs'

- On the `SipInterimCdr` feature timer, if no CDR has been recently written

- On session end

- When a feature (e.g. SDP Monitor) sets `WriteCdrOnSDPChange` to true

When the feature is about to write an INTERIM or STOP ACR for a Sentinel Session, if checks if the current Rhino node has an Rf Control Activity for the Diameter Rf session. If it does not, a new Rf Control Activity is started using the same Rf session identifier. This fails over the Rf session.

Also see Charging Information for general information about the contents of CDRs, ACRs and CCRs.

| This feature only supports writing binary CDRs. If the `cdr-ra` is configured to write text CDRs the feature will fail to execute.

### Configuration

These parameters configure the feature:

Parameter | Type | Description
--- | --- | ---
WriteCdrOnSDPChange | boolean | When a meaningful SDP change occurs on a monitored leg, write a CDR
InterimTimerPeriod | long | The maximum duration in seconds between timer driven interim CDRs. Setting this to zero will disable timer based interim CDRs.
UseCdrRa | boolean | Whether interim CDRs should be written to disk using the `cdr-ra`
UseRfControlRa | boolean | Whether ACRs should be written using the `rf-control-ra`

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SipInterimCdrProfileTable | SipInterimCdr feature configuration parameters | SentinelSelectionKey (for example, `OpenCloud::::`)

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished
featureFailedToExecute | Cause.invalidSessionState, "rfControlActivity no longer in session state"

### Provisioning interfaces

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

## Max Call Duration Feature

| This feature is deprecated as of version 2.8.0.3 of Sentinel SIP. Its functionality is now handled by the Session Refresh Feature.

The Max Call Duration Feature monitors the call duration and terminates the call if the maximum call time has been exceeded.

On an incoming initial ACK or when the `callEstablished` session state field is `true`, a timer is set. The timer length is controlled by the `MaxTimerInterval` and `MaxCallDuration` parameters in the feature’s configuration. `MaxCallDuration` can be overridden with a session state value to enable unlimited call duration or a session specific max call duration. A feature should override the `MaxCallDuration` in the initial call setup phase not during mid-call. On the expiry of the timer, the feature checks the call time against the maximum call duration. If the maximum call time has been exceeded, `LegManager.endSession` is instructed. If not, then the timer is reset to the minimum of `MaxTimerInterval` and the remaining `MaxCallDuration`.

### Details

Feature script name | MaxCallDuration
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | N/A
Feature execution points | Pre SipAccess_SipRequest SipEndSession Post SipAccess_SipResponse
Timer usage | Feature-targeted timer triggers feature directly on expiry. Does not need to be registered against SipAccess_ServiceTimer execution point.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key for example, `<platform>::::` | For selecting configuration data | Increment InputParameterErrors, common cleanup actions
CallEstablished | Boolean | `true` or `false` | `true` if the session has been established | Initially set to `false`.
MaxCallDuration | Long | `null` or a value greater than or equal to `0` | `null` value feature will use configuration data. `0` value feature will be disabled for unlimited call length. Greater than `0` will set the Maximum call duration (ms) | Initially set to `null` a value less than `0` will be ignored.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Call Duration configuration

Parameter | Type | Description
--- | --- | ---
MaxTimerInterval | long | Interval of periodic timer (ms)
MaxCallDuration | long | Maximum call duration (ms)

### Statistics

Name | Description
--- | ---
CallLimitReached | Counter incremented when the call has been ended due to reaching the maximum call duration.

## Record Timestamps Feature

The Record Timestamps feature records the times at which Sentinel received a call’s initial request, and its associated final response.

### Details

Name in feature scripts | RecordTimestamps
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | N/A
Feature execution points | SipAccess_SessionStart, SipAccess_PartyResponse, SipThirdPartyAccess_SessionStart
Timer usage | N/A

### Source Code

This feature’s source code is available in the Sentinel SDK in the `sentinel-sip-service-information-modules` module pack. It can be viewed by using the `create-module` command in the SDK with that module pack. This command will prompt you for information needed to create the new modules, once completed the original source for the feature can be found in the new modules.

The module-pack includes the following modules relevant to this feature:

Module Name | Description
--- | ---
sentinel-sip-service-information-modules | Group module for all service information features, including the modules listed below.
sentinel-sip-service-information-session-state-library | Contains the session state interface for the feature.
sentinel-sip-record-timestamps-feature | Contains the feature itself.

### Session state inputs and outputs

#### Inputs

None

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
PerLegInitialRequestTimeMillis | Map<String,Long> | A table mapping each leg to the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. | Time that the initial request was received on each leg
PerLegFinalResponseTimeMillis | Map<String,Long> | A table mapping each leg to the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. | Time that the final response to the initial request was received on each leg

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Statistics

Name | Description
--- | ---
RequestTimestampSet | Counter incremented when the timestamp for the initial request is set.
ResponseTimestampSet | Counter incremented when the timestamp for the final response is set.

### Behaviour

The feature needs to be run in two separate modes at different phases of each execution point. The `inbound` mode should be invoked in the SIP system pre scripts to process the incoming trigger leg. In `inbound` mode, it verifies that it was triggered by an initial request, or the final response to such a request. If neither of these conditions is met, the feature will finish execution without modifying any state. In `outbound` mode, it checks outgoing messages on all SIP legs. If it detects an initial request, the feature will record the current system time into the `PerLegInitialRequestTimeMillis` session state field against the corresponding leg name, increment the associated statistic, and then finish execution. If it detects a final response, the feature will record the current system time into the `FinalResponseTimeMillis` session state field and increment the associated statistic.

## Remove Headers From Outgoing Messages Feature

The RemoveHeadersFromOutgoingMessages feature performs removal of headers from outgoing messages based on configuration.

### Behavior

The RemoveHeadersFromOutgoingMessages works as follows:

- For any SIP message present on a leg’s SipMessageQueue any header matching an entry in the `HeadersToRemoveFromOutgoingMessages` configuration will be removed.

- For any SIP message present on a leg’s SipMessageQueue any `Supported` header value matching an entry in the `SupportedHeaderValuesToToRemoveFromOutgoingMessages` configuration will be removed.

| In order to capture all outgoing SIP messages this feature should be the last feature to run in `all` Post System Feature execution points. If configured this feature will modify the content of any outgoing message with a matching header or `Supported` header value at the time of execution. Changing the features position within feature scripts may have side affects for subsequent features. See Sentinel SIP Feature Execution Points for more information.

### Details

Feature script name | RemoveHeadersFromOutgoingMessages
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | none
Feature execution points | Pre none Post SipAccess_SubscriberCheck SipAccess_PartyRequest SipAccess_PartyResponse SipAccess_ServiceTimer SipAccess_ChargingReauth SipAccess_ChargingAbort SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReached SipAccess_CreditControlNotRequiredPostCC SipAccess_OCSFailurePostCC SipMidSession_PartyRequest SipMidSession_PartyResponse SipMidSession_ChargingReauth SipMidSession_ChargingAbort SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReached SipMidSession_CreditControlNotRequiredPostCC SipMidSession_OCSFailurePostCC SubscriptionSubscriberCheck SubscriptionSipRequest SubscriptionSipResponse SipTransaction_SubscriberCheck SipTransaction_Request SipTransaction_Response SipLegEnd SipEndSession

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key for example: `<platform>::::` | For selecting configuration data |

### Feature responses

Response | Reason
--- | ---
featureHasFinished | Feature has finished.

### RemoveHeadersFromOutgoingMessages configuration

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

Parameter | Type | Description
--- | --- | ---
HeadersToRemoveFromOutgoingMesssages | String[] | Each entry of the array represents a header e.g `Session-Expires` that if present will be removed from outbound messages
SupportedHeaderValuesToRemoveFromOutgoingMesssages | String[] | Each entry of the array represents a value e.g `timer` or `preconditions` that if present will be removed from the `Supported` header of outbound messages

| `HeadersToRemoveFromOutgoingMessages` can not be configured with the following values `Cseq`, `Via`, `Rseq`, `RAck`, `From` and `To`.

### Statistics

Statistic | When incremented
--- | ---
RemovedHeaderFromOutboundMessage | A header matching a configured `HeadersToRemoveFromOutgongMessages` value was removed.
FailedToRemoveHeaderFromOutboundMessage | A header matching a configured `HeadersToRemoveFromOutgongMessages` value could not be removed.
RemovedSupportedHeaderValueFromOutboundMessage | A `Supported` header matching a configured `SupportedHeaderValuesToRemoveFromOutgongMessages` value was removed.
FailedToModifySupportedHeaderOfOutboundMessage | A failure occurred removing a `Supported` header matching a configured `SupportedHeaderValuesToRemoveFromOutgongMessages` value.
Started | The feature is invoked.
FailedToStart | The feature fails to start.
IssuedWarning | The feature encounters a non-fatal error and alerts the core.
FailedDuringExecution | The feature encounters any fatal error and alerts that core.
TimedOut | The feature fails to complete execution within the allowable time frame.

### Provisioning interfaces

The feature is provisioned using the Sentinel SIP Service Configuration REST API or web interface.

## SDP Comparison Feature

The SDP Comparison feature updates charging information with the OCS when the media streams of a session have changed.

### Details

Feature script name | SDPComparison
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | SDP Monitor B2BUAScurPostFeature
Feature execution points | Pre SipAccess_OCSFailurePostCC SipMidSession_OCSFailurePostCC Post SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_PartyResponse SipAccess_PartyRequest SipMidSession_CreditAllocatedPostCC SipMidSession_CreditLimitReachedPostCC SipMidSession_PartyRequest SipMidSession_PartyResponse

### Behaviour

This feature tracks changes in SDPs used to negotiate media streams, and triggers credit re-authorization if material changes have occurred. Materialness is determined by classifying the codec specified in the SDP into 'equivalence classes' (see Configuration).

If the difference between the previous and newly negotiated SDP is material from a rating condition perspective, then the feature will perform a client-initiated credit re-authorization towards the Online Charging System (OCS). The OCS will be notified that the reason is due to rating conditions changing. While the re-authorization is in progress, the outgoing message is suspended. On successful response from the OCS, the outbound message processing is resumed.

If the difference between the previous and newly negotiated SDP is immaterial, then no credit re-authorization will be performed. On session refresh, where the new SDP matches the previously negotiated SDP, no credit re-authorization will be performed.

If a codec is not mapped to an equivalence class, it will trigger a re-authorization when compared to any codec which does belong to a class. Two codecs, neither of which are mapped to a class, are consided equivalent and will not trigger a re-authorization. Another way to think of this is to consider that all codecs not specifically mapped are essentially mapped to their own class.

The following diagram gives some examples:

See SDP Comparison for an overview of the process

### Session state inputs and outputs

#### Inputs

None

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
WriteCdrOnSDPChange | boolean | Indicates that a meaningful SDP change occurred on a monitored leg | Written when an SDP change has been accepted by the other party. Used by the Interim CDR feature.

### Mappers

This feature uses two mappers:

- The first is used to map an SDP match model to an SDP match model that has been adapted to contain code equivalence lookups. The default implementation is SdpMatchModelToSdpCcrMatchModelMapper

      // a mapper that takes a {{SDPMatchModel}} and generates a {{SDPMatchModel}}.
      final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
              getSessionState().getSentinelSelectionKey(),
              matchModel.getClass(),
              SdpMatchModel.class,
              mappingPoint);

- The second mapper takes a DiffModel representing the total differences of two SDP and filters it to only show those differences relative to charging. The default implementation is SdpDiffToSdpCcrDiffMapper

      // a mapper that takes a {{SDPDiffModel}} and generates a {{SDPDiffModel}}.
      final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
          getSessionState().getSentinelSelectionKey(),
          arg.getClass(),
          SdpDiffModel.class,
          mappingPoint);

### Configuration

The default configuration recognizes three equivalence classes - Audio8KHzSingleChannel, Audio16KHzSingleChannel, and Video90KHzSingleChannel. The codecs mapping to each class are as follows:

Equivalence Class | EncodingName/ClockRate/Channels
Audio8KHzSingleChannel | G726-40/8000/1 GSM-EFR/8000/1 DVI4/8000/1 GSM/8000/1 LPC/8000/1 G726-24/8000/1 G729D/8000/1 G726-32/8000/1 G726-16/8000/1 PCMA/8000/1 PCMU/8000/1 G729E/8000/1 G723/8000/1 G722/8000/1
Audio16KHzSingleChannel | DVI4/16000/1
Video90KHzSingleChannel | MPV/90000/1 JPEG/90000/1 H263-1998/90000/1 H263/90000/1 MP2T/90000/1 CelB/90000/1 H261/90000/1

See SDP Comparison for Rating Condition Change Determination for details of configuring the SDP comparison.

## SDP Monitor Feature

The SDP Monitor system feature keeps track of all Session Description Protocol (SDP) offers and answers on a leg.

It works like this:

1. When an SDP offer is received, the feature updates the leg’s `latestReceivedSDP`, `previousReceivedSDP` and `latestReceivedSDPSequenceNumber` and waits for the corresponding answer.

2. When the corresponding SDP answer is sent, the feature updates the leg’s `latestSentSDP`, `previousSentSDP` and `latestSentSDPSequenceNumber`.

3. If the offer/answer exchange is successful the current `committedSDP` becomes the `previousCommittedSDP` and the leg’s `committedSDP` is set to the latest sent SDP on the leg. The `committedSDPSequenceNumber` is set to the latest SDP sequence number.

4. If the offer/answer exchange is unsuccessful, the previous `committedSDP` and `committedSDPSequenceNumber` value(s) (if any) are restored. At which point the feature waits for a new SDP offer and the offer/answer exchange continues.

The feature also maintains an SDP field specifying the exchange initiator. The field is used by the Diameter Service Info Feature feature to set the `Media-Initiator-Flag` AVP in charging requests. Other features can access the SDP information using the Sentinel SIP Leg API.

### Details

Feature script name | SDPMonitor
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | None
Feature execution points | Pre SipAccess_SessionStart SipAccess_PartyRequest SipAccess_PartyResponse SipMidSession_PartyRequest SipMidSession_PartyResponse SipLegEnd SipInstructionExecutionFailure Post All execution points (to examine messages queued by other features).

| Pre- and Post- Execution Points The SDP Monitor feature must run as a pre-system feature on the execution points given above, so that it sees all incoming SIP messages. It must also run as a post-system feature on all execution points, to ensure that messages sent by other features can be inspected before transmission. A feature parameter must be specified when invoking the feature in execution scripts. This will be either `pre` in Pre system feature execution points or `post` in all Post system feature execution points.

### Leg SDP fields

These fields on the leg interface are available to other Sentinel SIP features.

Field | What it specifies
--- | ---
LatestReceivedSDP | The latest SDP received on the leg.
LatestSentSDP | The latest SDP sent on the leg.
CommittedSDP | The SDP that was committed after the last successful offer/answer exchange.
LatestSentSDPSequenceNumber | The SDP origin sequence number in the last SDP sent on the leg.
LatestReceivedSDPSequenceNumber | The SDP origin sequence number in the last SDP received on the leg.
CommittedSDPSequenceNumber | The SDP origin sequence number in this leg’s committed SDP.
PreviousReceivedSDP | The previous SDP received on the leg.
PreviousSentSDP | The previous SDP sent on the leg.
PreviousSentSDPSequenceNumber | The previous origin sequence number in the previous SDP sent on the leg.
PreviousReceivedSDPSequenceNumber | The previous origin sequence number in the previous SDP received on the leg.
PreviousCommittedSDP | The SDP that was committed by the previous offer/answer exchange.

### Session state inputs and outputs

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

### Feature responses

Response | Reason
--- | ---
featureHasFinished | Feature has finished.
featureCannotStart | Feature parameter error and was unable to start.

### Configuration

This feature is not configurable.

### Statistics

Statistic | What it counts
--- | ---
SDPRollback | The number of times an offer/answer exchange failed and the latest SDP was rolled back. Caused by rejection or failure to send.
SDPOfferReceived | The number of SDP offers that have been received by the feature.
SDPOfferSent | The number of SDP offers that have been sent by the feature.
SDPAnswerReceived | The number of SDP answers that have been received by the feature.
SDPRejectionReceived | The number of sent SDP offers rejected by receiving final error responses.
SDPAnswerSent | The number of SDP answers the feature has sent.
SDPRejectionSent | The number of received SDP offers rejected by sending final error responses.
SDPCommitted | The number of times a successful offer/answer exchange has resulted in a committed SDP.

## SDP Rewriter Feature

The SDP Rewriter system feature rewrites session descriptions in messages forwarded between certain legs, to avoid SDP conflicts.

### Details

Feature script name | SDPRewriter
Applicable contexts | SIP service
SAS Support | Yes
Prerequisite features | None
Feature execution points | All post execution points

### Behaviour

When a feature requires SDP conflict management, it can call `SdpRewriting.startSdpRewritingForLegs()` to start an SDP rewriting association between a pair of legs. This association is persisted in session state, and includes rules for rewriting SDP sent in either direction, so that conflicts are avoided. The SDP Rewriter feature then examines SDP message bodies on all messages sent on these legs, and rewrites the SDP as appropriate. If either party updates their session description, this feature updates its rewriting rules for the legs, so that changes are propagated correctly to the other party.

For more details see SDP conflict management.

| The SDP Rewriter feature must run as a post-system feature on all execution points, to ensure that messages containing SDP sent by other features can be rewritten before transmission. The feature must run before the SDP Monitor feature, so that SDP Monitor sees the updated SDP, if present.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description
--- | --- | --- | ---
SdpRewriterMap | `SdpRewriterMap` | A map containing Leg associations and SDP rewriting rules, created by `SdpRewriting`. | Updated when the feature detects a change in the session description, such as a new media line. The rewriting rules are updated so that SDP is rewritten correctly in both directions.

#### Outputs

None

### Configuration

This feature is not configurable.

### Statistics

Statistic | What it counts
--- | ---
SDPRewritten | The number of times that an SDP message body has been rewritten.

## SIP Do Not Charge Feature

`DoNotChargeSipSession` is a system feature that is used to disable charging for a session.

It disables charging on a SIP session, and carries out these actions:

- for each active `ReservationChargingInstance` in the session, clears any charging instructions that are pending and finalises charging if the charging instance is not in the `Final` state.

- sets the `MonitorCallOnly` session state field to `true`.

| See Sentinel SIP Charging Architecture for more information about Sentinel SIP charging model. See Sentinel Charging Manager for more information about the `ChargingManager` and `ReservationChargingInstance`

### Details

Feature script name | DoNotChargeSipSession
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | N/A

### Session state inputs and outputs

#### Outputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
MonitorCallOnly | boolean |  | This field is `true` if the session is only being monitored. The initial value of this field is `false`. |

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

## SIP Downstream Forking Feature

### What is downstream forking?

Downstream forking occurs when something downstream (e.g. S-CSCF) of the application (Sentinel) decides to fork a call (e.g a result of subscriber registration data). A downstream call branch to each destination will be created. All 1XX(with the exception of 100) and 2XX responses must be forwarded upstream and the first final response forwarded will result in all remaining forks with active transactions being terminated using the CANCEL method.

It is possible for one or more additional 200 OKs to arrive whilst the CANCEL is still being processed, in this event these will also be forwarded upstream. In the event this happens, 3GPP TS 24.229 states the UE should ACK the additional 200 OKs and follow immediately with a BYE.

### Specification references

- 3GPP TS 23.228

- 3GPP TS 24.229

### Call flows

S-CSCF Downstream Forking call flow examples. For simplicity, these examples have non-reliable provisional responses.

- Downstream fork answers

- Downstream fork error

- Calling party cancels

### Downstream fork answers

SCSCF forks INVITE downstream of Sentinel. B-Party- B'' answer

### Downstream fork error

SCSCF forks INVITE downstream of Sentinel. B-Party- B' send 487 Final response

### Calling party cancels

SCSCF forks INVITE downstream of Sentinel. A-Party Cancels Call

### Feature description

Feature script name | SipDownstreamForking
Applicable contexts | SIP service
SAS Support | No
Prerequisite Features | None

The SipDownstreamForking feature handles a SIP call forked downstream by the S-CSCF, an application, or other UAS. This feature must be triggered on every early response and request until the call has been setup.

For each new downstream forked leg (dialog) response, the feature will import the leg into the Sentinel SIP Service and if the original INVITE was received upstream, the feature will forward the response on a new upstream leg (dialog) which is created by the feature and linked with the downstream leg. Subsequent early dialog messages on these legs will be be ignored by this feature but handled in the default way by the Sentinel SIP Service until a final response is received.

When the feature receives a final response, it will detach all other downstream legs and their linked upstream legs from the Service, delegating responsibility to the SIP SIS RA to clean up these remaining dialogs. In the crossover case where a CANCEL is received from the Calling Party and a Called Party forked leg answers, the forked leg that answered will be released (resulting in a BYE request sent).

| Regardless of which leg sends the final error response, the SIP SIS RA will always send it the initial calling party leg.

- The imported downstream fork legs will have the following leg name format: `downstreamfork[unique session id]`.

- The created upstream fork legs will have the following leg name format: `upstreamfork[unique session id]`.

The feature should be installed in the SipAccess_PartyRequest and as the first feature in the SipAccess_PartyResponse. It cannot be run in any other execution points.

### Feature interaction

#### First response on a new forked dialog

The first response on a new forked dialog is delivered by the SIP SIS RA on the activity which sent the INVITE request. Subsequent responses are delivered on the leg created by this feature activity.

If another feature is also using this first response it will be necessary to determine the correct leg as follows:

    Leg actualResponseLeg = legManager.getLeg(response.getSipSession());

The leg will only differ from the leg associated with the INVITE dialog if the response.isForked() returns true.

### Session State inputs and outputs

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

### Error scenarios

Scenario | Handling
--- | ---
Error occurred when creating upstream forked Leg | Increment ImportUpstreamForkedLegError
Error occurred when importing downstream forked Leg | Increment ImportDownstreamForkedLegError

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interface.

## Sequential Forked SDP Mediation

The Sequential Forked SDP Mediation Feature is used to mediate 183 and 2xx messages into UPDATE’s if multiple 183 messages with SDP content have been received due to a sequential fork.

The first 183 is sent through unchanged. When a subsequent 183 message or 2xx with SDP is received the feature will transform this into an UPDATE to be sent upstream. If a 2xx with SDP is mediated to an UPDATE, a 2xx without SDP is sent to the upstream party once the UPDATE has been responded to by the upstream party.

The one change that is made to the SDP is the session version number in the origin line, the feature ensures this value is always bigger than the previously sent version number if the SDP has changed.

The feature also runs on mid session messages such as a re-INVITE from downstream to ensure that the upstream party always receives SDP origin session version numbers that are bigger than have been previously sent if the SDP has changed.

If while an unreliable 183 is being mediated, a 2xx with SDP is received then the 2xx with SDP is cached until the UPDATE triggered by unreliable 183 is responded to and the 2xx is then mediated.

The Feature configuration allows users to change the behaviour of the feature. The default setting is `ALLOWS_UPDATE`, this means the feature will look at the `allow` header of the INVITE message to determine whether or not the UE supports UPDATE messages. If there is no UPDATE value present then the messages will simply be passed on, but if the INVITE did contain UPDATE in its `allow` list then any subsequent 183’s and 2xx with SDP will be changed into UPDATE messages. The other values of this config override the `allow` header, if set to `ON` then the feature will ignore the `allow` list and always behave as if the UE supports UPDATE messages. If `OFF` then the feature will not change 183’s or 2xx’s to UPDATEs.

### Details

Feature script name | SequentialForkedSDPMediation
Applicable contexts | SIP service
SAS Support | Yes
Prerequisite features | N/A
Feature execution points | Post SipAccess_PartyResponse SipMidSession_PartyRequest SipMidSession_PartyResponse

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key for example, `<platform>::::` | For selecting configuration data | Increment InputParameterErrors, common cleanup actions

### Feature responses

Response | Reason
--- | ---
featureCannotStart | No feature configuration could be loaded
featureHasFinished | Feature has finished

### Feature configuration

Parameter | Type | Description
--- | --- | ---
Mediate183ToUpdate | enum | Determines behaviour of feature, valid value are `ON`, `OFF`, and `ALLOWS_UPDATE`

### Statistics

Name | Description
--- | ---
UpdateSupported | Incremented when the UE indicates that is supports UPDATE messages
UpdateNotSupported | Incremented when the UE indicates no support for UPDATE messages
SDPUpdated | Incremented when the feature modifies the outgoing SDP
Mediated183ToUpdate | Incremented when the feature changes a 183 message into an UPDATE

### Example Flow

## Session Refresh Feature

The Session Refresh feature periodically instructs all `INVITE` dialog legs to refresh, and ends the call once the max duration is reached.

### Details

Feature script name | SessionRefresh
Applicable contexts | SIP service
Call-Type | All
Session Plan | All
Execution points | Pre SipAccess_SipRequest SipAccess_ChargingReauth SipMidSession_ChargingReauth SipEndSession Post SipAccess_SipResponse SipAccess_ServiceTimer
Feature Extension Events | None
Network Operator Config | Yes
Subscriber Config | None
POJO or SBB | POJO
Feature FSMs | None
Feature Parameters | None
SAS Support | No
Prerequisite features | None

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key + for example, `<platform>::::` | For selecting configuration data | Increment InputParameterErrors common cleanup actions
CallEstablished | Boolean | `true` or `false` | `true` if the session has been established | Initially set to `false`

### Feature responses

Response | Reason
--- | ---
    featureHasFinished
| Feature has completed execution for the current invocation.
    featureIssuedWarning
| Feature has encountered a non-fatal issue during execution.

### Feature Statistics

`SessionRefresh` statistics are tracked by the `sentinel.sip` SBB and can be found under the following parameter set:
SLEE-Usage → sentinel.sip service ID → sentinel.sip SBB ID → feature.SessionRefresh

Name | Type | Description
--- | --- | ---
    Started
| Counter | Incremented when the feature is triggered.
    FailedToStart
| Counter | Incremented when the feature fails to start.
    FailedDuringExecution
| Counter | Incremented when the feature fails while executing.
    IssuedWarning
| Counter | Incremented when the feature issues a warning.
    TimedOut
| Counter | Incremented when the feature times out during execution.
    SessionRefreshTimerStarted
| Counter | Incremented when the feature starts the periodic timer.
    SessionRefreshTimerStopped
| Counter | Incremented when the feature stops the periodic timer.
    InstructRefreshOnTimerFire
| Counter | Incremented when the feature instructs legs to refresh due to the timer firing.
    InstructRefreshOnChargingReauth
| Counter | Incremented when the feature instructs legs to refresh due to a charging reauth.
    MaxCallDurationReached
| Counter | Incremented when the feature ends a call due to the max duration being exceeded.

### Configuration

This feature reads configuration from the `SessionRefreshProfileTable` profile table. Profiles in this table are named based on the Sentinel selection key that they should be applied to. The profile specification for this table is `sentinel-sip-session-refresh-feature-profile`.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
    TimerInterval
    long
    290
| Interval of periodic timer (seconds)
    RefreshPeriod
    long
    570
| Period of no activity for leg to refresh (seconds)
    MaxCallDuration
    int
    86400
| Maximum time the call may be active for (seconds)
    RefreshWithUpdateIfAllowed
    boolean
    false
| Whether the session should be refreshed using UPDATE requests so long as the endpoint allows UPDATE requests.

### Session Input Data

Name | Type | Description
--- | --- | ---
SentinelSelectionKey | SentinelSelectionKey | Used to select configuration data. Issue a feature warning and use default configuration values.
CallEstablished | boolean | Used to determine whether the session should be considered established before receiving an ACK.
MaxCallDuration | Long | If this field is given a value greater than `0`, it will be used in place of the configured max call duration for the session. The value is in milliseconds.

### Session Output Data

Name | Type | Description
--- | --- | ---
SessionEstablishedTime | long | Unix timestamp representing the time the session was established.
MaxCallDurationExpireTime | long | Unix timestamp representing the time at which the maximum call duration will be reached.

### Provisioning interfaces

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

### Behaviour

On an incoming initial `ACK` or when the `callEstablished` session state field is `true`, a repeating timer is set. The timer’s period is specified by the `TimerInterval` value in the feature’s configuration. This timer is armed redundantly if the session is replicated. The number of repetitions will be so such that the timer will stop firing soon after the maximum call duration is reached.

Each time the timer fires, the feature first checks if the maximum call duration has been exceeded. If the max call duration has been exceeded, the feature will end the session. If not, `Leg.refreshSession` is instructed on each leg using the `RefreshPeriod` from the feature’s configuration. The `RefreshPeriod` represents the period of no activity before a refresh request should occur. If no messages have been sent or received on a leg within the `RefreshPeriod`, a refresh request transaction will be initiated.

Refresh requests are by default re-`INVITE` requests. The Session Refresh feature can be configured using the `RefreshWithUpdateIfAllowed` configuration to use `UPDATE` requests instead. If an endpoint did not include the `UPDATE` method in it’s `Allows` header then the `RefreshWithUpdateIfAllowed` configuration is ignored.

| RFC 6141 describes this process in SIP `INVITE` dialogs. This will cause all legs to be refreshed immediately.

#### Receipt of a Re-Auth-Request on the Ro interface

RFC 4005 (https://tools.ietf.org/html/rfc4005#page-13) states:

> A Diameter server may initiate a re-authentication and/or re- authorization service for a particular session by issuing a Re-Auth- Request (RAR) message [BASE].

> For example, for pre-paid services, the Diameter server that originally authorized a session may need some confirmation that the user is still using the services.

> If a NAS receives an RAR message with Session-Id equal to a currently active session and a Re-Auth-Type that includes authentication, it MUST initiate a re-authentication toward the user, if the service supports this particular feature.

Therefore when receiving a RAR, Sentinel responds with an RAA, initiates a Credit Control Update Request (CCR-U) and triggers this feature. This means that one or more SIP dialog refreshes run in parallel to the CCR-U. If the session refresh is successful then no further action is necessary. However if SIP dialog refreshes are not successful then Sentinel will move to the End Session point-in-session, thereby sending a CCR-T.

Additionally when the `Validity-Time` timer expires, Sentinel acts as though a RAR was received.

## Store Header Info Feature

The StoreHeaderInfo feature is responsible for extracting information from incoming SIP requests that is relevant for charging purposes. It looks at and records information relevant for charging purposes, specifically from the Contact, Call-ID, P-Charging-Vector, and P-Access-Network headers on SIP requests and responses received from the served user. It records information from the P-Early-Media, Allow, and Contact headers relevant to access transfer procedures.

### Details

Name in feature scripts | StoreHeaderInfo
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | Determine Call Type Feature
Feature execution points | Many, will be triggered once for each SIP request or response received by Sentinel.
Timer usage | N/A

### Source Code

This feature’s source code is available in the Sentinel SDK in the `sentinel-sip-service-information-modules` module pack. It can be viewed by using the `create-module` command in the SDK with that module pack. This command will prompt you for information needed to create the new modules, once completed the original source for the feature can be found in the new modules.

The module-pack includes the following modules relevant to this feature:

Module Name | Description
--- | ---
sentinel-sip-service-information-modules | Group module for all service information features, including the modules listed below.
sentinel-sip-service-information-session-state-library | Contains the session state interface for the feature.
sentinel-sip-store-header-info-feature | Contains the feature itself.

### Session state inputs and outputs

#### Inputs

Name | Type | Purpose
--- | --- | ---
CallType | Enum | Used when determining if a message was received from the served user.

#### Outputs

Name | Type | Description
--- | --- | ---
ChargingIdentifier | String | The Charging Identifier for the served user, extracted from one of a number of possible parameters on the P-Charging-Vector header.
IMSChargingId | String | The IMS Charging Identifier for the served user, taken from the icid-value of the P-Charging-Vector header. May be equal to the ChargingIdentifier.
TerminatingInterOperatorIdentifier | String | The Terminating Inter-Operator Identifier, taken from the term-ioi parameter of the P-Charging-Vector header.
OriginatingInterOperatorIdentifier | String | The Originating Inter-Operator Identifier, taken from the orig-ioi parameter of the P-Charging-Vector header.
IMEI | String | The IMEI, extracted from the Contact header of the incoming message.
UserSessionId | String | The Call-ID for the access leg. Used as User Session Id in Diameter charging.
HeadersByLeg | HeadersByLeg | A map containing header name-value pairs, organized by leg name. eg records the value of the P-Early-Media header on the CalledParty leg.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Statistics

Name | Description
--- | ---
SetAccessNetworkInfo | Counter incremented when the AccessNetworkInfo field is set in session state by the feature.
SetPEarlyMedia | Counter incremented when the P-Early-Media header is found in the message and set in the headersByLeg object in session state.
SetChargingIdentifier | Counter incremented when the ChargingIdentifier field is set in session state by the feature.
SetIMSChargingId | Counter incremented when then IMSChargingId field is set in session state by the feature.
SetTerminatingIOI | Counter incremented when TerminatingInterOperatorIdentifier is set in session state by the feature.
SetOriginatingIOI | Counter incremented when OriginatingInterOperatorIdentifier is set in session state by the feature.
SetIMEI | Counter incremented when IMEI is set in session state by the feature.
SetUserSessionId | Counter incremented when UserSessionId is set in session state by the feature.

### Behaviour

The StoreHeaderInfo feature runs whenever a SIP request or response is received by Sentinel. Initially the feature examines which leg the message was received on to determine whether the message came from the served user (i.e. the calling party on the originating instance, and the called party on a terminating instance). If the message was not received from the served user, the feature will not attempt to modify headers related to charging. If the message was received from the served user, the feature will attempt to extract charging information from the message headers as described below. Other headers are examined in all cases, regardless of served leg. Once it has done this, the feature will finish execution.

#### P-Access-Network-Info Header

If the `P-Access-Network-Info` header is present on the message, it will be recorded in the `headersByLeg` session state field. If the active leg already had a value for this header, it will be updated.

| 3GPP TS 24.229 (Release 8 and later) permits multiple `P-Access-Network-Info` header values in a message. However for charging purposes, 3GPP TS 32.299 Release 8 only allows a single `Access-Network-Information` AVP inside the `IMS-Information` grouped AVP. This discrepancy is corrected in Release 12, but this product targets Release 8 (specifically 8.13.0). So at this time we only read the first `P-Access-Network-Info` header value and use this in the single `Access-Network-Information` AVP in the AVP CDR and the final Ro Credit-Control-Request.

#### P-Charging-Vector Header

If the `P-Charging-Vector` header is present, then the feature will attempt to extract several pieces of information:

- The value of the `icid-value` will be taken and stored in the `IMSChargingId` session state field.

- If the `term-ioi` parameter is present, its value will be taken and stored in the `TerminatingInterOperatorIdentifier` session state field.

- If the `orig-ioi` parameter is present, its value will be taken and stored in the `OriginatingInterOperatorIdentifier` session state field.

- If any additional charging identifier parameters are present, one will be taken and stored in the `ChargingIdentifier` session state field.

  - Any of the following parameters can be used: `gcid`, `dslcid`, `bcid`, `itc-id`, or `ecid`.

  - If no additional charging identifiers are found, the `icid-value` will be used for the `ChargingIdentifier`.

#### Contact Header

If there is a `+sip.instance` parameter on the `Contact` header of the incoming message, the feature will look at its value and attempt to extract a valid IMEI from it. If an IMEI is found, it will be taken and stored in the `IMEI` session state field.

#### Call-ID

The value of the `Call-ID` header is used as an identifier for the session in Diameter charging. So, the value of this header will be taken and stored in the `UserSessionId` session state field.

#### P-Early-Media Header

If the `P-Early-Media` header is present, the header value will be recorded for the triggering leg in the `headersByLeg` session state field.

#### Allow Header

If the `Allow` header is present, the header values will be recorded for the triggering leg in the `headersByLeg` session state field. If there are multiple headers, these will all be preserved.

#### Remote Target

If the incoming message is a target refresh and the `Contact` header is present, the header value will be recorded for the incoming leg in the `headersByLeg` session state field.

## Subscribe Downstream Forking Feature

The Subscribe Downstream Forking Feature manages the additional SIP legs that can result from forked subscriptions.

1. When Sentinel sends or forwards an initial SUBSCRIBE, a downstream proxy may fork the request to several targets.

2. Each target that accepts the SUBSCRIBE will send an initial NOTIFY back to Sentinel.

3. The first NOTIFY to arrive is associated with the original downstream leg, and will automatically be forwarded upstream by the B2BUA Feature if it previously forwarded the SUBSCRIBE .

4. If additional NOTIFYs arrive as a result of a fork, then the `SubscribeDownstreamForking` feature is needed to determine how to handle them.

5. Each additional NOTIFY potentially creates a new SIP dialog, or leg in Sentinel.

   - If the event package (determined by the NOTIFY `Event:` header) does not support forking, then the `SubscribeDownstreamForking` feature automatically rejects the NOTIFY with a 481 response, and no new leg is created.

   - If the event package does support forking, then the `SubscribeDownstreamForking` feature creates new downstream and upstream legs, and schedules the NOTIFY to be forwarded upstream. The new upstream and downstream legs are linked, and subsequent requests on these legs will be handled by the B2BUA Feature.

   - The names of event packages that are known to support forking are configured as per [forking-event-packages-configuration].

### Details

Feature script name | SubscribeDownstreamForking
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | B2BUA Feature
Feature execution point | SubscriptionSipRequest [Pre]

### Specification references

- 3GPP TS 23.228

- 3GPP TS 24.229

- RFC 6665: SIP-Specific Event Notification

- IANA SIP Event Packages Registry

### Example Call Flows

#### Forked subscription accepted

This call flow shows a downstream proxy forking a SUBSCRIBE request. The resulting NOTIFYs from each target are forwarded upstream.

#### Forked subscription rejected

This call flow shows a downstream proxy forking a SUBSCRIBE request. In this case, assume that the subscribed event package does not allow forking. The `SubscribeDownstreamForking` feature rejects the forked NOTIFY immediately with a 481 response.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description
--- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key for example, `<platform>::::` | For selecting configuration data

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
ForkedNotifyResult | ForkedNotifyResult | Enum values: NONE, REJECTED, or FORWARDED | Describes the outcome of the feature: NONE: no action was taken REJECTED: the forked NOTIFY was rejected with a 481 response ACCEPTED: the forked NOTIFY will be forwarded upstream, with new upstream and downstream legs created for the new subscription.

### Configuration

#### Forking event packages configuration

Parameter | Type | Description
--- | --- | ---
ForkingEvents | String[] | Names of SIP event packages that support forking.

The default set of event packages that support forking is:

- `call-completion`

- `dialog`

- `message-summary`

- `refer`

- `winfo`

This is derived from the current list of standard event packages in the IANA SIP Event Packages Registry.

If an event package happens to be an event template package (such as `winfo` above), all event packages that derive from it are handled automatically. So the fictional package `foo.winfo` will automatically support forking because `winfo` does.

Additional event packages may be added as standards evolve, or to support proprietary events.

### Statistics

Statistic | When incremented
--- | ---
ForkedSubscriptionAccepted | A forked NOTIFY is accepted because the event package allows forked subscriptions.
ForkedSubscriptionRejected | A forked NOTIFY is rejected because the event package does not allow forked subscriptions.
ForkedSubscriptionDownstreamLegError | The feature is unable to create the leg representing the downstream side of a forked subscription.
ForkedSubscriptionUpstreamLegError | The feature is unable to create the leg representing the upstream side of a forked subscription.

## SIP User Features

Sentinel includes many user features for SIP networks:

- Accept SIP Feature— 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 `INVITE` and 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-URI` and other select address headers in the received `INVITE` request.

- 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-URI` of the received `INVITE` request.

- Sip Proxy and Do Not Record Route Feature— Proxies the incoming SIP session.

- SIP Short Code Feature— A pre-credit check feature that performs number translation of short-codes in the `request-URI` of the received `INVITE` request.

- 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 `INVITE` messages 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.

- Vertical Service Code Feature— This feature detects Vertical Service Codes in the dialled digit string, and modifies the session as required to give effect to them.

## Accept SIP Feature

### Description

Feature name | AcceptSip
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | None

Sentinel feature which verifies the triggering event is a SIP INVITE and initializes a SIP session. This includes setting the session type to 'sipcall' and incrementing the accepted dialogs counter.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>:<network>:::`) | Selection key to be initialized with session type | Runtime exception handled by feature runner

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
SessionType | com.opencloud.sentinel.common.SessionType | sipcall | Session type set to sipcall
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>:<network>:<session type>::`) | Updated selection key including session type determined from application context

### Error scenarios

Scenario | Handling
--- | ---
Trigger not a SipRequest | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureCannotStart | Trigger event is not a SipRequest
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## B2BUA Subscription Activity Guard Feature

The B2BUA Subscription Activity Guard feature tracks outstanding subscriptions and invalidates sessions which have not been correctly shut down.

The B2BUA Subscription activity guard feature is used to protect against servers not correctly terminating their subscriptions. For each non-terminating notify that is B2BUAed by Sentinel, this feature starts a timer which fires after the expiration of the notify. If another notify for the same subscription is received, the timer is updated. If a terminating notify is sent, the timer is cleared and removed. If the timer fires, this shows that a terminating notify has not been sent by the server. In this case, the feature invalidates and detaches from both legs of the call, freeing resources and cleaning up as appropriate.

### Details

Feature script name | SubscriptionActivityGuard
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | B2BUA
Requisite Features execution point [script] | SubscriptionSipRequest [Pre]
Timer usage | Feature-targeted timer triggers feature directly on expiry. Does not need to be registered against SipAccess_ServiceTimer execution point.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key for example, `<platform>::::` | For selecting configuration data | Increment InputParameterErrors Common cleanup actions

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Statistics

Name | Description
--- | ---
ActivityGuardTimeout | Number of times the timer fired and the feature had to terminate the subscription.

### B2BUA Subscription Activity Guard configuration

The configuration for the B2BUA Subscription Activity Guard Feature is provisioned in the following table:

Parameter | Type | Description
--- | --- | ---
ActivityGuardWaitTimeMillis | long | Number of milliseconds to wait after the expiry time before shutting down the legs.

### Provisioning interfaces

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

## Call Parties Address Determination Feature

### Description

Feature name | CallPartiesAddressDetermination
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | Determine Call Type Feature

The Call Parties Address Determination feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature attempts to extract the called and calling parties addresses from the INVITE and set the ‘CallingPartyAddress’ and ‘CalledPartyAddress’ session state fields. The feature analyses the relevant ‘InviteRequest’ on the ‘callingParty’ leg and the ‘calledParty’ leg (the latter only being used in the third-party-triggered case when determining the called party address).

### Leg Manager inputs

Leg | Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | --- | ---
calledParty | InviteRequest | org.jainslee.resources.sip.SipRequest | See Easysip javadoc | INVITE sent to the called party | Runtime exception handled by feature runner
callingParty | InviteRequest | org.jainslee.resources.sip.SipRequest | See Easysip javadoc | INVITE received from (respectively, in the NetworkInitiated case, sent to) the calling party | Runtime exception handled by feature runner

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | For selecting which Leg InviteRequest to use for determining CalledPartyAddress | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
CalledPartyAddress | String | MSISDN | The called party address
CallingPartyAddress | String | MSISDN | The calling party address

### Error scenarios

Scenario | Handling
--- | ---
Address record in SIP Invite is null or missing URI | Report featureCannotStart

### Feature responses

Response | Reason
--- | ---
featureFailedToExecute | Address determination of calling and called parties failed
featureHasFinished | feature has finished

### Configuration

Call Parties Address Determination Feature cannot be configured.

## Determine Call Type Feature

### Description

Feature name | DetermineCallType
Applicable contexts | SIP service
SAS Support | No
Prerequisite Features | None

The Determine Call Type feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature attempts to identify the call’s type, one of `MobileOriginating`, `MobileTerminating`, or `MobileForwarded`, which is stored in the CallType session state variable for future features.

### Leg Manager inputs

Leg | Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | --- | ---
callingParty | InviteRequest | org.jainslee.resources.sip.SipRequest | See Easysip javadoc | INVITE received from (respectively, in the NetworkInitiated case, sent to) the calling party | Runtime exception handled by feature runner

### Configuration

Parameters | Type | Description
--- | --- | ---
additionalCallForwardingDetection | boolean | When true, additional parameters will be considered when distinguishing between `MobileOriginating` and `MobileForwarded` calls. (default: `true`)

### Configuration feature naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
DetermineCallTypeConfigurationTable | Sentinel configuration table | SentinelSelectionKey (for example, `OpenCloud::::`)

### Session state inputs and outputs

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
CallType | com.opencloud.sentinel.common.CallType | One of: `MobileOriginating`, `MobileTerminating`, `MobileForwarded`, `NetworkInitiated`, `EmergencyCall` | Session type of this call

### Statistics

Statistic | When incremented
--- | ---
Started | The feature is invoked.
FailedToStart | The feature fails to start.
IssuedWarning | The feature encounters a non-fatal error and alerts the core.
FailedDuringExecution | The feature encounters any fatal error and alerts that core.
TimedOut | The feature fails to complete execution within the allowable time frame.
CallTypeIsMobileOriginating | The feature determines that the call type is `MobileOriginating`.
CallTypeIsMobileTerminating | The feature determines that the call type is `MobileTerminating`.
CallTypeIsMobileForwarded | The feature determines that the call type is `MobileForwarded`.

### Error scenarios

Scenario | Handling
--- | ---
Failed to get INVITE request from calling party leg | Report featureCannotStart
Insufficient information to determine call type | Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureCannotStart | CallingParty leg InviteRequest has not been set
featureFailedToExecute | Call type could not be determined
featureHasFinished | feature has finished

### Behaviour

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

- `MobileOriginating`

- `MobileTerminating`

- `MobileForwarded`

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

The feature uses either one of two headers on an incoming SIP request to determine the call type: `P-Served-User` and `Route`. The `P-Served-User` header is the preferred source of information. The `Route` header is only checked if the call type cannot be determined from the `P-Served-User` header.

#### P-Served-User Header

There are two parameters of interest on the `P-Served-User` header.

The first is a valueless `orig-cdiv` parameter, if this is present the call type will be classified as `MobileForwarded`. Otherwise, the feature will look for the `sescase` parameter, the value of that parameter will determine the call type as follows:

Parameter Value | Resulting Call Type
--- | ---
`orig` | `MobileOriginating` or `MobileForwarded` (see Additional Call Forwarding Detection below)
`term` | `MobileTerminating`
`orig-cdiv` | `MobileForwarded`

If none of these parameters or values are present, the feature will check the `Route` header instead.

#### Route Header

The feature always looks at the top-most route header of the incoming message. It will look for the following valueless parameters on the header to determine the call type:

Parameter Name | Resulting Call Type
--- | ---
`orig` | `MobileOriginating` or `MobileForwarded` (see Additional Call Forwarding Detection below)
`term` | `MobileTerminating`
`orig-cdiv` | `MobileForwarded`

If none of these parameters or values are present, the feature will use the default call type: `MobileTerminating`.

#### Additional Call Forwarding Detection

When a parameter on the `P-Served-User` or `Route` header indicates the call type is `MobileOriginating` and the `AdditionalCallForwardingDetection` config option is set to true, the feature will execute additional checks to determine if the call has been forwarded.

There two additional checks, one on the `Request-URI` the other on the `History-Info` header. The call type will be determined to be `MobileForwarded` if either one of the following conditions are met:

1. The `Request-URI` has a `cause` parameter with one of the following values: `302`, `404`, `408`, `480`, `486`, `487`, `503`.

2. There is a `History-Info` header present on the request.

If neither condition is met, the call type will be determined to be `MobileOriginating`.

## Determine Chargeable Leg Feature

### Description

Feature name | DetermineChargeableLeg
Applicable contexts | SIP service
SAS Support | Yes
Prerequisite Features | DetermineCallType

The Determine Chargeable Leg feature determines the chargeable leg of a call based on the call type. This information is then used to set a session state field which can be used by other VoLTE features that need to do charging-related activities.

By default the feature runs directly after the Determine Call Type feature.

### Session input and output variables

#### Session input variables

Session state variable name | Variable type
--- | ---
    CallType
| Enum

#### Session output variables

Session state variable name | Variable type | Comments
--- | --- | ---
    LegForCdrs
| String | The leg that will be used for the interim CDR logic

### Error scenarios

Scenario | Handling
--- | ---
Call type not set in session state | Report featureFailedToExecute
Unable to access leg manager or incoming leg | Report featureFailedToExecute

### Chargeable Leg

- If the call type is "Mobile Originating" then the `LegForCdrs` session state field will get set to the name of the calling party leg, if it exists.

- If the call type is "Mobile Terminating" then the `LegForCdrs` session state field will get set to the name of the leg linked to the calling party leg, if it exists.

- If the call type is anything else then the session state field will not get changed.

### Feature responses

Response | Reason
--- | ---
featureFailedToExecute | Chargeable leg could not be determined
featureHasFinished | feature has finished

### Configuration

Determine Chargeable Leg cannot be configured.

## Determine Registration Status Feature

### Description

Feature name | DetermineRegistrationStatus
Applicable contexts | SIP service
SAS Support | No
Prerequisite Features | None

The Determine Registration Status feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature attempts to identify the user’s registration state as one of Registered or Unregistered, which is then stored in the `SipRegistrationStatus` session state variable for future features.

### Leg Manager inputs

Leg | Name | Type | Format | Description Behaviour if null/invalid
--- | --- | --- | --- | ---
callingParty | InviteRequest | org.jainslee.resources.sip.SipRequest | See Easysip javadoc | INVITE received from the calling party Runtime exception handled by feature runner

### Session State inputs and outputs

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
SipRegistrationStatus | com.opencloud.sentinel.common.SipRegistrationStatus | One of: Registered, Unregistered | Registration status of this call

### Error scenarios

Scenario | Handling
--- | ---
Failed to get an INVITE request from the calling party leg | Report featureCannotStart
Insufficient information to determine registration status | Report featureFailedToExecute

### Registration status

The call’s registration status is classified as one of:

- Registered

- Unregistered.

A SipRegistrationStatus enum is defined to represent the values, and the registration status is stored in session state variable SipRegistrationStatus.

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

    Function determineRegistrationStatus(callingPartyInvite)

        regState = determineRegistrationStatusBasedOnPServedUser(callingPartyInvite)

        IF regState is null
        THEN
            featureFailedToExecute()
        ENDIF

    SipRegistrationStatus Function determineRegistrationStatusBasedOnPServedUser(callingPartyInvite)
        header = callingPartyInvite.getAddressHeader(P_SERVED_USER)
        IF header is null
        THEN
            return null
        ENDIF

        regState = header.getParameter(REGSTATE)
        IF regState not set
        THEN
            return null
        ENDIF

        IF regState is REG
        THEN
            return Registered
        ELSEIF regState is UNREG
        THEN
            return Unregistered
        ELSE
            return null

### Feature responses

Response | Reason
--- | ---
featureCannotStart | CallingParty leg InviteRequest has not been set
featureFailedToExecute | Registration status could not be determined
featureHasFinished | feature has finished

### Configuration

Determine Registration Status cannot be configured.

## Determine Service Type Feature

### Description

| This feature is a placeholder. The integrator will need to provide a feature which determines service type and sets the SipServiceType (one of Voice/Fax/Data/Video) session state field correctly in the context of the target network.

Feature name | DetermineServiceType
Applicable contexts | SIP service
SAS Support | No
Prerequisite Features | None

The Determine Service Type feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature classifies the call’s service Type, which is stored in a session state variable for future features.

### Service type

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

- Voice

- Video

- Data

- Fax.

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

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

### Feature responses

Response | Reason
--- | ---

### Configuration

#### Configuration Profile Naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable | Address list configuration | ${SELECTIONKEY}:ClassifyCallScenario:HomeVLR
${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable | Feature specific Address List entry table | ${SELECTIONKEY}:ClassifyCallScenario:HomeVLR:${ADDRESS}

## Determine if Roaming Feature

### Description

Feature name | DetermineIfRoaming
Applicable contexts | SIP service
SAS Support | No
Prerequisite Features | None

The Determine If Roaming feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature sets the call’s Roaming Indicator, which is stored in a session state variable for future features. The DetermineIfRoaming feature analyses the `p-visited-network-id` header and compares it with the platforms set of home network ids.

### Leg Manager inputs

Leg | Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | --- | ---
callingParty | InviteRequest | org.jainslee.resources.sip.SipRequest | See Easysip javadoc | INVITE received from the calling party | Runtime exception handled by feature runner

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting the Home Network IDs to determine RoamingIndicator \ | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
RoamingIndicator | java.lang.Boolean | True: Roaming, False:NotRoaming | Roaming status indicator

### Feature responses

Response | Reason
--- | ---
featureCannotStart | SessionState SentinelSelectionKey is not set or CallingParty leg InviteRequest has not been set
featureFailedToExecute | Roaming status could not be determined
featureHasFinished | feature has finished

### Roaming indicator

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

- Roaming

- NotRoaming

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

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

    Function determineIfRoaming(callingPartyInvite)

        roamingIndicator = determineRoamingBasedOnPVisitedNetworkHeader(callingPartyInvite)

        IF roamingIndicator is null
        THEN
            roamingIndicator = determineRoamingBasedOnRecordRouteAnalysis(callingPartyInvite)
        ENDIF

        /* if that still didn't work report a feature error*/
        IF roamingIndicator is null
        THEN
            /* Roaming status could not be determined */
            featureFailedToExecute()
        ENDIF

    RoamingIndicator Function determineRoamingBasedOnPVisitedNetworkHeader(callingPartyInvite)

        headers = callingPartyInvite.getHeaders("p-visited-network-id")
        IF header is null
        THEN
            return null
        ENDIF

        /* assumes all values are the same (RFC3455 says 'hopefully' they are!)
         * so just take the first one
         */
        visitedNetworkID = headers.next()

        List<String> homeNetworkIDs = getSessionState().getSentinelSelectionKey().getHomeNetworkIDs();

        IF homeNetworkIDs contain visitedNetworkIDs THEN
           return false
        ENDIF

        return true

    /* Roaming based on record route anaylsis is NOT fully implemented.  However it will affect the
     * setting of the roaming indicator, so it is included here for completeness.
     */
    RoamingIndicator Function determineRoamingBasedOnRecordRouteAnalysis(callingPartyInvite)

           headers = callingPartyInvite.getAddressHeaders(RecordRouteHeader.NAME);
           IF SipParseException THEN
               TRACE "Unable to parse. Interpreting call as non-roaming.")
               return false
           ENDIF

           IF headers is null OR headers is empty {
                TRACE ("No header present: Interpreting call as non-roaming.");
                return false;
           ENDIF

           return null;

### Configuration Profile Naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SipSentinelConfigurationTable | Sentinel configuration table (profile configuration containing home network ids) | ${SELECTIONKEY}:homeNetworkIDs

## End Mid Session Feature

### Description

Feature name | EndMidSession
Applicable contexts | SIP Service
SAS Support | No
Prerequisite Features | None

Sentinel mid session feature to notify the Sentinel core to end the call. When notifying the core the cause code is determined according to the following pseudo-code:

        FUNCTION determineCauseCode()

            // an error set by another feature takes highest precedence
            cause = sessionState.getUserEndSessionCause()
            IF cause IS SET
                return cause

            // otherwise try to determine the release cause from the latest CCA
            cause = determineCauseFromCCA(sessionState.getLatestOcsAnswer())
            IF cause IS SET
                return cause

            // otherwise use a default
            return SipResponse.SC_FORBIDDEN

        FUNCTION determineCauseFromCCA(cca)

            //if there was no CCA, we cannot determine a code from there; CALL_REJECTED will be set
            if cca IS UNSET
                return null

            SWITCH (cca.getResultCode())
                CASE DiameterCcaResultCode.DIAMETER_USER_UNKNOWN
                    return SipResponse.SC_NOT_FOUND
                CASE DiameterCcaResultCode.DIAMETER_CREDIT_LIMIT_REACHED
                    return SipResponse.SC_PAYMENT_REQUIRED
                CASE DiameterResultCode.DIAMETER_SUCCESS
                    return determineCauseFromMscc(cca)
                DEFAULT
                    return SipResponse.SC_FORBIDDEN

Supports ‘sip_trigger’, ‘http_trigger’ and ‘sipcall’ session types.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SessionType | com.opencloud.sentinel.common.SessionType | One of: sip_trigger, http_trigger, sipcall | Session type of this call for choosing how to determine cause code from LatestOcsAnswer | Report featureFailedToExecute, featureHasFinished
UserEndSessionCause | Integer | Any release code | A pre-determined release cause | Attempt to determine cause from LatestOcsAnswer
LatestOcsAnswer | org.jainslee.resources.diameter.ro.types.CreditControlAnswer | Credit-Control-Answer | For determining release cause code if the UserReleaseCause is not set | Use default call release cause SC_FORBIDDEN

#### Outputs

This feature does not modify session state.

### Error scenarios

Scenario | Handling
--- | ---
SessionType is not supported | Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished
featureFailedToExecute | Invalid session type — trigger should be one of sip_trigger, http_trigger, or sipcall

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## End Session Feature

### Description

Feature name | EndSession
Applicable contexts | SIP service
SAS Support | No
Prerequisite Features | None

Sentinel initial trigger feature to notify the Sentinel core to end the call. Supports ‘sip_trigger’, ‘http_trigger’ and ‘sipcall’ session types. When notifying the core the cause code is determined according to the following pseudo-code:

        FUNCTION determineCauseCode()

            // an error set by another feature takes highest precedence
            cause = sessionState.getUserEndSessionCause()
            IF cause IS SET
                return cause

            // otherwise try to determine the release cause from the latest CCA
            cause = determineCauseFromCCA(sessionState.getLatestOcsAnswer())
            IF cause IS SET
                return cause

            // otherwise use a default
            return SipResponse.SC_FORBIDDEN

        FUNCTION determineCauseFromCCA(cca)

            //if there was no CCA, we cannot determine a code from there; CALL_REJECTED will be set
            if cca IS UNSET
                return null

            SWITCH (cca.getResultCode())
                CASE DiameterCcaResultCode.DIAMETER_USER_UNKNOWN
                    return SipResponse.SC_NOT_FOUND
                CASE DiameterCcaResultCode.DIAMETER_CREDIT_LIMIT_REACHED
                    return SipResponse.SC_PAYMENT_REQUIRED
                CASE DiameterResultCode.DIAMETER_SUCCESS
                    return determineCauseFromMscc(cca)
                DEFAULT
                    return SipResponse.SC_FORBIDDEN

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SessionType | com.opencloud.sentinel.common.SessionType | One of: sip_trigger, http_trigger, sipcall | Session type of this call for choosing how to determine cause code from LatestOcsAnswer | Report featureFailedToExecute, featureHasFinished
UserEndSessionCause | Integer | Any release code | A pre-determined release cause | Attempt to determine cause from LatestOcsAnswer
LatestOcsAnswer | org.jainslee.resources.diameter.ro.types.CreditControlAnswer | Credit-Control-Answer | For determining release cause code if the UserReleaseCause is not set | Use default call release cause SC_FORBIDDEN

#### Outputs

This feature does not modify session state.

#### Error scenarios

Scenario | Handling
--- | ---
SessionType is not supported | Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureFailedToExecute | Invalid session type
endSession Instruct | sentinel core to end the session and report cause
featureHasFinished | feature has finished

### Configuration

End Session cannot be configured.

## Reauthorize Credit Feature

### Description

Feature name | ReauthorizeCredit
Applicable contexts | SIP service
SAS Support | No
Prerequisite Features | None

Sentinel feature to notify the Sentinel Core to reauthorize credit post initial credit check. Used post-announcement where the rating may have changed due to the length of the announcement.

Sets the `ReauthorizeCreditAfterInitialCreditCheck` session state field to true.

### Session state inputs and outputs

#### Inputs

This feature does not read session state.

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
ReauthorizeCreditAfterInitialCreditCheck | boolean | true | Notify the sentinel core to reauthorize credit post initial credit check.

### Error scenarios

This feature always succeeds.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

This feature cannot be configured.

## SIP Determine Network Operator Feature

### Description

Feature name | SIPDetermineNetworkOperator
Applicable contexts | SIP service
SAS Support | No
Prerequisite Features | None

The SIP Determine Network Operator Feature sets the network operator element of the Sentinel selection key for use in the selection of: feature execution scripts, mappers, and address lists.

The feature will set the Network Operator element of the Sentinel selection key, based on the value returned by the DetermineNetworkOperator function below. This feature requires that the calling party SIP INVITE contains a ‘sentinel-network-operator’ header. If this header is not present, then the platform-configured default network operator is used.

### Leg Manager inputs

Leg | Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | --- | ---
calledParty | InviteRequest | org.jainslee.resources.sip.SipRequest | See Easysip javadoc | INVITE sent to the called party | Runtime exception handled by feature runner
callingParty | InviteRequest | org.jainslee.resources.sip.SipRequest | See Easysip javadoc | INVITE received from the calling party | Runtime exception handled by feature runner

### SIP headers

#### Inputs

Name | Format | Description | Behaviour if absent
--- | --- | --- | ---
sentinel-network-operator | String | Header indicating which network operator to select use | Use default network operator.

### Session state

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data and updating network operator field | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>:<network>:::`) | Only updated if network operator is determined

### Error scenarios

Scenario | Handling
--- | ---
No calling party available | Report featureCannotStart (invalid session state)
No called party available | Report featureCannotStart (invalid session state)
Sessionstate SentinelSelectionKey is null | Report featureCannotStart (invalid session state)
“sentinel-network-operator” SIP header present but empty | Increment CouldNotDetermineNetworkOperator, continue executing.
No “sentinel-network-operator” header, and default network operator could not be determined | Report featureFailedToExecute (invalid configuration)

### Feature responses

Response | Reason
--- | ---
featureCannotStart | Missing called or calling party, missing SentinelSelectionKey, “sentinel-network-operator” SIP header present but empty, or SessionState SentinelSelectionKey is not set.
featureHasFinished | Feature has finished

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SentinelConfigurationTable | Sentinel configuration table (contains DefaultNetworkOperator) | SentinelConfiguration

## SIP Mid Session Play Announcement Feature

The SipMidCallPlayAnnouncement feature plays a queue of announcements to the configured party during mid session.

### Details

Feature script name | SipMidCallPlayAnnouncement
Applicable contexts | SIP service
SAS Support | Yes
Prerequisite Features | Any feature setting the MidCallAnnouncementInfoQueue session state field and any feature that sets the LanguageConfig session state field, like Sip Set Language Feature feature.
Typical feature execution points | SipAccess_ServiceTimer, SipAccess_PartyResponse, SipMidSession_PartyRequest, SipMidSession_PartyResponse, and any other mid-session execution point where an announcement may be desired, such as SipMidSession_CreditLimitReached.
Timer usage | Execution-point targeted timer will trigger the feature at the SipAccess_ServiceTimer execution point on expiry.

The announcements are played by the MRF. The announcements to play are queued in the MidCallAnnouncementInfoQueue session state as SipAnnouncementInformation objects each with an announcement ID. The announcement may have an associated language otherwise the LanguageConfig session variable is used. If the MidCallAnnouncementInfoQueue is empty or null then the MidCallAnnouncementID session variable is used. If the MidCallAnnouncementID session variable is not set, the MidCallAnnouncementQueue is checked. If the MidCallAnnouncementQueue is empty or null then the feature returns without error or side effect to the dialog.

Another feature must be executed prior to the SipMidCallPlayAnnouncement feature to set the LanguageConfig and the MidcallAnnouncementId or queue.

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

The LanguageConfig String is a language code in RFC 3066 format. Use of the LanguageConfig session state field is optional. The feature will search for a profile using the LanguageConfig and MidcallAnnouncementId as keys. If the feature can’t find a profile for the specified language, it will search for a profile just using the MidcallAnnouncementId.

If there are multiple announcements scheduled in the MidCallAnnouncementInfoQueue, each announcement will be attempted on a new MRF dialog when each previous announcement completes (whether or not it played successfully). Each subsequent announcement necessitates sending another Re-INVITE to the calling party. If the MRF times out at any point, the MRF session will be torn down appropriately and the call will proceed as normal including queued announcements (or be ended, as in the above scenario).

### 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, `<platform>::::`) | For selecting configuration data | Increment InputParameterErrors Common cleanup actions
SDP | String | Text | Session description | Outgoing request will not contain SDP
LanguageConfig | String | An optional String input containing a language code. The RFC 3066 defines language codes, but the feature does not validate the format. | The value of this fields will be used to get the proper announcement profile. Default is null. | If null the profile search will not consider the language
MidCallAnnouncementInfoQueue | List<SipAnnouncementInformation> | List of SipAnnouncementInformation | List of announcements to play | Check for MidcallAnnouncementId
MidcallAnnouncementId | Integer | Non-negative | ID of the announcement to be played — 0 indicates no announcement to play Increment InvalidAnnouncementIDs (deprecated) | Check the announcement queue
MidCallAnnouncementQueue | List<Integer> | Non-negative | ID of the announcements to be played (deprecated) | Report featureHasFinished
PlayedAnnouncementIDs | int[] | List of announcement IDs | Announcements which have already been played | Initialized to an empty array
PAShouldEndSessionWhenFinished | boolean | Indicates whether the feature will call `endSession` when finished playing all announcements (deprecated) | Default is false |
MidCallEndSessionWithAnnouncement | boolean | Indicates whether the feature will call `endSession` when finished playing all announcements (replaces `PAShouldEndSessionWhenFinished`) | Default is false |
MidCallAnnouncementPlayedParty | String | Leg name indicating which party the announcement will be played to | Linked leg will be passivated during announcement (deprecated) | Play to callingParty
RequestIsResume | boolean | Indicates whether the current request is a resume. Set by other features to be read by this one. | Default is false |

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
MidCallAnnouncementInProgress | SipAnnouncementInformation |  | The announcement currently in progress, null if no announcement is in progress.
PlayedAnnouncementIDs | int[] | List of announcement IDs | Updated with each announcement ID the feature is invoked to play
PAShouldEndSessionWhenFinished | boolean |  | Set to true if the feature is invoked in the CreditLimitReached execution point. Can be cleared by a subsequent feature

### Error scenarios

Scenario | Handling
--- | ---
Null sessionstate MidcallAnnouncementId | Increment MissingAnnouncementIDs Finish
MidcallAnnouncementId session state field is ⇐ 0 | Increment InvalidAnnouncementIDs Finish
Null sessionstate SentinelSelectionKey | Increment InputParameterErrors Common cleanup actions
ACI not provided to the announcement feature | Increment InputParameterErrors Common cleanup actions
SipSession object not provided to the announcement feature in the activity context interface | Increment InputParameterErrors Common cleanup actions
Announcement properties not found for announcement ID | Increment InputParameterErrors Common cleanup actions
Announcement resource config not found for resource config ID | Increment ConfigurationErrors Common cleanup actions
Failed to send INVITE to Media Server | Increment SipSendErrors Common cleanup actions
Error received from MRF on Invite | Send Ack with Rejection to played party Increment SipErrors Re-invite passive party to resume call if leg not already released Common cleanup actions
Error received from MRF on Cancel due to played party BYE | Increment SipErrors Release passive party leg Common cleanup actions
MediaServer response timeout to INVITE | Send Ack with Rejection to played party Increment SipErrors Send Cancel to MRF Re-invite passive party to resume call if leg not already released Common cleanup actions
MediaServer response timeout to Cancel | Increment SipErrors Send Cancel to MRF Release passive party leg Common cleanup actions
Failed to send 200 Prack response | Increment SipSendErrors Report end Session with 500 ServerError to Sip Sentinel core
Failed to send ACK to MRF | Increment SipSendErrors Common cleanup actions
Failed to send BYE to MRF | Increment SipSendErrors Common cleanup actions
Failed to send CANCEL to MRF | Common cleanup actions
Failed to send 183 response due to unable to access INVITE from SIPSession | Increment InputParameterErrors Send ACK to MRF Cancel NoResponseTimer Send Bye to MRF Common cleanup actions
Failed to send 183 response | Increment SipSendErrors Cancel NoResponseTimer Send Bye to MRF Common cleanup actions

#### Common cleanup actions

Here are some common cleanup actions:

- If a BYE was received from the played or passive party during the feature, release the other party as well as the MRF leg.

- If both parties are still present, re-link the legs for B2BUA behaviour.

- Cancel the NoResponseTimer.

- Release the MRF Leg (may have been done already).

- Increment FeatureFSMCompletions.

- If the PAShouldEndSessionWhenFinished session state field is true, call endSession.

- Finish.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Announcement configuration

Announcements are referenced by ID. The following table shows configuration parameters for provisioning them.

Parameter | Type | Description
--- | --- | ---
Description | String | Description of the announcement
Id | String | Announcement id (number) plus optional language (eg. 20:en_NZ)
AnnouncementURL | String | URL of the announcement
Delay | Integer | Delay interval between announcement repetitions (in ms)
Duration | Integer | Maximum duration of the announcement (in ms)
Locale | String | Locale of the announcement as a string
MimeType | String | MimeType of the announcement as a string
Repeat | Integer | How many times the media server should repeat the announcement. (-1 means 'forever')
ResourceConfig | String | Name of the profile holding the media resource configuration
SuspendCharging | Boolean | True if charging is suspended during the announcement (only applies to Mid Call Announcements)
Interruptable | Boolean | True if the announcement is interruptable (only applies to Mid Call Announcements)
EnforceOneWayMedia | Boolean | True if media should be unidirectional from the MRF to the played party for the announcement. The feature will modify SDP directionality attributes between the MRF and played party to do this. (only applies to Mid Call Announcements)

#### Example

Here is an example announcement table configuration:

ID | Description | AnnouncementURL | Delay | Duration | Locale | MimeType | Repeat | ResourceConfig | SuspendCharging | Interruptable | EnforceOneWayMedia
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
15 | Play message "You have insufficient credit to make this call" | file:msg_15.wav | 0 | 4000 | en | audio/vnd.wave | 0 | default | true | false | false
17 | Play tone | file://cts71/annc/CallWaitingReactive.wav | 500 | 100 |  | audio/vnd.wave | 2 | default | false | false | false

The `ResourceConfig` is a reference by `ResourceId` to an entry in the Resource Configuration table with the resource configuration.

### Resource configuration

Parameter | Type | Description
--- | --- | ---
ResourceId | String | ID of this resource configuration Used by the announcement configuration profile to reference this configuration
MediaServerURI | String | The configured value for the media server URI
RouteDirectToResource | Boolean | The configured value for the route direct to resource If true, the service sends the Play Announcement INVITE directly to the media server (using Request URI) (values: true or false)
ServiceParameterType | String | The configured value for the service parameter type (for example, play, voicexml)
NoResponseTimeout | Long | The configured number of milliseconds that Sentinel will wait for the MRF to send a response to the INVITE or CANCEL
ICSCFURI | String | The configured value for the I-CSCF URI which is used put in the ROUTE header if RouteDirectToResource is false

#### Example

Here is an example resource configuration profile:

ResourceId | MediaServerURI | RouteDirectToResource | ServiceParameterType | NoResponseTimeout | ICSCFURI | default
--- | --- | --- | --- | --- | --- | ---
sip:annc-audio@localhost:5260;lr;transport=tcp | true | play | 1000 | icscfhost:5054 | voice | sip:dialog@mediaserver:5061;lr;transport=udp

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SipAnnouncementProfileTable | Announcement configuration profiles | SentinelSelectionKey:id (for example, `OpenCloud::::15`)
SipAnnouncementProfileTable | Announcement configuration profiles | SentinelSelectionKey:id:language (for example, `OpenCloud::::15:en-NZ`)
SipAnnouncementResourceConfigProfileTable | Announcement resource addresses and other resource configuration data | SentinelSelectionKey:resourceConfigName (for example, `OpenCloud::::voice`)

## SIP Normalization Feature

### Description

Feature script name | SipNormalization
Applicable contexts | SIP service session
SAS Support | Yes
Prerequisite Features | SipPrefixAndSuffixAnalysis— where required

The SIP Normalization feature normalizes the request-URI and other select address headers in the received INVITE request.

The `SipNormalization` uses the Normalization Component to normalize:

- `request URI`

- `From` address

- `To` address

- `P-Asserted-Id` address (if present)

- `P-Served-User` address (if present).

| The SipNormalization feature will only do analysis of an address if: the address is a tel URL the address is a SIP URI, where the user part of the URI is a digit string. Addresses may contain the digits allowed in a global phone number as per RFC 2806.

### Leg Manager Inputs

Leg | Name | Type | Format | Description | Behaviour if null/invalid
calledParty | InviteRequest | org.jainslee.resources.sip.SipRequest | See Easysip Javadoc | INVITE sent to the called party | Runtime exception handled by feature runner

| The Called Party `INVITE` request is fetched from the called party leg via the LegManager API. The Called Party `INVITE` request is updated via the LegManager API.

### Session state and leg inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | Selection key (for example, `<platform>::::`) | For configuring normalizer | Runtime exception handled by feature runner
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call | Report featureCannotStart, featureHasFinished

### Error scenarios

Scenario | Handling
--- | ---
Sessionstate selection key is null | Report featureCannotStart
Error during number normalization | Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureCannotStart | Sessionstate selection key is null
featureFailedToExecute | Error during number normalization
featureHasFinished | feature has finished

### Configuration

See Normalization Component.

### Configuration profile naming

See Normalization Component.

### Provisioning interfaces

See Normalization Component.

## SIP Play Announcement Feature

The SipPlayAnnouncement feature plays a queue of announcements to the calling party during call establishment.

### Description

Feature script name | SipPlayAnnouncement
Applicable contexts | SIP service
SAS Support | Yes
Prerequisite features | Any feature setting the EarlyMediaAnnouncementInfoQueue session state field and any feature that sets the LanguageConfig session state field, like Sip Set Language Feature feature.
Typical feature execution points | SipAccess_PartyResponse, SipAccess_PartyRequest, SipMidSession_PartyResponse, SipMidSession_PartyRequest, SipAccess_ServiceTimer, and any SipAccess execution points where an announcement may be triggered, such as SipAccess_SubscriberCheck.
Timer usage | Execution-point targeted timer will trigger the feature at the SipAccess_ServiceTimer execution point on expiry.

The announcement is played by the MRF. The announcements to play are queued in the EarlyMediaAnnouncementInfoQueue session state as SipAnnouncementInformation objects each with an announcement ID. The announcement may have an associated language otherwise the LanguageConfig session variable is used. If the EarlyMediaAnnouncementInfoQueue is empty or null then the AnnouncementID session variable is used. If the AnnouncementID session variable is not set, the EarlyMediaAnnouncementQueue is checked. If the EarlyMediaAnnouncementQueue is empty or null then the feature returns without error or side effect to the dialog.

Another feature must be executed prior to the SipPlayAnnouncement feature to set the EarlyMediaAnnouncementInfoQueue and the LanguageConfig.

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

The LanguageConfig String is a language code in RFC 3066 format. Use of the LanguageConfig session state field is optional. The feature will search for a profile using the LanguageConfig and AnnouncementID as keys. If the feature can’t find a profile for the specified language, it will search for a profile just using the AnnouncementID as key.

The SipPlayAnnouncement feature supports UE preconditions if present.

### Example Callflows

#### Play Announcement without Preconditions - OCS Rejects Call

In this scenario, the CCA-I returns with result code 4012 (credit limit reached); and a feature setting the EndSessionAfterAnnouncement session state field to a non-zero value is installed in the SipAccess_CreditLimitReached execution point and runs before PlayAnnouncement, which is also installed in the same execution point. B-Party is never contacted.

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.

#### Early media play announcement with preconditions not on MRF

In this scenario, the MRF does not support preconditions.

The call case is a Barring Announcement UE with preconditions supported, resources not initially available.

### Leg Manager inputs

Leg | Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | --- | ---
callingParty | InviteRequest | org.jainslee.resources.sip.SipRequest | See Easysip javadoc | INVITE received from (respectively, in the NetworkInitiated case, sent to) the calling party | Runtime exception handled by feature runner

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::` ) | For selecting configuration data | Increment InputParameterErrors Common cleanup actions
SDP | String | Text | Session description | Outgoing request will not contain SDP
EarlyMediaAnnouncementInfoQueue | SipAnnouncementInfo | non-negative | A list of announcements to be played in order. Each announcement specifies an ID and optionally a language to use. | Check the AnnouncementID and EarlyMediaAnnouncementQueue for further announcements to play.
AnnouncementID | Integer | non-negative | ID of the announcement to be played — 0, negative values and `null` indicate no announcement to play | Poll the `EarlyMediaAnnouncementQueue`
EarlyMediaAnnouncementQueue | List<Integer> | A list of positive integers | A list of IDs of the subsequent announcements to be played — entries such as `0`, `null` or negative values will be ignored. The AnnouncementID field takes priority over the queue. The element at index `0` will always be treated as the head of the queue. (deprecated) | If the queue itself is null, report featureHasFinished. If one of the entries is null or invalid, increment InvalidAnnouncementIDs and play the next one in the queue.
PlayedAnnouncementIDs | int[] | List of announcement IDs | Announcements which have already been played | Initialized to an empty array
EndSessionAfterAnnouncement | int | The feature will call endSession with the provided error code upon completion if non-zero | Default value is 0 — does not end session |
LanguageConfig | String | The RFC 3066 defines language formats, but the feature does not validates the format. | The feature will use the LanguageConfig supplied by the session state field as an input and use it to retrieve the proper announcement profile. | The default value is null, a null value runs the default profile without language configuration.

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
PlayedAnnouncementIDs | int[] | List of announcement IDs | Updated with each announcement ID the feature is invoked to play
EarlyMediaAnnouncementInProgress | SipAnnouncementInformation | Object | Set to the current announcement in progress. Null if no announcement is in progress.

### Error scenarios

Scenario | Handling
--- | ---
Null, negative or 0 found in EarlyMediaAnnouncementQueue | Increment InvalidAnnouncementIDs + retrieve next entry
Null sessionstate SentinelSelectionKey | Increment InputParameterErrors Common cleanup actions
ACI not provided to the announcement feature | Increment InputParameterErrors Common cleanup actions
SipSession object not provided to the announcement feature in the activity context interface | Increment InputParameterErrors Common cleanup actions
Announcement properties not found for announcement | Increment InputParameterErrors Common cleanup actions
Announcement resource config not found for resource config ID | Increment ConfigurationErrors Common cleanup actions
Failed to send INVITE to Media Server | Increment SipSendErrors Common cleanup actions
Error received from MRF | Increment SipErrors Common cleanup actions
MediaServer response timeout | Increment SipErrors Common cleanup actions
Failed to send 200 Prack response | Increment SipSendErrors
Report end Session with 500 | ServerError to SIP Sentinel core
Failed to send ACK to MRF | Increment SipSendErrors Common cleanup actions
Failed to send BYE to MRF | Increment SipSendErrors Common cleanup actions
Failed to send CANCEL to MRF | Common cleanup actions
Failed to send 183 response due to unable to access INVITE from SIPSession | Increment InputParameterErrors Send ACK to MRF Common cleanup actions
Failed to send 183 response | Increment SipSendErrors Common cleanup actions

Common cleanup actions: | Cancel NoResponseTimer Release MRF Leg End session if End Session Flag is set or if announcement is configured with `EndSessionOnFailure` set to true Increment FeatureFSMCompletions Finish

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Announcement configuration

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

Parameter | Type | Description
--- | --- | ---
Description | String | Description of the announcement
Id | String | Announcement id (number) plus optional language (eg. 20:en_NZ)
AnnouncementURL | String | URL of the Announcement
Delay | Integer | Delay interval between announcement repetitions (in ms)
Duration | Integer | Maximum duration of the announcement (in ms)
Locale | String | Locale of the Announcement as a string
MimeType | String | MimeType of the Announcement as a string
Repeat | Integer | How many times the media server should repeat the announcement. (-1 means 'forever')
ResourceConfig | String | Name of the profile hold the media resource configuration
SuspendCharging | Boolean | True if charging is suspended during the announcement. (Only applies to Mid Call Announcements)
Interruptable | Boolean | True if the announcement is interruptable. (Only applies to Mid Call Announcements)
EndSessionOnFailure | Boolean | True if the call should be ended if this announcement fails to play. (Only applies to Early Media Announcements)
EnforceOneWayMedia | Boolean | True if media should be unidirectional from the MRF to the played party for the announcement. The feature will modify SDP directionality attributes between the MRF and played party to do this. (only applies to Mid Call Announcements)

Example announcement table configuration:

ID | Description | AnnouncementURL | Delay | Duration | Locale | MimeType | Repeat | ResourceConfig | SuspendCharging | Interruptable | EnforceOneWayMedia
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
15 | Play message "You have insufficient credit to make this call" | file:msg_15.wav | 0 | 4000 | en | audio/vnd.wave | 0 | default | true | false | false
17 | Play tone | file://cts71/annc/CallWaitingReactive.wav | 500 | 100 |  | audio/vnd.wave | 2 | default | false | false | false

The `ResourceConfig` is a reference by `ResourceId` to an entry in the Resource Configuration table with the resource configuration.

### Resource configuration

Parameter | Type | Description
--- | --- | ---
ResourceId | String | Id of this resource configuration. It is used by the announcement configuration profile to reference this configuration.
MediaServerURI | String | The configured value for the media server URI
RouteDirectToResource | Boolean | The configured value for the route direct to resource. If true, the service sends the Play Announcement INVITE directly to the media server (i.e. using Request URI) (values: true or false)
ServiceParameterType | String | The configured value for the service parameter type e.g. play, voicexml
NoResponseTimeout | Long | The configured number of milliseconds that Sentinel will wait for the MRF to send a response to the INVITE.
ICSCFURI | String | The configured value for the I-CSCF URI which is used put in the ROUTE header if RouteDirectToResource is false.

Example resource configuration profile:

ResourceId | MediaServerURI | RouteDirectToResource | ServiceParameterType | NoResponseTimeout | ICSCFURI
--- | --- | --- | --- | --- | ---
default | sip:annc-audio@localhost:5260;lr;transport=tcp | true | play | 1000 | icscfhost:5054
voice | sip:dialog@mediaserver:5061;lr;transport=udp | true | voicexml | 1000 | icscfhost:5054

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SipAnnouncementProfileTable | Announcement configuration profiles | SentinelSelectionKey:id (for example, `OpenCloud::::15`)
SipAnnouncementProfileTable | Announcement configuration profiles | SentinelSelectionKey:id (for example, `OpenCloud::::15:en-NZ`)
SipAnnouncementResourceConfigProfileTable | Announcement resource addresses and other resource configuration data | SentinelSelectionKey:resourceConfigName (for example, `OpenCloud::::voice`)

### Provisioning interfaces

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

## SIP Prefix and Suffix Analysis Feature

### Description

Feature name | SipPrefixAndSuffixAnalysis
Applicable contexts | SIP Service
SAS Support | No
Prerequisite features | Determine Call Type Feature

The SIP prefix and suffix analysis feature performs prefix and suffix digit analysis on the request-URI of the received INVITE request.

| The `SipPrefixAndSuffixAnalysis` feature will only do analysis if; the `request-URI` is a `tel URL` the `request-URI` is a `SIP URI`, where the user part of the URI is a digit string. Addresses may contain the digits allowed in a global phone number as per RFC 2806.

Sentinel has a set of configurable prefix and suffix address lists, scoped by Sentinel selection key, which are used for this digit analysis.

- If a prefix or suffix matches an address in the request-URI, then the directive associated with the prefix (or suffix) is applied.

  - The directives are: `strip` prefix/suffix or `retain` prefix/suffix, and set session parameter with configured value.

- If the directive is `strip`, then the request-URI is updated in the outgoing `INVITE`.

| The `SipPrefixAndSuffixAnalysis` feature will not do any analysis if the `CallType` is `EmergencyCall` or `MobileTerminating`. Subsequent features may make additional changes to the `request URI`, so the final address sent in the `INVITE` will be dependent on those features.

Parameter | Description
--- | ---
Address | Prefix or suffix to match
Description |
ListId | ${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialPrefixList ${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialSuffixList
ParameterName | Session state field to set (for example, `AnnouncementID`). Field name is in Java identifier format, and follows the rules of Java identifiers (such as not being a Java keyword).
ParameterType | boolean, integer, long, string
ParameterValue | Value to write to session state. Must be formatted correctly for the value specified in the Parameter Type field
PrefixDirective | strip, retain

Example of prefix analysis configuration:

Prefix/suffix address | Directive | Session Parameter | Parameter Type | Parameter Value | Description
--- | --- | --- | --- | --- | ---
1234 | STRIP | CLI | String | SUPPRESS |
555 | STRIP | TARIFF | String | Cheap-International-Calling |
*591 | STRIP | PROFILE | Integer | 1 | Profile selection
*592 | STRIP | PROFILE | Integer | 2 | Profile selection
*593 | STRIP | PROFILE | Integer | 3 | Profile selection
*594 | STRIP | PROFILE | Integer | 4 | Profile selection
. | STRIP |  |  |  | Strip ST (end of pulsing) digit

| 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 `INVITE` request is fetched from the called party Leg via the `LegManager API`. The Called Party `INVITE` request is updated via the `LegManager API`.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call for determining whether to analyse the INVITE | Report featureCannotStart, featureHasFinished

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
Other session state fields | see Description | see Description | This feature can update other session state fields according to configuration data when a prefix or suffix match is found

### Error scenarios

Scenario | Handling
--- | ---
Sessionstate SentinelSelectionKey is null | Report featureCannotStart
Attempt to set non-existent SessionState parameter | Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureCannotStart | SessionState SentinelSelectionKey is not set
featureFailedToExecute | Attempt to set non-existent SessionState parameter
featureHasFinished | feature has finished

### Configuration

Prefix and Suffix Analysis uses Sentinel AddressLists for configuration data. See Address Lists on how to provide the configuration data.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
${PLATFORMOPERATOR}_PrefixAndSuffixAnalysisFeature_AddressListConfigurationTable | Address list configuration | ${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialPrefixList or ${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialSuffixList
${PLATFORMOPERATOR}_PrefixAndSuffixAnalysisFeature_AddressListEntryTable | Feature specific Address List entry table | ${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialPrefixList:${ADDRESS} or ${SELECTIONKEY}:SipPrefixAndSuffixAnalysis:SipSpecialSuffixList:${ADDRESS}

| 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
SAS Support | Yes
Prerequisite features | Classify Call Scenario Feature

The Short Code feature is a pre-credit check feature that performs number translation of short-codes in the `request-URI` of the received `INVITE` request. If the `request-URI` does include a short-code, then `SipShortCode` updates the `request-URI` and `To` addresses in the received `INVITE`, using a short-code translation table.

| The SipShortCode feature will only do analysis if: the `request-URI` is a `tel URL` the `request-URI` is a `SIP URI`, where the user part of the URI is a digit string. Addresses may contain the digits allowed in a global phone number as per RFC 2806.

If the number is in international format and is prefixed by the home country code then the prefix will be removed before performing analysis. The feature makes use of the Normalization Component to remove the prefix.

If the number is in international format and is not prefixed by the home country code then no analysis will be performed.

Sentinel has a configurable short-code address list, scoped by the Sentinel selection key, which is used for this digit analysis. If a short-code matches an address in the `request-URI`, then both the `request-URI` and the `To` address are updated with a translated address (that corresponds to the short-code).

| The `SipShortCode` feature will not do any analysis if the `CallType` is `EmergencyCall` or `MobileTerminating`. Subsequent features may make additional changes to the request URI, so the final address sent in the `INVITE` will be dependent on those features.

### Leg Manager inputs

Leg | Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | --- | ---
calledParty | InviteRequest | org.jainslee.resources.sip.SipRequest | See the EasySIP javadoc | INVITE sent to the called party | Runtime exception handled by feature runner

| The Called Party `INVITE` request is fetched from the called party Leg via the `LegManager` API. The Called Party `INVITE` request is updated via the `LegManager` API.

### Session State and Leg inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | Report featureCannotStart, featureHasFinished
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call | Throw runtime exception, report featureHasFinished

### Error scenarios

Scenario | Handling
--- | ---
Sessionstate SentinelSelectionKey is null | Report featureCannotStart
Called Party Leg is null | Throw runtime exception Report featureHasFinished
Called Party Invite Request is null | Throw runtime exception Report featureHasFinished
Sessionstate CallType is null | Throw runtime exception Report featureHasFinished

### Feature responses

Response | Reason
--- | ---
featureCannotStart | SessionState SentinelSelectionKey is not set
featureHasFinished | feature has finished

### Configuration

#### Short Code feature configuration

Parameters | Type | Description
--- | --- | ---
MinLength | Integer | Minimum short code length
MaxLength | Integer | Maximum short code length

Example configuration:

MinLength | MaxLength
--- | ---
3 | 3

#### Short Code address list configuration

The `SipShortCode` address list entry is an extension of the standard Address list entry, the addition being the ‘translatedAddress’ field which is used for number translation:

Parameter | Type | Description
--- | --- | ---
…​ | …​ | …​
TranslatedAddress | String | the value of the short code translated address (in international format)

Example configuration:

Address | TranslatedAddress
--- | ---
100 | 6422987654
200 | 6422123456

The `SipShortCode` address is a digit string which can contain any digits valid for the network.

TranslatedAddress is a digit string in international format.

The short code list applies to all subscribers scoped to Sentinel selection key.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
ShortCodeFeatureConfigProfileTable | Short code feature configuration | SentinelSelectionKey (for example, `OpenCloud::::`)
${PLATFORMOPERATOR}_SipShortCode_AddressListConfigurationTable | Address list configuration | ${SELECTIONKEY}:SipShortCode:SipShortCodeAddressList
${PLATFORMOPERATOR}_SipShortCode_AddressListEntryTable | Feature specific Address List entry table | ${SELECTIONKEY}:SipShortCode:SipShortCodeAddressList:${ADDRESS}

| The SipShortCode feature address list configuration uses the same profile tables as the SS7 version of the feature. The names of the address lists are, however, particular to the SipShortCode feature.

#### Normalization Configuration

See Normalization Component.

### Provisioning interfaces

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

### Statistics

Name | Description
--- | ---
ShortCodeTranslated | Counter incremented when a short code is translated.
InternationalNumberIgnored | Counter incremented when a number is ignored as it is international and not prefixed by the home country code.
StrippedHomeCountryCode | Counter incremented when the home country code prefix is removed from a number before attempting analysis.

## SIP Subscriber Determination Feature

### Description

Feature name | SubscriberDetermination
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | DetermineCallType

The Subscriber Determination feature is a pre credit check feature early in the feature list (but always after the emergency number feature). The feature inspects the SIP INVITE to determine the subscriber address for this session and set the Subscriber session state field.

It determines the subscriber address either by:

- returning the value already stored in the Subscriber session state field; otherwise

- returning the value of the P-Served-User header (if that header is present); otherwise

- analysing the FROM or RequestURI headers, depending on the call type:

  - moc: subscriber address is the URI in the FROM header

  - mtc: subscriber address is the URI in the RequestURI header

  - networkinitiated: subscriber address is the URI in the FROM header

The feature will string the parameters from the URIs in case some is present.

### Leg Manager inputs

Leg | Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | --- | ---
calledParty | InviteRequest | org.jainslee.resources.sip.SipRequest | See EasySIP javadoc | The invite to be sent to the called party | Runtime exception handled by feature runner

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
CallType | com.opencloud.sentinel.common.CallType | One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall | Session type of this call | Subscriber will not be determined unless it can be determined from PServedUserHeader
Subscriber | String | SIP URI | Check the subscriber is not already set before proceeding | Subscriber determination will take place

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
Subscriber | String | SIP URI | The subscriber address

### Error scenarios

Scenario | Handling
--- | ---
Called Party leg Invite Request is null or does not contain Subscriber address | Report featureFailedToExecute

### Feature responses

Response | Reason
--- | ---
featureFailedToExecute | Invalid subscriber, if the feature was unable to determine any sensible subscriber address in any of the above ways
featureHasFinished | feature has finished

### Configuration

This feature cannot be configured.

## SIP Third Party Call Setup Feature

The SIP Third Party Call Setup feature manages the actual call setup and SDP negotiation

### Details

Feature name | SipThirdPartyCallSetup
Applicable contexts | SIP service
SAS Support | No
Typical feature execution points | SipThirdPartyAccess_SubscriberCheck, SipAccess_CreditAllocatedPostCC, SipAccess_ControlNotRequiredPostCC, SipAccess_PartyRequest, SipAccess_PartyResponse, SipAccess_ServiceTimer, SubscriptionSipRequest, SipMidSession_PartyResponse
Prerequisite Features | SIP Third Party HTTP Trigger Feature
Timer usage | Execution-point targeted timer will trigger the feature at the SipAccess_ServiceTimer execution point on expiry.

The SIP Third Party Call Setup feature:

1. First unlinks the legs created by SIP Third Party HTTP Trigger Feature.

2. Starts to set up the call.

3. The setup begins with A party negotiation.

4. When it receives a positive answer from the A party, the feature start negotiation with the B party, using the SDP received from the A party.

5. The call will be established if a positive answer was received from the B party.
   Otherwise the call setup fails.

| The SIP Third Party Call Setup feature can also be used to provide Third Party Call Control (3pcc) functionality for other services.

### Example call flows

Sentinel starts a call setup on valid HTTP requests from the SIP Third Party HTTP Trigger Feature. Below are examples of these call flows: successful; and A party busy, B party busy, and A party disconnects before B party answers failures.

#### Successful call setup flow

This call flow represents a successful call setup. The B party accepts the SDP offer. Sentinel sends an ACK message to the A party with the SDP answer received from the B party.

#### A party busy failure flow

This flow represents a case where the A party is busy.

#### B party busy failure flow

This flow represents a case where the B party is busy.

#### A party disconnects before B party answers failure flow

This flow represents a case where the A party disconnects before the B party answers.

### Session state inputs and outputs

#### Inputs

Name | Type | Format | Description
--- | --- | --- | ---
APartyLegName | String | Text | A party leg name
BPartyLegName | String | Text | B party leg name
PreserveSessionOnAPartyFailureResponse | boolean | `true` or `false` | Determines if the feature should end or preserve the SIP session if the A Party responds with a failure response.
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key for example: `<platform>::::` | For selecting configuration data

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
CallEstablished | Boolean | `true` or `false` | Sets true if the session has been established.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

See under SIP Third Party Call Configuration. The only parameter used by this feature is `NoAnswerApplicationTimer`.

### Statistics

Name | Description
--- | ---
FailedToSetupCall | Counter incremented when failed to setup the call.
CallEstablished | Counter incrremented when successfully setup the call.

## SIP Third Party HTTP Trigger Feature

THe SIP Third Party HTTP Trigger feature processes an HTTP request, creates the A and B party legs, and maps the HTTP request to SIP INVITE messages.

### Details

Feature name | SipThirdPartyHttpTrigger
Applicable contexts | SIP service
SAS Support | No
Prerequisite Features | N/A
Typical feature execution points | SipThirdPartyAccess_SessionAccept, SipThirdPartyAccess_SubscriberCheck, SipAccess_CreditAllocatedPostCC, SipAccess_ControlNotRequiredPostCC, SipEndSession

### Processing HTTP requests

The SIP Service accepts HTTP requests in the following format:

    http://<host>:<port>/sentinel-sip?subscriber=447408800855&cgpn=642200001&cdpn=642200002

The feature checks for presence of the `subscriber`, `cgpn`, and `cdpn` request parameters. If all parameters are available, the feature creates the suspended legs with the initial INVITE messages, according to the parameters from the HTTP request and feature configuration. The legs after creation are suspended and linked.

If the feature is being used in an uncharged scenario, it should run in the `SipThirdPartyAccess_SubscriberCheck` script in order to trigger the sending of an HTTP 200 (callIsBeingSetup) response without waiting for a CCA. In a charged scenario, it should not run in `SipThirdPartyAccess_SubscriberCheck`, to ensure that it waits for a success CCA before sending the response. See Configuration for an example of configuring the script to cover both cases.

### Example Call Flows

#### Successful flow

This call flow shows a case when Sentinel receives valid HTTP request. Sentinel responds with 200 OK with `callIsBeingSetup` in the message body.

#### Invalid HTTP request

This call flow shows a case when Sentinel receives invalid HTTP request. The request is invalid if any of required HTTP request parameters `subscriber`, `cgpn` or `cdpn` is missing. Sentinel responds with 200 OK with `callSetupFailed` in the message body.

### Session state inputs and outputs

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
CallType | com.opencloud.sentinel.common.CallType | `NetworkInitiated` | Call type of this call
SessionType | com.opencloud.sentinel.common.SessionType | `http_trigger` | Session type of this call
APartyLegName | String | `AParty` | A party leg name created by the feature
BPartyLegName | String | `BParty` | B party leg name created by the feature
HttpAci | javax.slee.ActivityContextInterface |  | ACI on which the HTTP request was received, and which will be used to send the response

### Error scenarios

Scenario | Handling
--- | ---
Missing any of required HTTP request parameters: `subscriber`, `cgpn`, `cdpn` | Sends HTTP 200OK response with the `callSetupFailed` as the content
Error on leg creation | Sends HTTP 200OK response with the `callSetupFailed` as the content
On CreditLimitReached or OCSFailure | Sends HTTP 200OK response with the `callRefused` as the content

### Mappers

This feature uses three mappers:

- The first two are used to map HTTP requests to outgoing SipRequests, as determined by the mapper execution point. The default implementations are HttpRequestToCallingPartySipRequest:

      // a mapper that takes a {{HttpRequest}} and generates a {{SipRequest}}.
      final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
              getSessionState().getSentinelSelectionKey(),
              HttpRequest.class,
              SipRequest.class,
              SipMappingPoint.CallingPartySipRequest
              );

  and HttpRequestToCalledPartySipRequest:

      // a mapper that takes a {{HttpRequest}} and generates a {{SipRequest}}.
      final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
              getSessionState().getSentinelSelectionKey(),
              HttpRequest.class,
              SipRequest.class,
              SipMappingPoint.CalledPartySipRequest
              );

- The third mapper maps a SipThirdPartyCallOutcomes to a HTTP response The default implementation is SdpDiffToSdpCcrDiffMapper:

      // a mapper that takes a {{SipThirdPartyCallOutcomes}} and generates a {{HttpResponse}}.
      final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
          getSessionState().getSentinelSelectionKey(),
          SipThirdPartyCallOutcomes.class,
          HttpResponse.class,
          mappingPoint);

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

To support both charged and uncharged calls, the `SipThirdPartyAccess_SubscriberCheck` script should be configured as follows:

    featurescript SipThirdPartyAccessSubscriberCheck {
        ...
        if not session.MonitorCallOnly { run SipThirdPartyCharging }
        else { run SipThirdPartyHttpTrigger run SipThirdPartyCallSetup }
        ...
    }

The configuration for mapping HTTP request to the SIP INVITE message is available under SIP Third Party Call Configuration. The parameters used by the feature are:

- ExpiresHeader

- MaxForwardsHeader

- RouteHeaderURI

- SupportedHeader

- UserAgentHeader

- Transport

- IsSipURIUsed

- SipURIDomain

### Statistics

Statistic | Incremented when…​
--- | ---
APartyLegCreated | A party leg is created
BPartyLegCreated | B party leg is created
LegsLinked | legs have been linked

## Send Failure End Session Feature

The Send Failure End Session feature is an instruction execution failure feature.

The feature instructs `LegManager.endSession(403)` if the triggering instruction failure was a `sendMessage`. This will result in any outstanding requests receiving a 403 response.

### Details

Feature name | SendFailureEndSession
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | None
Typical feature execution point | SipInstructionExecutionFailure

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

Send Failure End Session cannot be configured.

## Sip Proxy and Do Not Record Route Feature

### Description

Feature name | SipProxyAndDoNotRecordRoute
Applicable contexts | SIP service
SAS Support | Yes
Prerequisite Features | N/A

The Sip Proxy And Do Not Record Route feature calls the leg manager instruction `proxyAndDoNotRecordRoute` on the leg associated with an initial SIP request.

### Session input and output variables

Sip Proxy and Do Not Record Route does not define any session state.

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Configuration

Sip Proxy and Do Not Record Route cannot be configured.

### Statistics

Name | Description
--- | ---
InvokedProxyAndDoNotRecordRouteForRequest | Counter incremented when a request is proxied.

## Sip Set Language Feature

The Sip Set Language feature is used to set the language used on play announcements. It sets the session state field `LanguageConfig` to the value present in the profile.

### Details

Feature name | SipSetLanguage
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | None
Typical feature execution point | SipAccess_PartyResponse, SipAccess_PartyRequest, SipMidSession_PartyResponse, SipMidSession_PartyRequest, SipAccess_ServiceTimer, and any SipAccess execution points where an announcement may be triggered, such as SipAccess_SubscriberCheck.

### Configuration

Parameters | Description
LanguageConfig | a string containing the language. The recommendation is to use the RFC 3066 as format (for example, `en-UK`), but the feature does validate the format.

### Configuration feature naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
SipSetLanguageProfileTable | Sentinel configuration table | SentinelSelectionKey (for example, `OpenCloud::::`)

### Outputs

Name | Type | Format | Description
LanguageConfig | Session state field | String | The language string, for example `en-UK`.

## Sip Third Party Charging Feature

The SIP Third Party Charging feature creates the SCUR charging instance, maps initial SIP INVITE message to a session counter address, and makes the credit reservation.

The SIP `INVITE` message used is the message created by the SIP Third Party HTTP Trigger Feature from the incoming HTTP request.

Since the SIP Third Party Charging feature only creates the charging instance and makes credit reservation, the rest of the charging process must be handled by the B2BUA SCUR Features.

### Details

Feature name | SipThirdPartyCharging
Applicable contexts | SIP service
SAS Support | No
Prerequisite features | SIP Third Party HTTP Trigger Feature
Related features | B2BUA SCUR Features
Typical feature execution points | SipThirdPartyAccess_SubscriberCheck

### Feature responses

Response | Reason
--- | ---
featureHasFinished | feature has finished

### Session State inputs and outputs

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
B2BUAChargingCounterAddress | com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress | Session counter address | Session counter address mapped from the initial INVITE message

### Mappers

This feature uses a mapper to convert the SIP request to a `SessionCounterAddress`. The default implementation is SipRequestToSessionCounterAddress:

    // a mapper that takes a {{SipRequest}} and generates a {{SessionCounterAddress}}.
    final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
            getSessionState().getSentinelSelectionKey(),
            SipRequest.class,
            SessionCounterAddress.class,
            mappingPoint);

### Configuration

The feature is not configurable.

## Subscription Expiry Feature

The Subscription Expiry Feature ensures that subscriptions end when they expire and Sentinel is acting as the subscription server (endpoint).

The feature monitors the active subscriptions by inspecting the outgoing `NOTIFY` messages, and sets a timer based on the `Subscription-State.expires` parameter. If any of the timers associated with the Subscription Expiry feature expire, then `leg.endSubscription` is used to end the associated subscription. The subscription timers will be cancelled when the subscription has ended (`SIP NOTIFY` message with subscription-state terminated or leg/session ended).

### Details

Feature name | SubscriptionExpiry
Applicable contexts | SIP service
SAS Support | No
Prerequisite Features | None
Typical feature execution points | SubscriptionSipRequest SipEndSession SipLegEnd
Timer usage | Feature-targeted timer triggers feature directly on expiry. Does not need to be registered against SipAccess_ServiceTimer execution point

### Leg Manager inputs

Leg | Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | --- | ---
All | NotifyRequest | org.jainslee.resources.sip.OutgoingSipRequest | See Easysip javadoc | NOTIFY sent to the subscribing party | N/A

### SIP headers

#### Inputs

Name | Format | Description | Behaviour if absent
--- | --- | --- | ---
Subscription-State | String | Header indicating state of subscription | N/A

### Feature responses

Response | Reason
--- | ---
featureHasFinished | Feature has finished

## Unconditional Reject Session Feature

### Description

Feature name | UnconditionalRejectSession
Applicable contexts | Diameter Mediation Service
SAS Support | No
Prerequisite Features | None

Sentinel feature which unconditionally rejects a session with SIP response of SC_FORBIDDEN. Used primarily in a vanilla install of sentinel that has yet to be configured. I.e a plain install of sentinel will reject all sessions it receives.

### Session state inputs and outputs

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

### Error scenarios

This feature always succeeds.

### Feature responses

Response | Reason
--- | ---
refuseSession | intended behaviour
featureHasFinished | feature has finished

### Configuration

This feature is not configurable.

### Provisioning interfaces

This feature has no provisioning interfaces.

## Vertical Service Code Feature

This feature detects Vertical Service Codes in the dialled digit string, and modifies the session as required to give effect to them.

### Details

Feature name | VerticalServiceCode
Applicable contexts | SIP service
SAS Support | Yes
Prerequisite features | None

Both prefix and full dial string matching is supported.

Possible modifications to the session include

- Strip the matched service code from the Request URI and To header

- End the session with a specific response code

- Set up session state to play a specific announcement

- Change the session plan

- Store a specified value, the matched service code or the dial string suffix to a specified session state field

### Session State inputs and outputs

#### Inputs

Name | Type | Format | Description | Behaviour if null/invalid
--- | --- | --- | --- | ---
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey | selection key (for example, `<platform>::::`) | For selecting configuration data | N/A

#### Outputs

Name | Type | Format | Description
--- | --- | --- | ---
OriginalRequestUri | String |  | The Request URI before any modification by the feature
OriginalNormalisedDialString | String |  | The normalised dial string before service codes were extracted
DialledVerticalServiceCodePrefixes | List of String |  | Any prefix service codes found in the OriginalNormalisedDialString
DialledVerticalServiceCodeFullNumber | String |  | The full match service code if found in OriginalNormalisedDialString after any prefix service codes are removed. Not set if no FullNumber service code found.
DialledSuffix | String |  | The suffix dial string after all prefix service codes are removed from OriginalNormalisedDialString when no FullNumber match was made. Empty string if FullNumber match occurs.
SentinelSelectionKey | com.opencloud.sentinel.common.SentinelSelectionKey |  | When a matched Action changes the Plan ID.
EarlyMediaAnnouncementInfoQueue | List<SipAnnouncementInformation> |  | When a matched Action has an announcement ID
<any> | Integer, Long, Boolean, (and their primitives), String, and any Enum type. |  | Constant value specified in the Action for the service code, converted as specified in the Action and in consideration of the type of the session state field.
<any> | String | Dialled Prefix or Suffix | The service code prefix, or the dialled suffix to that service code may be stored into the String session state field specified in the Action for the service code.

### Behaviour

#### Matching

The feature first extracts the dialled digit String from the Request URI. If no digits can be found the feature finishes.

If the request URI is a `tel:` URL with `phone-context` parameter of `geo-local` then the feature finishes.

If the number is in international format and is not prefixed by the home country code the feature finishes.

If the number is in international format and is prefixed by the home country code then the prefix will be removed before performing analysis. The feature makes use of the Normalization Component to remove the prefix.

The feature then attempts to match the remaining dialstring first against the FullNumber, and failing that against the Prefix AddressLists.

If a match is found …​

- The Action profile whose name is specified in the matched AddressList Entry is loaded.

- The actions specified in the Action profile and AddressList entry are performed as described below in Performing Actions.

- If the match is a prefix match and the action’s `AllowAdditionalPrefixes` is `true`, matching is repeated against the remainder of the dial string.

If any matched actions have `StripMatch` set to `true` then the `Request URI`, and `To:` header are updated to reflect that.

#### Performing Actions

##### Play Announcement

If the AddressListEntry’s `AnnouncementID` is `> 0` it is added to the SessionState’s `EarlyMediaAnnouncementInfoQueue` without `chargeForAnnouncement` or a specified `Language`.

##### End the session with a specific response code

If the Action’s `EndSessionResponseCode` is `> 0` it is used to terminate the session after any queued announcements have played or immediately if no announcements are queued.

##### Change the session plan

If the Action’s `PlanId` is a non empty string, it is set into the `SentinelSelectionKey`. This `PlanID` will be used from the next ExecutionPoint.

##### Set a specified session state field to a specified value.

If the Action’s `SessionStateFieldName` is the name of an actual SesionState field …​

- if the Action’s `SessionStateDataSource` is set to `SERVICE_CODE_VALUE` and the SessionState field is a String field, the matched code is set in that field.

- if the Action’s `SessionStateDataSource` is set to `SUFFIX` and the SessionState field is a String field, the dial string following the prefix code is set in that field. This may include other service codes that have yet to be processed.

- if the Action’s `SessionStateDataSource` is set to `CONSTANT` then

  - The Action’s `ValueForConstantDataSource` is attempted to be converted according to the Action’s `TypeForConstantDataSource`.

  - If conversion is successful, the converted value is attempted to be assigned to the SessionState field.

Any failures to find the session state field, or convert or assign a value will generate SAS events, trace logs and the feature reports featureFailedToExecute.

#### Precedence

If multiple matched AddressList Entries request an announcement, then all such announcements will be queued in the order they are matched.

If multiple matched service code Actions specify an `EndSessionResponseCode` the last one matched applies.

If multiple matched service code Actions set the same SessionState field, the last matched one applies.

If multiple matched service code Actions change the session plan, the last matched one applies.

### Error scenarios

Scenario | Handling
--- | ---
Calling Party Leg is null | Throw runtime exception Report featureHasFinished
Leg manager is null | Report featureFailedToExecute
Cannot load Full or Prefix Address List | Report featureFailedToExecute
Invite Request is null | Report featureFailedToExecute
Trigger is not a SIP Request | Report featureFailedToExecute
AddressListEntry specifies an action but the Action profile cannot be found | Report featureFailedToExecute
Missing Normalizer home country code configuration | Report featureFailedToExecute
All digits have been stripped by service code actions | Report featureFailedToExecute
Unable to convert `valueForConstantDatasource` value to the specified type when assigning to a session state field | Reports featureFailedToExecute with specifics in Tracing and SAS event
Unable to assign a value to specified session state field, Session State field does not exist Specified conversion type is incompatible with field’s actual type Assigning null to a primitive field ValueForConstantDataSource is not a valid enum value for the enum field. | Reports featureFailedToExecute with specifics in Tracing and SAS event

### Configuration

Configuration is split between address lists and profile tables. The address lists contain data that needs to be configured by an operator, such as choosing specific service codes for supplied actions and setting which announcement (if any) is appropriate to that action.

The profile table contains data related to how Sentinel or another feature should be triggered to perform certain service code actions. Any new features which have functionality that could usefully be triggered by service codes should supply their own entries in the profile table.

#### Vertical Service Code address list configuration

The feature uses an AddressListCollection `VerticalServiceCode` with lists named `Prefix` and `FullNumber` for matching prefix and full number service codes respectively.

They are extensions of the standard Address list entry and both have the same structure with the following additional fields.

Parameter | Type | Description
--- | --- | ---
…​ | …​ | …​
Action | String | The name of a Vertical Service Code Actions profile to be applied when this service code is found. REM provides a list to select from.
AnnouncementID | Integer | ID of an announcement to be played when this service code is found, set to 0 to disable announcements. REM provides a list to select from.

Example configuration:

Address | Action | AnnouncementID
--- | --- | ---
*87 | MMTel_OIR_ID_Restriction_Current_Session_Disable | 0
*63 | MMTel_CDIV_Disable | 20

The service code lists apply to all subscribers scoped to Sentinel selection key.

#### Vertical Service Code Actions profile table configuration

Standard and customised actions are stored in a profile table `VerticalServiceCodeActions`. The table maps an Action name to the actions to perform. The Action name is the result of looking up the dialstring in the Prefix or FullNumber VerticalServiceCode address lists.

Parameter | Type | Description
--- | --- | ---
actionID | String | The name of this profile without the Sentinel Selection key prefix.
displayName | String | Used by REM to allow the user editing the address lists to choose this Action.
stripMatch | Boolean | If true the matching prefix should be stripped from the Request URI and To: headers. Set to false for the FullNumber addressList otherwise there will be no digits in the request URI and the call will fail.
allowAdditionalPrefixes | Boolean | If `true`, further matching will be attempted on the remaining dial string. Not applicable to the FullNumber addressslist as that consumes the whole dialled digit string and there is nothing further to match against.
endSessionResponseCode | Integer | If set to a valid SIP error response code, this action will end the session with that response code. Set to 0 when the action should not end the session.
planID | String | This plan ID will be set on the Sentinel selection key when this service code action is performed. Leave unset or empty to not change the service plan.
sessionStateFieldName | String | The name of a session state field to set when this service code action is performed. Leave unset or empty to not set any field.
sessionStateDataSource | String | Determines where to get the value from to set in the session state field, must be one of: 'SUFFIX', 'SERVICE_CODE_VALUE', or 'CONSTANT'.
valueForConstantDatasource | String | The value to put in the session state field if the Session State Data Source is CONSTANT. Will be parsed as specified by `sessionStateFieldType`.
sessionStateFieldType | String | The type of conversion to apply to `valueForConstantDatasource`, must be one of: 'INTEGER', 'BOOLEAN', 'LONG', 'STRING' or 'ENUM'. Only applicable when `sessionStateDataSource` is `CONSTANT`. Must correspond to the type of the session state field or the assignment will fail.

Example configuration: ${platform.operator.name}:::::MMTel_OIR_ID_Restriction_Current_Session_Disable

Parameter | Value
--- | ---
actionID | 'MMTel_OIR_ID_Restriction_Current_Session_Disable'
displayName | 'MMTel OIR - Disable Identity Restriction For Current Session'
stripMatch | true
allowAdditionalPrefixes | true
endSessionResponseCode | 0
planID | ''
sessionStateFieldName | 'DialledCallerIDRestriction'
sessionStateDataSource | 'CONSTANT'
sessionStateFieldType | 'ENUM'
valueForConstantDatasource | 'OIR_CALLER_ID_UNBLOCK'

#### Normalization Configuration

The normalizer is used to strip the home country code. See Normalization Component.

### Configuration profile naming

Configuration Profile Table Name | Description | Profile Naming
--- | --- | ---
${PLATFORMOPERATOR}_VerticalServiceCode_AddressListConfigurationTable | Address list configuration | ${PLATFORMOPERATOR}:::::VerticalServiceCode:FullNumber: ${PLATFORMOPERATOR}:::::VerticalServiceCode:Prefix:
${PLATFORMOPERATOR}_VerticalServiceCode_AddressListEntryTable | Feature specific Address List entry table | ${PLATFORMOPERATOR}:::::VerticalServiceCode:FullNumber:${ADDRESS} ${PLATFORMOPERATOR}:::::VerticalServiceCode:Prefix:${ADDRESS}
${PLATFORMOPERATOR}_VerticalServiceCodeActionsTable | Actions | ${PLATFORMOPERATOR}:::::VerticalServiceCode:${ACTION_NAME}

### Provisioning interfaces

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

### Statistics

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

Name | Type | Description
--- | --- | ---
    Started
| Counter | Incremented when the feature is triggered.
    FailedToStart
| Counter | Incremented when the feature fails to start.
    FailedDuringExecution
| Counter | Incremented when the feature fails while executing.
    IssuedWarning
| Counter | Incremented when the feature issues a warning.
    TimedOut
| Counter | Incremented when the feature times out during execution.
    RequestUriIsGeoLocal
| Counter | Incremented when the feature does not proceed because the Request URI is geolocal.
    DialledNumberOutsideHomeCountry
| Counter | Incremented when the feature does not proceed because the dialled number is international and outside the home country.
    NoDialStringInRequestUri
| Counter | Incremented when the feature does not proceed because no dial string can be found.
    FoundDialStringToAnalyse
| Counter | Incremented when the feature finds a dial string to analyse.
    FoundPrefixServiceCode
| Counter | Incremented when the feature finds an entry in the prefix address list matching the dial string.
    FoundFullNumberServiceCode
| Counter | Incremented when the feature finds an entry in the full number address list matching the dial string.
    NoServiceCodesFound
| Counter | Incremented when the feature finds no service codes in the dial string.
    SessionStateFieldSet
| Counter | Incremented when an Action sets a session state field.
    PlanIdSet
| Counter | Incremented when an Action changes the session plan.
    AnnouncementQueued
| Counter | Incremented when an Action queues an announcement.
    PreparedToEndSession
| Counter | Incremented when an Action schedules the session to end.
    ServiceCodeStrippedFromRequestUri
| Counter | Incremented when an Action strips a matched service code from RequestURI.
    EndSessionInstructed
| Counter | Incremented when the feature ends the session.
    UpdatedUris
| Counter | Incremented when the feature updates the Request URI, and the To: header.
    FailedToUpdateUris
| Counter | Incremented when the feature is unable to update the URIs. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/diameter-service-features/index.adoc :here: sentinel-components/features/diameter-service-features/ :idprefix: diameter-service-features :leveloffset: 1 = Diameter Service Features :indexpage: :sortorder: 6 Sentinel includes many features for Diameter networks: ==== * Accept Diameter Mediation Session Feature — Sets the Sentinel selection key session type to ‘diametermediation’ * Diameter Determine Network Operator Feature — Sets the Network Operator element of the Sentinel selection key based on the value returned by the `DetermineNetworkOperator` function * Diameter Subscriber Determination Feature — Used to determine the subscriber address based on AVPs in the `CreditControlRequest(INITIAL)` * Diameter Unconditional Reject Session Feature — Unconditionally rejects a Diameter session. ==== :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/diameter-service-features/accept-diameter-mediation-session-feature.adoc :here: sentinel-components/features/diameter-service-features/ :idprefix: accept-diameter-mediation-session-feature :leveloffset: 1 = Accept Diameter Mediation Session Feature == Description [cols="h,<" width="50"]

|Feature name |AcceptDiameterMediationSession |Applicable contexts |Diameter Service |SAS Support | No |Prerequisite features |None

Sets the Sentinel selection key session type to `diametermediation`. == Session state inputs and outputs === Inputs [cols="5*" options="header"]

|Name |Type |Format |Description |Behaviour if null/invalid

|SentinelSelectionKey |com.opencloud.sentinel.common.SentinelSelectionKey |selection key (for example, `<platform>:<network>:::`) |To be updated with the session type for this session |Runtime exception handled by feature runner

=== Outputs [cols="4*" options="header"]

|Name |Type |Format |Description

|SessionType |com.opencloud.sentinel.common.SessionType |diametermediation |Session type of SessionType.diametermediation

|SentinelSelectionKey |com.opencloud.sentinel.common.SentinelSelectionKey |selection key (for example, `<platform>:<network>:diametermediation::`) |Updated selection key including session type determined from application context

== Error scenarios This feature always succeeds. == Feature responses [width="40"]

|Response |Reason

|featureHasFinished |feature has finished

== Configuration This feature is not configurable. == Provisioning interfaces This feature has no provisioning interfaces. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/diameter-service-features/diameter-determine-network-operator-feature.adoc :here: sentinel-components/features/diameter-service-features/ :idprefix: diameter-determine-network-operator-feature :leveloffset: 1 = Diameter Determine Network Operator Feature == Description [cols="h,<" width="55"]

|Feature name |DiameterDetermineNetworkOperator |Applicable contexts |Diameter Service |SAS Support | No |Prerequisite Features |None

The Diameter Service’s Determine Network Operator Feature sets the network operator element of the Sentinel selection key for use in the selection of feature execution scripts, mappers and address lists. The feature will set the Network Operator element of the Sentinel selection key based on the value returned by the DetermineNetworkOperator function below. Determine Network Operator feature uses the `3GPP-IMSI-MCC-MNC` of the initial CCR to determine the network operator. It uses a map of (`3GPP-IMSI-MCC-MNC` → network operator). If no mapping can be found, then a default network operator is returned. [quote, From 3gpp TS 32.299, which references 3gpp TS 29.061] 3GPP-IMSI-MCC-MNC : MCC and MNC extracted from the user’s IMSI (first 5 or 6 digits, as applicable from the presented IMSI). == Session state inputs and outputs === Inputs [cols="5*" options="header"]

|Name |Type |Format |Description |Behaviour if null/invalid

|SentinelSelectionKey |com.opencloud.sentinel.common.SentinelSelectionKey |selection key e.g `<platform>::::` |To be updated with network operator determined from triggering initial CCR |Runtime exception to be handled by feature runner

=== Outputs [cols="4*" options="header"]

|Name |Type |Format |Description

|SentinelSelectionKey |com.opencloud.sentinel.common.SentinelSelectionKey |selection key e.g `<platform>:<network>:::` |Updated with network operator determined from triggering initial CCR

== Error scenarios [cols="3,4" width="80"]

|Scenario |Handling

|Trigger not CreditControlRequest |Report featureCannotStart |Cannot map 3GPP-IMSI-MCC-MNC to a network operator and no default is available |Increment `CouldNotDetermineNetworkOperator`
Report featureFailedToExecute

== Feature responses [cols="1,3" width="85"]

|Response |Reason

|featureCannotStart |Trigger event must be CreditControlRequest |featureFailedToExecute |Cannot map 3GPP-IMSI-MCC-MNC to a network operator and no default is available |featureHasFinished |feature has finished

== Configuration IMSI-MCC-MNC to network operator mapping table: [cols="1,1,3" width="75"]

|Parameter |Type |Description

|Address |GT Address |The ImsiMccMnc address (for example: 00101) |NetworkOperator |String |The Network Operator to set (for example: MVNO1)

The default is stored in the Sentinel configuration table. Example table: [cols="1,2" width="30"]

|Address |NetworkOperator

|00101 |OpenCloud |00102 |MVNO1

== Configuration profile naming [cols="2,2,1"]

|Configuration Profile Table Name |Description |Profile Naming

|SentinelImsiMccMncToNetworkOperatorProfileTable |IMSI MCC MNC to network operator mapping table |ImsiMccMnc address

== Provisioning interfaces The feature is provisioned using the Sentinel Diameter Determine Network Operator REST API or web interface. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/diameter-service-features/diameter-subscriber-determination-feature.adoc :here: sentinel-components/features/diameter-service-features/ :idprefix: diameter-subscriber-determination-feature :leveloffset: 1 = Diameter Subscriber Determination Feature == Description [cols="h,<" width="45"]

|Feature name |SubscriberDetermination |Applicable contexts |Diameter Service |SAS Support | No |Prerequisite Features |None

The Subscriber Determination Feature is used to determine the subscriber address based on AVPs in the CreditControlRequest(INITIAL). If the Subscriber session state field is not set, then the Subscriber Determination feature will set it based on value of `creditControlRequest/SubscriptionId[0]/SubscriptionIdData`. NOTE: This feature will not change the Subscriber session state field if it is already set. == Session state inputs and outputs === Inputs [cols="5*" options="header"]

|Name |Type |Format |Description |Behaviour if null/invalid

|Subscriber |String |Arbitrary |Use existing value if set |Proceed with subscriber determination

|InitialCcr |org.jainslee.resources.diameter.ro.types.CreditControlRequest |https://developer.opencloud.com/devportal/devportal/apis/diameter/diameter-connectivity-pack/2.0/diameter-connectivity-pack-2.0-javadoc/org/jainslee/resources/diameter/ro/types/CreditControlRequest.html[Credit-Control-Request] |Initial CCR which triggered this session |Unless subscriber was pre-determined, report featureFailedToExecute, featureHasFinished

=== Outputs [cols="1,1,1,6" width="80"]

|Name |Type |Format |Description

|Subscriber |String |Arbitrary |Subscriber determined from initial CCR, unless already set

== Error scenarios [cols="2,1" width="85"]

|Scenario |Handling

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

== Feature responses [cols="1,3" width="75"]

|Response |Reason

|featureFailedToExecute |Subscriber address determination failed. Flag invalid subscriber |featureHasFinished |feature has finished

== Configuration This feature is not configurable. == Configuration profile naming This feature is not configurable. == Provisioning interfaces This feature has no provisioning interfaces. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/diameter-service-features/diameter-unconditional-reject-session-feature.adoc :here: sentinel-components/features/diameter-service-features/ :idprefix: diameter-unconditional-reject-session-feature :leveloffset: 1 = Diameter Unconditional Reject Session Feature == Description [cols="h,<" width="45"]

|Feature name |UnconditionalRejectSession |Applicable contexts |Diameter Service |SAS Support | No |Prerequisite Features |None

Unconditionally rejects a Diameter session. Used primarily in a vanilla install of Sentinel that has yet to be configured. (A plain install of Sentinel will reject all sessions it receives.) Result code is set to DIAMETER_UNABLE_TO_COMPLY. == Session state inputs and outputs This feature does not read from or write to session state. == Error scenarios This feature always succeeds. == Feature responses [width="45"]

|Response |Reason

|respondDiameterBaseResult |intended behaviour |featureHasFinished feature |has finished

== Configuration This feature is not configurable. == Provisioning interfaces This feature has no provisioning interfaces. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/test-features/index.adoc :here: sentinel-components/features/test-features/ :idprefix: test-features :leveloffset: 1 = Test Features :indexpage: :sortorder: 8 Sentinel includes features for testing purposes: [cols="2*" options="header"]

|Feature |Description

|com.opencloud.sentinel.feature.common.test.TestNeverFinish |This feature starts (calls `startFeature()`) but does not finish (it never calls `featureHasFinished()`). It is intended for testing Sentinel feature timeout behaviour for incorrectly designed features

|com.opencloud.sentinel.feature.notification.TestSetNotificationMessage |This feature sets the “NotificationMessage” session state field to the string “notification”

|com.opencloud.sentinel.feature.initialtrigger.TestSetAnnouncementId |Test Set Announcement ID

|com.opencloud.sentinel.feature.initialtrigger.TestFailingFeature |This SS7 feature throws a RuntimeException when run

|com.opencloud.sentinel.feature.initialtrigger.TestFailingSs7CallbackFeature |This SS7 feature throws a RuntimeException on SS7 callbacks (e.g. SS7 aborts, disconnects, etc.)

|com.opencloud.sentinel.feature.initialtrigger.TestFollowOnCall |This SS7 feature will attempt a follow on call when run in the BPartyNotEstablished execution point. The new b-party address for the follow on call is set in the TestFollowOnCallSessionState.

|com.opencloud.sentinel.feature.initialtrigger.TestAVPToFCI |This SS7 feature will send a FurnishChargingInformation and (optionally) send a delimiter when run in the PostCreditCheck or BPartyNotEstablished_PostCC execution points. It will also accept the dialog if necessary to send the FCI.

|com.opencloud.sentinel.feature.enddialog.TestSetUserReleaseCause |This SS7 feature sets the “UserReleaseCause” session state field to Cause.CauseValue.CLASS1_INVALID_NUMBER_FORMAT (0x1c)

|com.opencloud.sentinel.feature.common.test.TestSetSessionState Test |bxref:test-set-session-state[Set Session State}

|com.opencloud.sentinel.feature.common.test.TestRouteHeaderConfiguration |This SIP feature randomly sets the “RouteHeaderURI” session state field to either “scscf1:5160” or “scscf2:5160”

IMPORTANT: These features are included for test purposes and may not be suitable for use in production environments. NOTE: Some (or all) of these features may not be available in a given Sentinel release. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/test-features/test-set-announcement-id.adoc :here: sentinel-components/features/test-features/ :idprefix: test-set-announcement-id :leveloffset: 1 = Test Set Announcement ID [cols="h,<" width="50"] == Description [cols="h,<" width="45"]

|Feature name |TestSetAnnouncementID |Applicable contexts |SS7 service, SIP service |SAS Support | No |Prerequisite features |none

The Test Set Announcement ID feature sets the AnnouncementID session state field to a value based on the Subscriber session state field. The value used to populate the AnnouncementID field will be picked from the TestSetAnnouncementID/testPrefixesToPlayAnnouncement address list based on the Subscriber ID. The default announcement ID set by this feature is 17, but several other values can be set based on the value looked up from the address list. == Session state inputs and outputs === Inputs [cols="5*" options="header"]

|Name |Type |Format |Description |Behaviour if null/invalid

|SentinelSelectionKey |com.opencloud.sentinel.common.SentinelSelectionKey |selection key (for example, `<platform>::::`) |For selecting configuration data |Report featureCannotStart, return

|Subscriber |String |N/A |Subscriber identifier |

=== Outputs

|Name |Type |Format |Description

|AnnouncementID |int |N/A |The Announcement ID to set

== Error scenarios [width="50"]

|Scenario |Handling

|Null sentinel selection key |Report featureCannotStart |Missing address list |Report featureCannotStart |Missing address list prefixes |Report featureCannotStart

== Feature responses [width="40"]

|Response |Reason

|featureHasFinished |feature has finished

== Configuration The Test Set Announcement ID configuration requires an address list for configuration. [width="40"]

|SchemaName |List Name

|TestSetAnnouncementId |testPrefixesToPlayAnnouncement

The announcement ID will be set based on the value looked up from the address list as follows: [width="35"]

|Matched Address |Announcement ID

|34915 |15 |34916 |17 |34917 |17 |34918 |18 |34919 |19 |default |17

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/features/test-features/test-set-session-state.adoc :here: sentinel-components/features/test-features/ :idprefix: test-set-session-state :leveloffset: 1 = Test Set Session State == Description [cols="h,<" width="50"]

|Feature name |TestSetSessionState |Applicable contexts |SS7 service, SIP service |SAS Support | No |Prerequisite Features |none

The Test Set Session State feature allows setting session state fields to arbitrary values based on its configuration. == Session state inputs and outputs === Outputs One or more session state fields will be set to pre-configured values. Only specific field types can be set — see the configuration section below. == Error scenarios [width="50"]

|Scenario |Handling

|Missing configuration |Report featureCannotStart |Invalid configuration |Report featureCannotStart

== Feature responses [width="40"]

|Response |Reason

|featureHasFinished |feature has finished

== Configuration The Test Set Session State feature: * is configured through the `TestSetSessionStateConfigTable` profile table * uses all configuration profiles found in this table Each profile used represents configuration for a single session state field. The naming of the individual profiles does not matter. Each profile has the following fields: [cols="1,6"]

|Parameters |Description

|FieldName |The name of the field to set. (e.g. MySessionStateField) |FieldType |The type of the field to set. This must equal one of the valid types as listed in the table below. (e.g. java.lang.Integer) |FieldValue |The value to set the field to. (e.g. 7)

The feature supports the following session state field types: * java.lang.String * java.lang.Integer * java.lang.Long * java.lang.Boolean :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/utility-components/index.adoc :here: sentinel-components/utility-components/ :idprefix: utility-components :leveloffset: 1 = Utility Components :indexpage: :sortorder: 3 Sentinel includes a number of utility software components that are used by features bundled with Sentinel and may also be used by new features added with the SDK. The utility components include: ==== * Normalization Component— The Sentinel Normalizer normalizes International, Unknown, National, or Subscriber NADI format addresses * Service Timer Provider— The ServiceTimerProvider API is used by features to raise feature-specific timers. * XPath Language Component— The Sentinel XPath component supports a subset of the XPath language, which supports Diameter messages in Sentinel. * CAP Charging Component --The Sentinel ChargingGTFormatter allows the generation of global titles for use in CAP charging requests. ==== :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/utility-components/cap-charging-component.adoc :here: sentinel-components/utility-components/ :idprefix: include-cap-charging-component :leveloffset: 1 = CAP Charging Component :page-id: include-cap-charging-component == Description [cols="h,a" width= "55"]

|Component name | ChargingGTFormatter |Applicable contexts | * VoLTE Service * IP-SM-GW Service |Features using component | * Cap Location Headers * MO Submission Location

The Sentinel ChargingGTFormatter allows the generation of global titles for use in CAP charging requests. == Configuration Configuration is stored on a profile table called `CapChargingConfigProfileTable`. Data is scoped according to a Sentinel selection key. [cols="2l,1,1,6" options="header"]

|Attribute Name |Type |Default |Description |ChargingGTFormatString |String |null |The format template to use when creating Charging GTs. It must be a digit string except for tokens ('{iso}', '{mcc}', '{mnc}) which are substituted in. |UnknownLocationChargingGT |String |null |The Charging GT to use when one could not be generated because the user’s location could not be determined.

== Session Input Variables [cols="1,1,3a" options="header"]

|IsoCountryCode |String |The ISO country code that the subscriber is registered with. It is used for formatting the `OC-Charging-GT` header. |PaniMccMncs |List<MccMnc> |The MCCs and MNCs that the subscriber is registered with. They are used for formatting the `OC-Charging-GT` header.

== Behaviour The ChargingGTFormatter allows the generation of global titles from the `ChargingGTFormatString`. The ChargingGTFormatter will attempt replace any `{iso}` tokens in the `ChargingGTFormat` string with the ASCII digit values for the characters in the `IsoCountryCode` session state field. The `IsoCountryCode` should be upper case characters. ==== A `ChargingGTFormatString` of `555{iso}555` and `IsoCountryCode` of `NZ` would result in `5557890555`. ==== The ChargingGTFormatter will attempt replace any `{mcc}` and `{mnc}` tokens in the `ChargingGTFormat` string with the MCC and MNC values from the first entry in the `PaniMccMncs` session state field. ==== A `ChargingGTFormatString` of `55{mcc}55{mnc}55` and first `PaniMccMncs` entry of `mcc.123.mnc.456` would result in `551235545655`. ==== If the `ChargingGTFormatString` contains any tokens other than `{mcc}`, `{mnc}`, or `{iso}` then the ChargingGTFormatter will do nothing and return `null`. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/utility-components/normalization-component.adoc :here: sentinel-components/utility-components/ :idprefix: include-normalization-component :leveloffset: 1 = Normalization Component :page-id: include-normalization-component == Description [cols="h,a" width= "55"]

|Component name | Normalizer |Applicable contexts | * SS7 Service * SIP Service * VoLTE Service * XCAP |Features using component | * (SS7) Normalization * (SS7) SMSNormalization * (SIP) SipNormalization * MMTelCDIV * MMTelICB * MMTelOCB

The Sentinel Normalizer normalizes International, Unknown, National, or Subscriber NADI format addresses into either: * international address format — starting with CC + MNC * national format — starting with MNC where MNC is specified in the NetworkDialingCode configuration setting. The Sentinel Normalizer may decide to not normalize the address if the address is either: * shorter than the `MinNormalizableLength` * an entry in the `SkipNormalizationAddressList` This allows for short codes and specific longer length numbers to avoid normalization. The `SkipNormalizationAddressList` is a configurable address list scoped by the Sentinel selection key; it is only used by the SIP normalization component. Normalization is invoked by the call type specific normalization features Voice Call Normalization Feature, SMS Normalization Feature and SIP Normalization Feature. It is also invoked by the XCAP Server to reject requests containing numbers which are not normalizable. Furthermore, MMTelCDIV, MMTelICB and MMTelOCB use the normalization component to normalize numbers in outgoing requests, and when comparing numbers. [NOTE] ==== Support for formatting of special characters in SS7 signalling (such as: * → B, # → C) is provided by the SS7 Prefix and Suffix Analysis Feature. Sentinel supports special character mapping only if they are prefixes or suffixes. ==== == Configuration [cols="1,1,3"]

|Parameter |Type |Description

|NationalPrefix | String | National dialling prefix (for example, 0) |CountryCode | String | Country code |NetworkDialingCode | String | Network dialling code, used as the MNC |InternationalEscapeCode | String | Escape code for dialing international numbers (for example, 00) |NormalizeTo | String | Indicates the default format of Nature of Address Indication (NADI); one of: [international, national] |ProfileVersion | Integer | The current profile’s version (used for determining if reloading is required) |MinNormalizableLength | Integer | The minimum length of an address for it to be normalizable.

== Normalization address list configuration The `SkipNormalizationAddressList` address list uses the standard Address list entry. Addresses that prefix match against entries in the list are not normalized. [NOTE] ==== Using the 'SkipNormalizationAddressList' to avoid normalizing numbers is only supported by the (SIP) SipNormalization and the SCCCamelToIMSReOriginationSIPFeature in Sentinel-Volte. ==== == Configuration profile naming

|Configuration Profile Table Name |Description |Profile naming

|NormalizationFeatureConfigProfileTable |Normalization parameter configuration |SentinelSelectionKey (for example, `OpenCloud::::`)| |${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable |Address list configuration |${SELECTIONKEY}:Normalizer:SkipNormalizationAddressList |${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable |Feature specific Address List entry table |${SELECTIONKEY}:Normalizer:SkipNormalizationAddressList:${ADDRESS}

== Provisioning interfaces The Normalizer component is provisioned using the Sentinel Normalization REST API or Managing Normalization web interface. == Behaviour The Normalizer component normalizes addresses based on its configuration. Initially the address to normalize is checked for length against the `MinNormalizableLength`, and against the `SkipNormalizationAddressList`. If the address is under the `MinNormalizableLength`, or matches the prefix list, normalization is skipped. Then the configuration of the component is checked to determine whether the address should be normalized to national or international format. * If the number should be normalized to international format if the number is in national format, the configured `CountryCode` will be prepended to the address. if the number is in subscriber format, the `CountryCode` and the configured `NetworkDialingCode` will be prepended to the address. If the current format of the number is unknown, the format will be determined by checking against the configured `InternationalEscapeCode` and `NationalPrefix`, and then normalizing as appropriate. If neither of those prefixes match the address, it will be returned unchanged. * If the number should be normalized to national format if the number is in international format, the length of the configured `CountryCode` will be removed from the start of the address. if the number is in subscriber format, the configured `NetworkDialingCode` will be prepended to the address. If the current format of the number is unknown, the format will be determined by checking against the configured `InternationalEscapeCode` and `NationalPrefix`, and then normalizing as appropriate. If neither of those prefixes match the address, it will be returned unchanged. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/utility-components/servicetimerprovider.adoc :here: sentinel-components/utility-components/ :idprefix: servicetimerprovider :leveloffset: 1 = ServiceTimerProvider == Description [cols="h,<" width="50"]

|Component name |ServiceTimerProvider |Applicable contexts |SIP service |Features using component |CallDiversion

The ServiceTimerProvider API can be used by features to set feature specific timers and receive TimerEvents, when the timers fire. NOTE: ServiceTimerProvider is currently only available in the Sentinel SIP frontend, but the concept eventually will be extended to the other cores. See ServiceTimerProvider of the Sentinel Overview and Concepts Guide for usage and API documentation. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/utility-components/xpath-language-component.adoc :here: sentinel-components/utility-components/ :idprefix: include-xpath-language-component :leveloffset: 1 = XPath Language Component :page-id: include-xpath-language-component == Description [cols="h,a" width="60"]

|Component name |Sentinel-XPath |Applicable contexts | * SS7 service * Diameter Mediation Service |Features using component | * PlayAnnouncement * ScriptedPromotions

The Sentinel XPath component supports a subset of the XPath language, which supports Diameter messages in Sentinel. It supports path expressions for querying Diameter messages. The path elements are Diameter AVPs with ‘-’ removed. For example, Multiple-Services-Credit-Control has path element `MultipleServicesCreditControl`. NOTE: The elements are case sensitive. == Examples Query the Validity-Time AVP from the first Multiple-Services-Credit-Control AVP: `MultipleServicesCreditControl[1]/ValidityTime` Query the command-level Result-Code AVP: `ResultCode` Query the Subscription-Id AVP: `SubscriptionId` XPath predicates can be used to query specific AVPs where multiple AVPs of that type are permitted. For instance, multiple `MultipleServicesCreditControl` AVPs are permitted in CreditControlRequest and CreditControlAnswer. To return the Result-Code AVP from the `MultipleServiceCreditControl` AVP with Rating-Group set to 1, use the following expression: * `MultipleServicesCreditControl[RatingGroup=1]/ResultCode` :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/index.adoc :here: sentinel-components/promotions/ :idprefix: promotions :leveloffset: 1 = Promotions :indexpage: :sortorder: 4 This section covers: ==== * OCS failure handling promotions * Promotions buckets * Promotions commit used units feature * Promotions free reservations feature * Scripted promotions feature ==== TIP: For an overview of what promotions are and how they work, see the Sentinel Overview and Concepts Guide. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/ocs-failure-handling-promotions/index.adoc :here: sentinel-components/promotions/ocs-failure-handling-promotions/ :idprefix: ocs-failure-handling-promotions :leveloffset: 1 = OCS Failure Handling Promotions :indexpage: :sortorder: 1 OCS failure handling promotions features include: * OCS failure handling data promotion feature * OCS failure handling SMS promotion feature * OCS failure handling time promotion feature :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/ocs-failure-handling-promotions/ocs-failure-handling-data-promotion-feature.adoc :here: sentinel-components/promotions/ocs-failure-handling-promotions/ :idprefix: ocs-failure-handling-data-promotion-feature :leveloffset: 1 = OCS Failure Handling Data Promotion Feature == Description [cols="1h,<" width="60"]

|Feature name |OcsFailureHandlingDataPromotionFeature |Applicable contexts |Diameter service |SAS Support | No |Prerequisite features |

Used in an OCS Failure case to grant units if available from an `OcsFailureHandlingData` bucket. == Configuration This feature is not configurable. == Provisioning interfaces This feature has no provisioning interfaces. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/ocs-failure-handling-promotions/ocs-failure-handling-sms-promotion-feature.adoc :here: sentinel-components/promotions/ocs-failure-handling-promotions/ :idprefix: ocs-failure-handling-sms-promotion-feature :leveloffset: 1 = OCS Failure Handling SMS Promotion Feature == Description [cols="1h,<" width="60"]

|Feature name |OcsFailureHandlingSmsPromotionFeature |Applicable contexts |Diameter service |SAS Support | No |Prerequisite features |

Used in an OCS failure case to grant units if available from an `OcsFailureHandlingSms` bucket. == Configuration This feature is not configurable. == Provisioning interfaces This feature has no provisioning interfaces. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/ocs-failure-handling-promotions/ocs-failure-handling-time-promotion-feature.adoc :here: sentinel-components/promotions/ocs-failure-handling-promotions/ :idprefix: ocs-failure-handling-time-promotion-feature :leveloffset: 1 = OCS Failure Handling Time Promotion Feature == Description [cols="1h,<" width="60"]

|Feature name |OcsFailureHandlingTimePromotionFeature |Applicable contexts |Diameter service |SAS Support | No |Prerequisite features |

Used in an OCS failure case to grant units if available from an `OcsFailureHandlingTime` bucket. == Configuration This feature is not configurable. == Provisioning interfaces This feature has no provisioning interfaces. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/promotion-buckets.adoc :here: sentinel-components/promotions/ :idprefix: promotions-buckets :leveloffset: 1 = Promotions Buckets A promotion bucket is a counter of units available to a given subscriber. Each bucket must have a unique name and can be configured within Sentinel to be of one of the following access types: * External database * Cassandra * SLEE profiles * Sentinel session state * Unlimited. Each promotion must state the name of the bucket to which units shall be charged if the promotion applies. Multiple promotions can charge to the same bucket. If the bucket is configured for ‘external database’ access, the promotion bucket units are held in an external database. == Promotion units Promotion units are generic and can be used to represent any unit type. There is a one-to-one ratio between the value of a promotion unit and the value of the charging unit being deducted by a promotion. For example, if a promotion matches a request for 1024 Octets, then 1024 promotion units will be deducted. Therefore, it is generally not sensible to match two different unit types in the same promotion, unless they have a one-to-one value. == Provisioning interfaces Promotion bucket configuration and data are provisioned using the Sentinel REST API or web interface. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/promotions-commit-used-units-feature.adoc :here: sentinel-components/promotions/ :idprefix: promotions-commit-used-units-feature :leveloffset: 1 = Promotions Commit Used Units Feature == Description [cols="1h,a" width="60"]

|Feature name |PromotionsCommitUsedUnits |Applicable contexts | * SS7 service |SAS Support | No * Diameter Mediation Service |Prerequisite features | |Postrequisite features |ScriptedPromotions

`PromotionsCommitUsedUnits` handles all `UsedServiceUnit` requests for a set of promotions. The committing of `UsedServiceUnits` to promotion buckets is performed based on the analysis of session counters in session state. If the promotion script no longer applies when the used service units related to the promotion arrive, this feature will still handle the units. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/promotions-free-reservations-feature.adoc :here: sentinel-components/promotions/ :idprefix: promotions-free-reservations-feature :leveloffset: 1 = Promotions Free Reservations Feature == Description [cols="1h,a" width="55"]

|Feature name |PromotionsFreeReservations |Applicable contexts | * SS7 service |SAS Support | No * Diameter Mediation Service |Prerequisite features |ScriptedPromotions

`PromotionsFreeReservations` frees any promotion-related reservations that have not been freed before the end of the session. It is mandatory to include this as an end session feature if either Scripted Promotions Feature or a feature which extends `BaseJavaPromotionFeature` is in use. Unused reservations are determined by examining the current state of the session counters stored in session state. The feature must be installed in the end session execution point in both the SS7 and Diameter client services. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/scripted-promotions-feature/index.adoc :here: sentinel-components/promotions/scripted-promotions-feature/ :idprefix: scripted-promotions-feature :leveloffset: 1 = Scripted Promotions Feature :indexpage: :toc: macro :toclevels: 4 :toc-title: On this page…​ toc::[] == Description [cols="1h,a" width="55"]

|Feature name |ScriptedPromotions |Applicable contexts | * SS7 service |SAS Support | No * Diameter Mediation service * SIP service |Prerequisite features |PromotionsCommitUsedUnits |Postrequisite features |PromotionsFreeReservations

Using the `ScriptedPromotions` feature, new promotions can be created, enabled, disabled, or removed during normal Sentinel online operation. The promotions are executed in the Diameter Mediation module which is used by all Sentinel client modules: Diameter Client and SS7 Client. Scripted Promotions are available for all session and call sessions, including Voice/Video/Data/Fax calls triggered by CAMEL, CAMEL callback calls, MO SMS, and Diameter sessions. === Session scenarios The following scenarios are supported and enabled via scripted promotions: * charge all units for a session from a single or multiple promotion, entirely suppressing interaction with the OCS * charge units from multiple MSCCs in a single CCR where they have different parameters (such as servicdid) to different promotions, to the OCS * serially interleave promotions and OCS requests related to a condition * charge units to a promotion on OCS failure * direct debit and refund units with promotions. Scripted Promotion may apply: * between promotions with wide validity dates * between subscription-specific validity dates * during certain times of day or on certain days * across a service plan for a set of subscribers * to certain session types only (such as SMS, Voice calls, GGSN sessions, and so on) * based on individual subscription * based on AVPs available in the CCRs (such as tarrifs, roaming indicators, serviceIds, rating groups, or location information) * based on type of units. === Promotions feature API The Diameter Mediation module exposes a feature execution point `DiameterMediationChargingControlFeatureEndpoint` to provide `ScriptedPromotions` and other third-party developed promotions with the necessary controls over session behaviour. The feature endpoint API provides the following controls: [cols="1,3" width="75"]

|Method |Description

|suppressOcsInteraction |request: suppress further interaction with the OCS |enableOcsInteraction |request: enable further interaction with the OCS |isOcsInteractionEnabled |check if ocs interaction is currently enabled |shutdownOCS |request: existing OCS connection shall be shutdown if one exists

`ScriptedPromotions` uses these controls to apply promotions where applicable to requests from the Diameter mediation clients. === Promotion selection Promotion selection is performed using the following algorithm: ---- Get the list of promotions by selection key For each promotion in the list in order of ascending priority evaluate the conditional expression of the promotion to determine if it is applicable to the session Reserve applicable requested units from the promotion bucket Update the CCR and synthesize a CCA ---- Promotion selection is only relevant to the `CreditControlRequests` which have `RequestServiceUnit` AVPs. All `UsedServiceUnit` AVPs are handled without condition by `PromotionsCommitUsedUnits`. All outstanding promotion reservations on session end are freed by `PromotionsFreeReservations`. == Scripted promotion scope A scripted promotion has one of the following scopes: * All subscribers (applies to all subscribers) * Subscribed (applies to subscribers who have subscribed to the promotion). The scope is determined using the `subscriberIsEligible` function in Promotion Selection Expressions. If this function is present, the scope will be to subscribed subscriber only. If this function is absent, the promotion is scoped to all subscribers. === Configuration A promotion bucket is referenced by SubscriberId and the bucket name stated by each promotion. A bucket contains the available and reserved units. The unit type may be: time (seconds), bytes, event counts, or some service-specific unit type. The unit type is not enforced by the bucket. It is the responsibility of the promotion to correctly select requested service unit AVPs with the correct unit type for the promotion. The bucket unit record contains the following fields: [cols="1,6"]

|Parameter |Description

|SubscriberId |Subscriber identifier |BucketName |Name of the bucket |AvailableUnits |Available units for this promotion |ReservedUnits |Any units which have been reserved during session charging but not committed as used units, or freed at session end

The subscriber also has a promotion configuration retrieved by the Subscriber Data Lookup Feature: [cols="1,3"]

|Parameter |Description

|PromotionList |Used by the `subscriberIsEligible` promotion script function Promotion Selection Expressions |PromotionValidityStartDates |Used by the `subscriberIsEligible` promotion script function Promotion Selection Expressions |PromotionValidityEndDates |Used by the `subscriberIsEligible` promotion script function Promotion Selection Expressions

Each scripted promotion is configured in the PromotionsTable: [cols="1,4"]

|Parameter |Description

|SelectionKey |Sentinel selection key the promotion is scoped to (for example, `OpenCloud::::`) |PromotionName |Promotion name (for example, `AnytimeFreeData`) |BucketName |Bucket name (for example, `AnytimeFreeData`) |PromotionPriority |Promotions selection priority |PromotionConditionSrc |See Promotion Selection Expressions (for example `chargingUnitTypeOneOf(CCInputOctets,CCOutputOctets,CCTotalOctets)`) |EncodedValidityEnd |Used by the `promotionIsCurrent` function to determine promotion-wide validity |EncodedValidityStart |Used by the `promotionIsCurrent` function to determine promotion-wide validity

PromotionBucketsConfigTable: [cols="1,6"]

|Parameter |Description

|BucketName |The ID of the promotion bucket for which this configuration applies. |DataSource |profile,dbquery,cassandra,unlimited,sessionstate. Used when no dedicated access configuration can be found for a particular bucket name. Note: the profile is only used for testing or demo purposes.

PromotionsConfigTable: [cols="1,3"]

|Parameter |Description

|DefaultDataSource |profile,dbquery,cassandra,unlimited,sessionstate. Used when no dedicated access configuration can be found for a particular bucket name. Note: the profile is only used for testing or demo purposes. |PartialGrantingThreshold |0 |PromotionApplicationMode |one_only (single option available) |UnitGrantingMode |partial, full_only. When set to partial, will grant units to the minimum set by the PartialGrantingThreshold parameter. When set to full_only, the units will only be granted if the full amount is available from the promotion bucket.

PromotionsDbQueryConfigProfileTable: [cols="1,3" width="85"]

|Parameter |Description

|AddSQL |SQL statement for adding a bucket for a subscriber |DatabaseRequestTimeout |Database request timeout in milliseconds |DeleteSQL |SQL statement for deleting a bucket for a subscriber |istAllSQL |SQL statement for listing all buckets |LoadSQL |SQL statement for loading a bucket based on subscriber id and bucket name |UpdateSQL |SQL statement for updating a bucket based on subscriber id and bucket name

== Configuration profile naming

|Configuration profile table name |Description |Profile naming

|PromotionsTable |Configuration of scripted promotions |SentinelSelectionKey:priority_promotionname (for example, `OpenCloud:::::0_AnytimeFreeData`) |PromotionBucketsConfigTable |Configuration of promotion bucket properties (such as access type) |SentinelSelectionKey:BucketName (for example, `OpenCloud::::AnytimeFreeData`) |PromotionsConfigTable |Configuration of promotions behaviour |SentinelSelectionKey (for example, `OpenCloud::::`) |PromotionsDbQueryConfigProfileTable |DbQuery statement configuration |SentinelSelectionKey for example, `OpenCloud::::`)

=== Provisioning interfaces Scripted promotions are provisioned using the Sentinel Promotions REST API or web interface. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/index.adoc :here: sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/ :idprefix: promotion-selection-expressions :leveloffset: 1 = Promotion Selection Expressions :indexpage: == Description Promotions selection conditional expressions determine promotion applicability by analysing the set of Request Service Unit AVPs which are present in one or more MultipleServicesCreditControl AVPs. == Promotion Conditional Expressions Promotion Selection Expressions are Boolean expressions using the follow operators (in descending precedence): +! (NOT), && (AND) and |  | (OR)+ Parenthesis () may be used in the expressions. Comparison operators: > < == != >= ⇐ Types: Boolean, String, Integer Access to session state: variables are prefixed with sessionstate. or ss. Constants: string (“string”); boolean (`true | false | TRUE | FALSE`); integer (1, -1) === XPath expressions XPath expressions on Diameter messages are used to select an AVP from the message for use in the expressions (see XPath Language Component): ---- ss.LatestClientRequest/MultipleServicesCreditControl\[ServiceID = 1\] ss.LatestClientRequest/MultipleServicesCreditControl\[ServiceID = 1\]/RequestedServiceUnit/CCInputOctets ---- === Predicates and variables [cols="3*a" options="header"]

|Function |Arguments |Description

|promotionIsCurrent |N/A |Uses the validity information in the promotion’s configuration in PromotionsTable

|subscriberIsEligible |N/A |Uses the validity information in the subscriber’s promotion configuration

|timeOfDayBetween |integer: start time, Integer: stop time (For example, `timeOfDay(800, 1400)` means inclusive hours between 0800 and 1400 |Returns true if current time of day is between the start and stop time. If the start time is > stop time, then timeOfDay will check between start time — 2400 and 0000 — stop

|todayOneOf |Any of “Mon”,“Tue”,“Wed”,“Thur”,“Fri”, “Sat”,“Sun” (for example, `todayOneOf("Mon", "Fri"))` |Returns true if current day of week is one of the listed days

|sessionstate.<varname>, ss.<varname> |N/A |In predicate context, returns true if not null, an empty array, an empty collection, an empty string or a Boolean with value of true, otherwise false. In expression context (that is, as argument to function or comparator) returns the actual value.

| Boolean sessionstate fields always evaluate to true in predicate context unless they are null. To test for false, compare the returned object to false using ==

|chargingServiceIDOneOf |Comma-delimited list of serviceNames (see ServiceIDConfigTable Configuration) |returns true if the service name of the charging info is in the argument list

|chargingUnitTypeOneOf |Comma-delimited list of any of CCServiceSpecificUnits, CCMoney, CCInputOctets, CCOutputOctets, CCTotalOctets, CCTime |returns true if the charging unit type of the charging info is in the argument list

Functions may be added by using the SDK to provide extensions. === Example ---- subscriberIsEligible() && ss.ccr/Multiple-Service-Credit-Control[Service-Id = 1 and */CC-Input-Octets] && ss.isRoaming && ( timeOfDayBetween(800, 1000)
timeOfDayBetween(1800, 1900)) && todayOneOf("Mon","Fri") ---- === Syntax See Promotion Selection Expression DSL Grammar. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/promotion-selection-expression-dsl-grammar.adoc :here: sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/ :idprefix: promotion-selection-expression-dsl-grammar :leveloffset: 1 = Promotion Selection Expression DSL Grammar The following grammar (in the ANLTR parser generator notation) defines the syntax of promotion selection expressions. ---- grammar SentinelPromotionScript; promotionCondition : predicate EOF ; predicate : andPred ('
' andPred)* ; andPred : condition ('&&' condition)* ; condition : '(' predicate ')'
'!' condition
comparison ; comparison : expression (COMPARATOR expression)? ; expression : ID ('.' ID)* '(' argumentList? ')'
id=ID ('.' ID)* (pathExpr)? //a variable is a function without args
LONG
STRING ; argumentList : expression (',' expression )* ; pathExpr : '/' relativePathExpr?
'//' relativePathExpr
relativePathExpr ; relativePathExpr: stepExpr (( '/'
'//' ) stepExpr )* ; stepExpr: ( '.'
abbrevForwardStep ) (xpathpredicate)? ; abbrevForwardStep : attributeFlag = '@'? (stQName = qName
stNodeExpansion = '') ; xpathpredicate : '[' orExpr ']' ; orExpr : andExpr ('or' andExpr) ; andExpr : comparisonexpr ('and' comparisonexpr)* ; comparisonexpr: primaryExpr (COMPARATOR literal)?; primaryExpr : pathExpr
'(' pathExpr ')'
LONG ; literal : STRING
numericLiteral
varRef; numericLiteral: LONG DECIMALLITERAL
DOUBLELITERAL; qName: (ID ':' ID)
ID; varRef: '$' nCName; nCName: ID ('.' ID)*; COMPARATOR : '=='
'<'
'>'
'!='
'⇐'
'>='; ID : ('a'..'z'
'A'..'Z'
'_') ('a'..'z'
'A'..'Z'
'0'..'9'
'_')* ; LONG : ('-')? '0'..'9'+ ; DECIMALLITERAL : ('.' ('0'..'9')+)
(('0'..'9')+ '.' '0'..'9'*); DOUBLELITERAL : (('.' ('0'..'9')+)
'0'..'9')+ ('.' '0'..'9'*)? ('e'
'E') ('+'
'-')? ('0'..'9')+; STRING : '"' ~('\\'
'"')* '"' ; WS : ( ' '
'\t'
'\r'
'\n' ) ; ---- :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/service-id-config-table-configuration.adoc :here: sentinel-components/promotions/scripted-promotions-feature/promotion-selection-expressions/ :idprefix: service-id-config-table-configuration :leveloffset: 1 = Service ID Config Table Configuration The ServiceID configuration table provides a mapping between ServiceID integers in Diameter messages and the names of the services. == Configuration The `ServiceIDConfigTable` is scoped by selection key and has the following fields: [cols="1,2" width="40"]

|Parameter |Description

|ServiceIDs |Array of integers |ServiceNames |Array of service name strings

=== Example profile: [width="40"]

|ServiceIDs |ServiceNames

|100,101,200 |Facebook,Voicecall,Youtube

In this example: * Facebook has service id 100. * Voicecall has service id 101. * Youtube has service id 200. == Configuration profile naming

|Configuration Profile Table Name |Description |Profile Naming

|ServiceIDConfigTable |Selection of database implementation and rating group for the feature |SentinelSelectionKey (for example, `OpenCloud::::`)

== Provisioning interfaces The service IDs are provisioned using the Diameter Mediation REST API or web interface (under Sentinel > Service Configuration > Diameter Mediation > Service IDs). :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/index.adoc :here: sentinel-components/mappers/ :idprefix: mappers :leveloffset: 1 = Mappers :indexpage: :sortorder: 5 Sentinel comes with many mappers that can be configured at various mapping points and scopes. Mappers include: ==== * Sentinel diameter mappers * Sentinel diameter mediation mappers * Sentinel OCS driver mappers * Sentinel SIP mappers * Sentinel Registrar mappers * Sentinel SS7 mappers ==== :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-diameter-mappers.adoc :here: sentinel-components/mappers/ :idprefix: sentinel-diameter-mappers :leveloffset: 1 = Sentinel Diameter Mappers :toc: macro :toclevels: 4 :toc-title: On this page…​ toc::[] == SentinelCCAToRoClientCCA `com.opencloud.sentinel.mapper.impl.SentinelCCAToRoClientCCA` Mappings:

|Name |From |To

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

== SentinelASRToRoClientASR `com.opencloud.sentinel.mapper.impl.SentinelASRToRoClientASR` Mappings:

|Name |From |To

|SentinelASRToRoClientASR |org.jainslee.resources.diameter.base.types.AbortSessionRequest |org.jainslee.resources.diameter.base.types.AbortSessionRequest

== SentinelRARToRoClientRAR `com.opencloud.sentinel.mapper.impl.SentinelRARToRoClientRAR` Mappings:

|Name |From |To

|SentinelRARToRoClientRAR |org.jainslee.resources.diameter.base.types.ReAuthRequest |org.jainslee.resources.diameter.base.types.ReAuthRequest

== RoClientRAAToSentinelRAA `com.opencloud.sentinel.mapper.impl.RoClientRAAToSentinelRAA` Mappings:

|Name |From |To

|RoClientRAAToSentinelRAA |org.jainslee.resources.diameter.base.types.ReAuthAnswer |org.jainslee.resources.diameter.base.types.ReAuthAnswer

== CCRToCDR `com.opencloud.sentinel.mapper.impl.CCRToCDR` Mappings:

|Name |From |To

|CCRToCDR |org.jainslee.resources.diameter.ro.types.CreditControlRequest |com.google.protobuf.Message

== RoClientCCRToSentinelCCR `com.opencloud.sentinel.mapper.impl.RoClientCCRToSentinelCCR` Mappings:

|Name |From |To

|RoClientCCRToSentinelCCR |org.jainslee.resources.diameter.ro.types.CreditControlRequest |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== RoClientASAToSentinelASA `com.opencloud.sentinel.mapper.impl.RoClientASAToSentinelASA` Mappings:

|Name |From |To

|RoClientASAToSentinelASA |org.jainslee.resources.diameter.base.types.AbortSessionAnswer |org.jainslee.resources.diameter.base.types.AbortSessionAnswer

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-diameter-mediation-mappers.adoc :here: sentinel-components/mappers/ :idprefix: sentinel-diameter-mediation-mappers :leveloffset: 1 = Sentinel Diameter Mediation Mappers == SessionStateToSentinelCCRTerminate `com.opencloud.sentinel.mapper.impl.SessionStateToSentinelCCRTerminate` Mappings:

|Name |From |To

|SessionStateToSentinelCCRTerminate |com.opencloud.sentinel.common.SentinelDiameterMediationSessionState |org.jainslee.resources.diameter.ro.types.CreditControlRequest

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-ocs-driver-mappers.adoc :here: sentinel-components/mappers/ :idprefix: sentinel-ocs-driver-mappers :leveloffset: 1 = Sentinel OCS Driver Mappers :toc: macro :toclevels: 4 :toc-title: On this page…​ toc::[] == RoOcsRARToSentinelRAR `com.opencloud.sentinel.mapper.impl.RoOcsRARToSentinelRAR` Mappings:

|Name |From |To

|RoOcsRARToSentinelRAR |org.jainslee.resources.diameter.base.types.ReAuthRequest |org.jainslee.resources.diameter.base.types.ReAuthRequest

== SentinelRAAToRoOcsRAA `com.opencloud.sentinel.mapper.impl.SentinelRAAToRoOcsRAA` Mappings:

|Name |From |To

|SentinelRAAToRoOcsRAA |org.jainslee.resources.diameter.base.types.ReAuthAnswer |org.jainslee.resources.diameter.base.types.ReAuthAnswer

== RoOcsCCAToSentinelCCA `com.opencloud.sentinel.mapper.impl.RoOcsCCAToSentinelCCA` Mappings:

|Name |From |To

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

== RoOcsASRToSentinelASR `com.opencloud.sentinel.mapper.impl.RoOcsASRToSentinelASR` Mappings:

|Name |From |To

|RoOcsASRToSentinelASR |org.jainslee.resources.diameter.base.types.AbortSessionRequest |org.jainslee.resources.diameter.base.types.AbortSessionRequest

== SentinelCCRToRoOcsCCR `com.opencloud.sentinel.mapper.impl.SentinelCCRToRoOcsCCR` Mappings:

|Name |From |To

|SentinelCCRToRoOcsCCR |org.jainslee.resources.diameter.ro.types.CreditControlRequest |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== SentinelASAToRoOcsASA `com.opencloud.sentinel.mapper.impl.SentinelASAToRoOcsASA` Mappings:

|Name |From |To

|SentinelASAToRoOcsASA |org.jainslee.resources.diameter.base.types.AbortSessionAnswer |org.jainslee.resources.diameter.base.types.AbortSessionAnswer

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-registrar-mappers.adoc :here: sentinel-components/mappers/ :idprefix: sentinel-registrar-mappers :leveloffset: 1 = Sentinel Registrar Mappers :toc: macro :toclevels: 4 :toc-title: On this page…​ toc::[] == ReceivedRegisterRequestToNetworkOperatorLookupKey `com.opencloud.sentinel.registrar.mapper.impl.ReceivedRegisterRequestToNetworkOperatorLookupKey` [cols="1,1,2" options="header"]

|From …​ | …​ To | Description

| IncomingSipRequest | String | Returns the To address host as the lookup key.

== ReceivedRegisterRequestToSessionState `com.opencloud.sentinel.registrar.mapper.impl.ReceivedRegisterRequestToSessionState` [cols="1,1,2" options="header"]

|From …​ | …​ To | Description

| IncomingSipRequest | SentinelRegistrarSessionState | Extracts the first-party REGISTER request and response from the third-party REGISTER request message body, and stores them in session state.

== RegisterRequestAndResponseToUserIdMapper `com.opencloud.sentinel.registrar.mapper.impl.RegisterRequestAndResponseToUserIdMapper` [cols="1,1,2" options="header"]

|From …​ | …​ To | Description

| UserIdsSessionState | UserIdsSessionState | Extracts common identities from the first-party REGISTER request and response in session state, and stores them in session state fields. In particular the private-id, public-ids, Contacts, and any GRUU that are present.

== SessionStateToRegisterCdrAvpBasedMapper `com.opencloud.sentinel.registrar.mapper.impl.SessionStateToRegisterCdrAvpBasedMapper` [cols="1,1,2" options="header"]

|From …​ | …​ To | Description

|SentinelRegistrarSessionState |com.google.protobuf.Message |Builds an audit CDR from fields in session state

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-sip-mappers.adoc :here: sentinel-components/mappers/ :idprefix: sentinel-sip-mappers :leveloffset: 1 = Sentinel SIP Mappers :toc: macro :toclevels: 4 :toc-title: On this page…​ Labels: pending_finishupdate toc::[] == HttpRequestToCallingPartySipRequest `com.opencloud.sentinel.mapper.impl.HttpRequestToCallingPartySipRequest` Mappings:

|Name |From |To

|HttpRequestToCallingPartySipRequest |com.opencloud.slee.resources.http.HttpRequest |org.jainslee.resources.sip.SipRequest

== HttpRequestToCalledPartySipRequest `com.opencloud.sentinel.mapper.impl.HttpRequestToCalledPartySipRequest` Mappings:

|Name |From |To

|HttpRequestToCalledPartySipRequest |com.opencloud.slee.resources.http.HttpRequest |org.jainslee.resources.sip.SipRequest

== ThirdPartyCallOutcomeToHttpResponse `com.opencloud.sentinel.mapper.impl.ThirdPartyCallOutcomeToHttpResponse` Mappings:

|Name |From |To

|ThirdPartyCallOutcomeToHttpResponse |om.opencloud.sentinel.common.SipThirdPartyCallOutcomes |com.opencloud.slee.resources.http.HttpResponse

== CCAtoSessionCounterList `com.opencloud.sentinel.mapper.impl.CCAtoSessionCounterListMapper` Mappings:

|Name |From |To

|CCAtoSessionCounterListMapper |org.jainslee.resources.diameter.ro.types.vcb0.CreditControlAnswer |java.util.List

== ChargingInstanceToCCR `com.opencloud.sentinel.mapper.impl.ChargingInstanceToCCR` Mappings:

|Name |From |To

|ChargingInstanceToCCR |com.opencloud.sentinel.charging.ChargingInstance |org.jainslee.resources.diameter.ro.types.vcb0.CreditControlRequest

== SdpDiffToSdpCcrDiffMapper `com.opencloud.sentinel.mapper.impl.SdpDiffToSdpCcrDiffMapper` Mappings:

|Name |From |To

|SdpDiffToSdpCcrDiffMapper |com.opencloud.sentinel.diff.sdp.SdpDiffModel |com.opencloud.sentinel.diff.sdp.SdpDiffModel

== SdpMatchModelToSdpCcrMatchModelMapper `com.opencloud.sentinel.mapper.impl.SdpMatchModelToSdpCcrMatchModelMapper` Mappings:

|Name |From |To

|SdpMatchModelToSdpCcrMatchModelMapper |com.opencloud.sentinel.diff.sdp.SdpMatchModel |com.opencloud.sentinel.diff.sdp.SdpMatchModel

== SessionStateToForcedOutgoingSipErrorResponse `com.opencloud.sentinel.mapper.impl.SessionStateToForcedOutgoingSipErrorResponse` Mappings:

|Name |From |To

|SessionStateToForcedOutgoingSipErrorResponse |org.jainslee.resources.sip.IncomingSipRequest |org.jainslee.resources.sip.OutgoingSipResponse

== SipRequestToCCR `com.opencloud.sentinel.mapper.impl.SipRequestToCCR` Mappings:

|Name |From |To

|SipRequestToCCR |org.jainslee.resources.sip.SipRequest |org.jainslee.resources.diameter.ro.types.vcb0.CreditControlRequest

== SipRequestToSessionCounterAddress `com.opencloud.sentinel.mapper.impl.SipRequestToSessionCounterAddress` Mappings:

|Name |From |To

|SipRequestToSessionCounterAddress |org.jainslee.resources.sip.SipRequest |com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/mappers/sentinel-ss7-mappers.adoc :here: sentinel-components/mappers/ :idprefix: sentinel-ss7-mappers :leveloffset: 1 = Sentinel SS7 Mappers :toc: macro :toclevels: 4 :toc-title: On this page…​ This page describes the Sentinel SS7 mappers. toc::[] == CCAToReleaseCallArg `com.opencloud.sentinel.mapper.impl.CCAToReleaseCallArg` Mappings:

|Name |From |To

|CCAToReleaseCallArg |org.jainslee.resources.diameter.ro.types.CreditControlAnswer |com.opencloud.slee.resources.cgin.callcontrol.CCReleaseCallArg

== CorrelationDataToCAPInitialDP `com.opencloud.sentinel.mapper.impl.CorrelationDataToCAPInitialDP` Mappings:

|Name |From |To

|CorrelationDataToCAP1InitialDP |byte[] |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg

== CAP3InitialDPSMSArgToCCR `com.opencloud.sentinel.mapper.impl.CAP3InitialDPSMSArgToCCR` Mappings:

|Name |From |To

|CAP3InitialDPSMSArgToCCR |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== CAP3EventReportSMSArgToCCR `com.opencloud.sentinel.mapper.impl.CAP3EventReportSMSArgToCCR` Mappings:

|Name |From |To

|CAP3EventReportSMSArgToCCR |com.opencloud.slee.resources.cgin.cap_v3.CAP3EventReportSMSArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== CAP3InitialDPArgToConnectArg `com.opencloud.sentinel.mapper.impl.CAP3InitialDPArgToConnectArg` Mappings:

|Name |From |To

|CAP3InitialDPArgToConnectArg |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPArg |com.opencloud.slee.resources.cgin.callcontrol.CCConnectArg

== CCSpecializedResourceReportArgToCCR `com.opencloud.sentinel.mapper.impl.CCSpecializedResourceReportArgToCCR` Mappings:

|Name |From |To

|CCSpecializedResourceReportArgToCCR |com.opencloud.slee.resources.cgin.callcontrol.CCSpecializedResourceReportArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== CAP3InitialDPSMSArgToCAP3ConnectSMSArg `com.opencloud.sentinel.mapper.impl.CAP3InitialDPSMSArgToCAP3ConnectSMSArg` Mappings:

|Name |From |To

|CAP3InitialDPSMSArgToCAP3ConnectSMSArg |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg |com.opencloud.slee.resources.cgin.cap_v3.CAP3ConnectSMSArg

== CAP2ApplyChargingReportToReauthCCR `com.opencloud.sentinel.mapper.impl.CAP2ApplyChargingReportToReauthCCR` Mappings:

|Name |From |To

|CAP2ApplyChargingReportToReauthCCR |com.opencloud.slee.resources.cgin.cap_v2.CAP2ApplyChargingReportArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== LegTypeToCS1CallInformationRequestArg `com.opencloud.sentinel.mapper.impl.LegTypeToCS1CallInformationRequestArg` Mappings:

|Name |From |To

|LegTypeToCS1CallInformationRequestArg |com.opencloud.slee.resources.in.datatypes.cc.LegType |com.opencloud.slee.resources.cgin.etsi_inap_cs1.CS1CallInformationRequestArg

== CAPInitialDPArgToCorrelationData `com.opencloud.sentinel.mapper.impl.CAPInitialDPArgToCorrelationData` Mappings:

|Name |From |To

|CAP1InitialDPArgToCorrelationData |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |byte[] |CAP2InitialDPArgToCorrelationData |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |byte[] |CAP3InitialDPArgToCorrelationData |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPArg |byte[] |CAP4InitialDPArgToCorrelationData |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitialDPArg |byte[]

== DialogOpenRequestEventToCdr `com.opencloud.sentinel.mapper.impl.DialogOpenRequestEventToCdr` Mappings:

|Name |From |To

|DialogOpenRequestEventToCdr |com.opencloud.slee.resources.cgin.DialogOpenRequestEvent |com.google.protobuf.Message

== ThirdPartyCallOutcomeToHttpResponse `com.opencloud.sentinel.mapper.impl.ThirdPartyCallOutcomeToHttpResponse` Mappings:

|Name |From |To

|ThirdPartyCallOutcomeToHttpResponse |com.opencloud.sentinel.common.SipThirdPartyCallOutcomes |com.opencloud.slee.resources.http.HttpResponse

== CCInitialDPArgToCCR `com.opencloud.sentinel.mapper.impl.CCInitialDPArgToCCR` Mappings:

|Name |From |To

|CCInitialDPArgToCCR |com.opencloud.slee.resources.cgin.callcontrolCCInitialDPArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

|CAP2InitialDPArgToCCR |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== LegTypeToCAP2CallInformationRequestArg `com.opencloud.sentinel.mapper.impl.LegTypeToCAP2CallInformationRequestArg` Mappings:

|Name |From |To

|LegTypeToCAP2CallInformationRequestArg |com.opencloud.slee.resources.in.datatypes.cc.LegType |com.opencloud.slee.resources.cgin.cap_v2.CAP2CallInformationRequestArg

== CallTypeToCCRequestReportBCSMEventArg `com.opencloud.sentinel.mapper.impl.CallTypeToCCRequestReportBCSMEventArg` Mappings:

|Name |From |To

|CallTypeToCCRequestReportBCSMEventArg |com.opencloud.sentinel.common.CallType |com.opencloud.slee.resources.cgin.callcontrol.CCRequestReportBCSMEventArg

== CCInitialDPArgToCAP4InitiateCallAttempt `com.opencloud.sentinel.mapper.impl.CCInitialDPArgToCAP4InitiateCallAttempt` Mappings:

|Name |From |To

|CCInitialDPArgToCAP4InitiateCallAttempt |com.opencloud.slee.resources.cgin.callcontrol.CCInitialDPArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

|CAP1InitialDPArgToCAP4InitiateCallAttempt |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

|CAP2InitialDPArgToCAP4InitiateCallAttempt |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

|CAP3InitialDPArgToCAP4InitiateCallAttempt |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

|CAP4InitialDPArgToCAP4InitiateCallAttempt |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitialDPArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

== CAP2InitialDPArgToConnectArg `com.opencloud.sentinel.mapper.impl.CAP2InitialDPArgToConnectArg` Mappings:

|Name |From |To

|CAP2InitialDPArgToConnectArg |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |com.opencloud.slee.resources.cgin.callcontrol.CCConnectArg

== SentinelErrorToReleaseCallArg `com.opencloud.sentinel.mapper.impl.SentinelErrorToReleaseCallArg` Mappings:

|Name |From |To

|SentinelErrorToReleaseCallArg |com.opencloud.sentinel.common.SentinelError |com.opencloud.slee.resources.cgin.callcontrol.CCReleaseCallArg

== SessionTypeToCAP3RequestReportSMSEventArg `com.opencloud.sentinel.mapper.impl.SessionTypeToCAP3RequestReportSMSEventArg` Mappings:

|Name |From |To

|SessionTypeToCAP3RequestReportSMSEventArg |com.opencloud.sentinel.common.SessionType |com.opencloud.slee.resources.cgin.cap_v3.CAP3RequestReportSMSEventArg

== HttpRequestToCAP2InitialDPArg `com.opencloud.sentinel.mapper.impl.HttpRequestToCAP2InitialDPArg` Mappings:

|Name |From |To

|HttpRequestToCAP2InitialDPArg |com.opencloud.slee.resources.http.HttpRequest |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg

== CCInitialDPArgToConnectArg `com.opencloud.sentinel.mapper.impl.CCInitialDPArgToConnectArg` Mappings:

|Name |From |To

|CCInitialDPArgToConnectArg |com.opencloud.slee.resources.cgin.callcontrol.CCInitialDPArg |com.opencloud.slee.resources.cgin.callcontrol.CCConnectArg

== CAP1InitialDPArgToConnectArg `com.opencloud.sentinel.mapper.impl.CAP1InitialDPArgToConnectArg` Mappings:

|Name |From |To

|CAP1InitialDPArgToConnectArg |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |com.opencloud.slee.resources.cgin.callcontrol.CCConnectArg

== CAP2ApplyChargingReportToCCR `com.opencloud.sentinel.mapper.impl.CAP2ApplyChargingReportToCC` Mappings:

|Name |From |To

|CAP2ApplyChargingReportToCCR |com.opencloud.slee.resources.cgin.cap_v2.CAP2ApplyChargingReportArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== AdditionalCallPartyArgToCAP4InitiateCallAttempt `com.opencloud.sentinel.mapper.impl.AdditionalCallPartyArgToCAP4InitiateCallAttempt` Mappings:

|Name |From |To

|AdditionalCallPartyArgToCAP4InitiateCallAttempt |com.opencloud.sentinel.mapper.types.AdditionalCallPartyArg |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitiateCallAttemptArg

== CAP2CallInformationReportToCCR `com.opencloud.sentinel.mapper.impl.CAP2CallInformationReportToCCR` Mappings:

|Name |From |To

|CAP2CallInformationReportToCCR |com.opencloud.slee.resources.cgin.cap_v2.CAP2CallInformationReportArg |org.jainslee.resources.diameter.ro.types.CreditControlRequest

== SessionStateCreditBufferToCAP2ApplyChargingArg `com.opencloud.sentinel.mapper.impl.SessionStateCreditBufferToCAP2ApplyChargingArg` Mappings:

|Name |From |To

|SessionStateCreditBufferToCCApplyChargingArg |com.opencloud.sentinel.common.SentinelSs7SessionState |com.opencloud.slee.resources.cgin.callcontrol.CCApplyChargingArg

|SessionStateCreditBufferToCAP2ApplyChargingArg |com.opencloud.sentinel.common.SentinelSs7SessionState |com.opencloud.slee.resources.cgin.cap_v2.CAP2ApplyChargingArg

== CAPInitialDPToCorrelationIdPoolAddress `com.opencloud.sentinel.mapper.impl.CAPInitialDPToCorrelationIdPoolAddress` Mappings:

|Name |From |To

|CAP1InitialDPToCorrelationIdPoolAddress |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |java.lang.String

|CAP2InitialDPToCorrelationIdPoolAddress |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |java.lang.String

|CAP4InitialDPToCorrelationIdPoolAddress |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitialDPArg |java.lang.String

== CAP3InitialDPSMSArgToCdr `com.opencloud.sentinel.mapper.impl.CAP3InitialDPSMSArgToCdr` Mappings:

|Name |From |To

|CAP3InitialDPSMSArgToCdr |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPSMSArg |com.google.protobuf.Message

== CCAToCAP2ApplyChargingArg `com.opencloud.sentinel.mapper.impl.CCAToCAP2ApplyChargingArg` Mappings:

|Name |From |To

|CCAToCCApplyChargingArg |org.jainslee.resources.diameter.ro.types.CreditControlAnswer |com.opencloud.slee.resources.cgin.callcontrol.CCApplyChargingArg

|CCAToCAP2ApplyChargingArg |org.jainslee.resources.diameter.ro.types.CreditControlAnswer |com.opencloud.slee.resources.cgin.cap_v2.CAP2ApplyChargingArg

== CAP1InitialDPArgToCdr `com.opencloud.sentinel.mapper.impl.CAP1InitialDPArgToCdr` Mappings:

|Name |From |To

|CAP1InitialDPArgToCdr |com.opencloud.slee.resources.cgin.cap_v1.CAP1InitialDPArg |com.google.protobuf.Message |CAP2InitialDPArgToCdr |com.opencloud.slee.resources.cgin.cap_v2.CAP2InitialDPArg |com.google.protobuf.Message |CAP3InitialDPArgToCdr |com.opencloud.slee.resources.cgin.cap_v3.CAP3InitialDPArg |com.google.protobuf.Message |CAP4InitialDPArgToCdr |com.opencloud.slee.resources.cgin.cap_v4.CAP4InitialDPArg |com.google.protobuf.Message

== HttpRequestToSS7CallCdr `com.opencloud.sentinel.mapper.impl.HttpRequestToSS7CallCdr` Mappings:

|Name |From |To

|HttpRequestForSs73rdPartyCallToCdr |com.opencloud.slee.resources.http.HttpRequest |com.google.protobuf.Message

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-components/address-lists.adoc :here: sentinel-components/ :idprefix: include-address-lists :leveloffset: 1 :doctitle: Address Lists :sortorder: 6 :page-id: include-address-lists = Address Lists :indexpage: :leveloffset: +1 = Address List Overview == What is an address list? An address list is a searchable collection of addresses. Each address in an address list may also have some associated data. You can use address lists for some of the features bundled with Sentinel, such as: * special prefixes —Prefix and Suffix Analysis Feature does a longest prefix match against a dialled number to see if the dialled address includes one of the prefixes. * short-codes — The Short Code Feature does an exact match against a dialled number to see if the dialled number is a short-code. Each short-code in the address list has the fully qualified address the short-code represents. * global-title addresses — The SS7 Determine Network Operator Feature does a longest prefix match against the destination SCCP address to determine which network operator the new session is for. Each address list has a unique name. The addresses in the address list are stored in SLEE profiles. Sentinel manages a cached digit tree for each address list. The digit tree provides fast exact, longest prefix, and longest suffix matching of addresses. .addresses in an address list called “Prefixes”, mapped into a digit tree image::sentinel-components/features/sip-features/sip-user-features/addresslist.png[] Addresses in an address list are sequences of: 0 …​ 9, a …​ f, A …​ F, #, , . TIP: You provision address lists using the Sentinel Element Manager. See the Sentinel Administration Guide for details. IMPORTANT: Address lists should only be managed with the Sentinel Element Manager or the RESTful HTTP provisioning interface. The SLEE profile tables, how they are named, and many of the fields are internal to Sentinel and the Element Manager. = Profile Tables for Address Lists Address lists are stored using SLEE profiles: * Address list configuration profile — defines configuration properties of the address list (for example, should it be cached). * Address list entry profile  — the entries in the address list (and any associated data, if any) [NOTE] ==== An address list is identified by two properties: * *address list name— the name of the address list. For example, the PrefixAndSuffixAnalysis feature uses address lists called: ‘SpecialPrefixList’ and ‘SpecialSuffixList’. * schema name — corresponds to the type of the address list. For example, the PrefixAndSuffixAnalysis feature address lists have the schema name ‘PrefixAndSuffixAnalysis’. Address lists that do not associate any data with an address list entry have the schema name ‘Sentinel’. ==== Sentinel adopts a simple naming convention for mapping an address list schema name to the SLEE profile tables required for address lists that use that schema. * Address list configuration Table Name — <PlatformOperatorName>_<SchemaName>_AddressListConfigurationTable * Address list entry Table Name  — <PlatformOperatorName>_<SchemaName>_AddressListEntryTable For example, the PrefixAndSuffixAnalysis feature uses address lists that are stored in these profile tables: * <PlatformOperatorName>_PrefixAndSuffixAnalysis_AddressListConfigurationTable * <PlatformOperatorName>_PrefixAndSuffixAnalysis_AddressListEntryTable Address lists that do not have any data associated with entries in the address list use a schema name of ‘Sentinel’ and are stored in the following SLEE profile tables: * <PlatformOperatorName>_Sentinel_AddressListConfigurationTable * <PlatformOperatorName>_Sentinel_AddressListEntryTable == Address List Configuration Profile Each address list has a configuration profile with these properties: [cols="1,1,3" width="90"]

|Parameter |Type |Description

|Description |String | |Name |String |The name of this address list |SchemaName |String |The name of the schema of this address list |PlatformOperator |String |…​ of the Selection key, for this address list to be used |NetworkOperator |String |…​ of the Selection key, for this address list to be used |SessionType |String |…​ of the Selection key, for this address list to be used |PlanId |String |…​ of the Selection key, for this address list to be used |SubscriptionId |String |…​ of the Selection key, for this address list to be used |DefaultSearchMode|Integer |One of: 0 — exact match, 1 — longest prefix match, 2 — longest suffix match |ShouldCache |Boolean |True, if the Sentinel core should maintain a cached version of the address list in memory |Version |Long |Sentinel core tracks the version for address lists that are cached in memory. If the version changes, then the Sentinel core re-builds the cached version of the address list. The version is incremented by the Sentinel Element Manager, once a set of updates to an address list (either by changing this configuration, or changing list entries) should be applied to any cached versions of the address list in memory.

== Address List Entry Profile Each Address List entry corresponds to a profile with these properties: [cols="1,1,3" width="90"]

|Parameter |Type |Description

|Description |String | |Address |String |The address string — a sequence of characters matching: 0 …​ 9, a …​ f, A …​ F, #, *, . |listId |String |The list id is a string that identifies the address list this entry belongs to. It has the following form: <selectionkey>:<schemaName>:<listname>

NOTE: Address lists that have additional data will have additional properties for that data. See Using Address Lists in the Extending Sentinel with the SDK guide to understand how a feature uses an address list and how you can associate data with entries in an address list. :leveloffset: -1 :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/index.adoc :here: provisioning/ :idprefix: provisioning :leveloffset: 1 = Provisioning :indexpage: :sortorder: 4 == Using the Sentinel Element Manager You provision Sentinel using the Sentinel Element Manager. The Sentinel Element Manager provides a web interface and machine API for provisioning Sentinel. TIP: The Sentinel Element Manager is an extension of the Rhino Element Manager (REM). See Installing the Sentinel Express Provisioning Module to install the Sentinel provisioning module in REM. For general information on using Rhino Element Manager, see the Rhino Element Manager User Guide. To provision Sentinel, see the procedures to: ==== * Configure the Sentinel REM Extension * Provision Sentinel using the Web Interface * Sentinel Provisioning REST API * Working with CDRs * Configure Auditing of Provisioning Operations * Configure and use the Sentinel XCAP API ==== :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-configuration/index.adoc :here: provisioning/provisioning-configuration/ :idprefix: provisioning-configuration :leveloffset: 1 = Provisioning Configuration :indexpage: :sortorder: 1 You set configuration options for the Sentinel provisioning application using a properties file. On startup, the Sentinel provisioning server tries to read this file: `${REM_HOME}/sentinel-provisioning-config.properties` By default, this file does not exist, and Sentinel uses default options. To configure provisioning options: . create this file . add the property definitions you want to customize. You can also configure Sentinel EM to provision data in an external database. == Provisioning configuration options ==== You can configure these Sentinel provisioning options: * `sentinel.<featurename>.default-page-size` * `sentinel.homezone.configuration.cache.timeout` * `sentinel.homezone.sql.cache.timeout` * `sentinel.subscriberdata.configuration.cache.timeout` * `sentinel.subscriberdata.fields.cache.timeout` * `sentinel.subscriberdata.sql.cache.timeout` * `sentinel.promotions.configuration.cache.timeout` * `sentinel.promotions.sql.cache.timeout` * `sentinel.core.configuration.cache.timeout` ==== === `sentinel.<featurename>.default-page-size` [cols="1h,4a" width="80"]

|Description |The default page size used when listing entries in this resource collection. |Java type |int |Default value |10 |Example |`sentinel.promotions.default-page-size=50`

=== `sentinel.homezone.configuration.cache.timeout` [cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for HomeZone configuration data used by the provisioning services. The HomeZone zones provisioning services will cache the configured lookup type (profile, dbquery) for a particular Sentinel selection key value for this amount of time. |Java type |long |Default value |60000 (1 minute) |Example |`sentinel.homezone.configuration.cache.timeout=10000`

=== `sentinel.homezone.sql.cache.timeout` [cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for HomeZone SQL configuration data used by the provisioning services. The HomeZone zones provisioning services will cache the configured SQL statements for a particular Sentinel selection key value for this amount of time (only applicable if zones are being stored in an external database). |Java type |long |Default value |60000 (1 minute) |Example |`sentinel.homezone.sql.cache.timeout=10000`

=== `sentinel.subscriberdata.configuration.cache.timeout` [cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for Subscriber Data configuration data used by the provisioning services. The Subscriber Data provisioning services will cache the lookup type (profile, dbquery, cassandra) for a particular Sentinel selection key value for this amount of time. |Java type |long |Default value |60000 (1 minute) |Example |`sentinel.subscriberdata.configuration.cache.timeout=10000`

=== `sentinel.subscriberdata.fields.cache.timeout` [cols="1h,4a" width="80"]

|Description |Description The cache timeout (in milliseconds) to use for Subscriber Data fields configuration data used by the provisioning services. The Subscriber Data provisioning services will cache the configured fields for a particular Sentinel selection key value for this amount of time. |Java type |long |Default value |60000 (1 minute) |Example |`sentinel.subscriberdata.fields.cache.timeout=10000`

=== `sentinel.subscriberdata.sql.cache.timeout` [cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for Subscriber Data SQL configuration data used by the provisioning services. The Subscriber Data provisioning services will cache the configured SQL statements for a particular Sentinel selection key value for this amount of time (only applicable if records are being stored in an external database). | Java type |long | Default value |60000 (1 minute) | Example |`sentinel.subscriberdata.sql.cache.timeout=10000`

=== `sentinel.promotions.configuration.cache.timeout` [cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for Promotions configuration data used by the provisioning services. The Promotion bucket provisioning services will cache the configured lookup type (profile, dbquery, cassandra) for a particular Sentinel selection key value for this amount of time. |Java type |long |Default value |60000 (1 minute) |Example |`sentinel.promotions.configuration.cache.timeout=10000`

=== `sentinel.promotions.sql.cache.timeout` [cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for Promotions SQL configuration data used by the provisioning services. The Promotion bucket provisioning services will cache the configured SQL statements for a particular Sentinel selection key value for this amount of time (only applicable if bucket data is being stored in an external database). |Java type |long |Default value |60000 (1 minute) |Example |`sentinel.promotions.sql.cache.timeout=10000`

=== `sentinel.core.configuration.cache.timeout` [cols="1h,4a" width="80"]

|Description |The cache timeout (in milliseconds) to use for Sentinel configuration data used by the XCAP API. |Java type |long |Default value |6000 (1 minute) |Example |`sentinel.promotions.sql.cache.timeout=10000`

== Provisioning data in an external database If any of the Sentinel data (such as subscriber data records, home zone zones, or promotion buckets) is stored in an external database, Sentinel EM will need to be configured to connect to it directly. See: * Provisioning data in Cassandra * Provisioning data in TimesTen :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-configuration/provisioning-data-in-cassandra.adoc :here: provisioning/provisioning-configuration/ :idprefix: provisioning-data-in-cassandra :leveloffset: 1 = Provisioning Data in Cassandra :sortorder: 1 == Configuring provisioning lookup types and connections Below are instructions for configuring Cassandra lookup types and the connection to the Cassandra database. === Configuring Cassandra provisioning lookup types Sentinel comes with two Cassandra-based provisioning service implementations: for subscriber data and promotion buckets. ==== Subscriber data To use the Cassandra-based provisioning service implementation for subscriber data, in the provisioning GUI: [cols="1h,19a" width="95"]

|1 |Select Sentinel ⇒ Feature Configuration from the menu. |2 |Select Subscriber Data Lookup from the Feature dropdown. |3 |Click the Lookup Config tab. |4 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the subscriber data records stored in Cassandra.

- If all subscriber data records are stored in Cassandra, then select (none) for all the scope options.

- If no configuration exists at this level, click Add New. |5 |Change the Lookup type option to cassandra, and click Save.

==== Promotion buckets To use the Cassandra-based provisioning service implementation as the default option for promotion buckets, in the provisioning GUI: [cols="1h,15a" width="95"]

|1 |Select Sentinel ⇒ Promotion Configuration from the menu. |2 |Click the Config tab. |3 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the promotion bucket data stored in Cassandra.

- If all promotion bucket data is stored in Cassandra, then select (none) for all the scope options.

- If no configuration exists at this level, click Add New. |4 |Change the Default data source option to cassandra, and click Save.

To use the Cassandra-based provisioning service implementation only for specific promotion buckets, in the provisioning GUI: [cols="1h,12a" width="95"]

|1 |Select Sentinel ⇒ Promotion Configuration from the menu. |2 |Click the Bucket Config tab. |3 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the scope the promotion bucket configuration data is stored at. |4 |Select one of the existing bucket configurations from the list, or click Add New to create a new one. |5 |Change the Data source option to cassandra, and click Save.

==== Configuring the Cassandra connection If using any Cassandra-based provisioning service implementations, the provisioning server must be told how to connect to it. [cols="1h,12a" width="95"]

|1 |Open a browser, and connect to the REM server where you have installed the Sentinel REM extension. |2 |Go to the Management section, and connect to the appropriate Rhino instance. |3 |Select Sentinel ⇒ Cassandra from the menu.

|4 |Click the Edit button. |5 |Fill in all the fields with the Cassandra connection information, and click Save.

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-configuration/provisioning-data-in-timesten.adoc :here: provisioning/provisioning-configuration/ :idprefix: provisioning-data-in-timesten :leveloffset: 1 = Provisioning Data in TimesTen :sortorder: 2 == Configuring JDBC provisioning lookup types and connections Below are instructions for configuring JDBC provisioning lookup types and the connection to the TimesTen database. === Configuring JDBC provisioning lookup types Sentinel comes with three JDBC-based provisioning service implementations: for subscriber data, promotion buckets, and home zones. ==== Subscriber data To use the JDBC-based provisioning service implementation for subscriber data, in the provisioning GUI: [cols="1h,19a" width="95"]

|1 |Select Sentinel ⇒ Feature Configuration from the menu. |2 |Select Subscriber Data Lookup from the Feature dropdown. |3 |Click the Lookup Config tab. |4 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the subscriber data records stored in TimesTen.

- If all subscriber data records are in TimesTen, then select (none) for all the scope options.

- If no configuration exists at this level, click Add New. |5 |Change the Lookup type option to dbQuery, and click Save.

=== Promotion buckets To use the JDBC-based provisioning service implementation as the default option for promotion buckets, in the provisioning GUI: [cols="1h,19a" width="95"]

|1 |Select Sentinel ⇒ Promotion Configuration from the menu. |2 |Click the Config tab. |3 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the promotion bucket data stored in TimesTen.

- If all promotion bucket data is in TimesTen, then select (none) for all the scope options.

- If no configuration exists at this level, click Add New. |4 |Change the Default data source option to dbquery, and click Save.

To use the JDBC-based provisioning service implementation only for specific promotion buckets, in the provisioning GUI: [cols="1h,19a" width="95"]

|1 |Select Sentinel ⇒ Promotion Configuration from the menu. |2 |Click the Bucket Config tab. |3 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the scope the promotion bucket configuration data is stored at. |4 |Select one of the existing bucket configurations from the list, or click Add New to create a new one. |5 |Change the Data source option to dbquery, and click Save.

=== Home zones To use the JDBC-based provisioning service implementation for home zones, in the provisioning GUI: [cols="1h,19a" width="95"]

|1 |Select Sentinel ⇒ Feature Configuration from the menu. |2 |Select Home Zone from the Feature dropdown. |3 |Click the Config tab. |4 |Set the Sentinel selection key scope (Network, Session Type, and so on) to correspond to the home zone zones stored in TimesTen.

- If all home zone zones are in TimesTen, then select (none) for all the scope options.

- If no configuration exists at this level, click Add New. |5 |Change the Zone lookup type option to dbQuery, and click Save.

=== Configuring TimesTen JDBC connection (using Tomcat server) If using any JDBC-based provisioning service implementations, you’ll need to configure JNDI entries in your servlet container: [cols="1h,19a" width="95"]

|1 |Install the TimesTen native client on the machine where from REM will be run. |2 |Copy `ttjdbc6.jar` from `<timesten_instance_home>/lib/` to `${CATALINA_HOME}/lib/`. |3 |Edit (or create) `${CATALINA_HOME}/bin/setenv.sh` and add some custom environment settings:

    # Specify the path to the lib directory of the local TimesTen client install
    LD_LIBRARY_PATH=/opt/TimesTen/tt1121/lib
    export LD_LIBRARY_PATH

    # (Solaris 64bit only)
    # If running on Solaris 64bit, specify the -d64 flag to run Tomcat using the 64bit JVM
    # Otherwise, Tomcat won't be able to load the 64bit TimesTen libraries
    #CATALINA_OPTS="-d64"

|4 |Edit `${CATALINA_HOME}/conf/server.xml`, and add a data source definition in the `GlobalNamingResources` section (replacing username, password, and the connection URL with whatever applies for your TimesTen setup):

    <!-- ... -->
      <GlobalNamingResources>
        <!-- ... -->
        <Resource name="SentinelDataSource" auth="Container"
                  type="javax.sql.DataSource" driverClassName="com.timesten.jdbc.TimesTenDriver"
                  url="jdbc:timesten:client:sentinelCS"
                  username="username" password="password" maxActive="50" maxIdle="30"
                  maxWait="-1"/>
      </GlobalNamingResources>
      <!-- ... -->

|5 |Edit (or create) `${CATALINA_HOME}/conf/Catalina/localhost/rem.xml`, and add resource links for whichever services you need to connect to TimesTen:

    <Context>
      <!-- For provisioning Subscriber Data records in TimesTen -->
      <ResourceLink name="jdbc/subscriberdata"
                    global="SentinelDataSource"
                    type="javax.sql.DataSource"/>

      <!-- For provisioning Promotion Buckets in TimesTen -->
      <ResourceLink name="jdbc/promotions"
                    global="SentinelDataSource"
                    type="javax.sql.DataSource"/>

      <!-- For provisioning HomeZone Zones in TimesTen -->
      <ResourceLink name="jdbc/homezone"
                    global="SentinelDataSource"
                    type="javax.sql.DataSource"/>
    </Context>

|6 |Start/restart Tomcat.

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/index.adoc :here: provisioning/provisioning-web-interface/ :idprefix: provisioning-web-interface :leveloffset: 1 = Provisioning Web Interface :indexpage: :sortorder: 2 == Accessing the provisioning web interface [NOTE] ==== Using Rhino Element Manager The provisioning web interface appears as an extension inside the Rhino Element Manager (REM) web application. For general information on using REM, see the Rhino Element Manager User Guide. To use the Sentinel provisioning web interface and machine API you will, at minimum, need to configure a Rhino instance in REM. ==== To access the Sentinel provisioning interface in REM: [cols="1h,20a"]

|1 |Open a browser, and enter the URL of the REM server where the Sentinel REM extension has been installed (for example, http://localhost:8080/rem). |2 |Enter your REM login credentials (the default account credentials are emadm / password). |3 |Select Manage a Rhino Element. |4 |Connect to the Rhino instance where Sentinel is installed. |5 |Select one of the options from the Sentinel menu.

For help using each of the Sentinel management panels, see: ==== * Managing session plans * Managing Cassandra * Managing feature execution scripts * Managing subscriber data * Using the machine API * Configuring features, services, Sentinel core, and promotions * Managing mappers * Managing plans, session types, and subscriptions * Managing normalization * Managing promotions * Managing correlation resource adaptor entities * Managing XCAP host mappings ==== TIP: For inline help using the provisioning web interface management pages, select one of the pages from the menu, and then click the help icon in the upper-right of the management screen. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-session-plans.adoc :here: provisioning/provisioning-web-interface/ :idprefix: managing-session-plans :leveloffset: 1 = Managing Session Plans :sortorder: 1 == Associating feature execution scripts with points in the session Use this management page to associate feature execution scripts with points in the session: [cols="1h,20a"]

|1 |Choose a session plan from the dropdown list.

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

| If there is no script associated at that point for the given selection key then the right panel will be blank.

| When viewing a point with an existing script association, you can click open script in editor to jump to the feature execution script management page with that script open for editing.

|4 |To set or change the script associated with a particular point and selection key:

- Click select different script.

  A list of feature execution scripts displays.

  Click image to enlarge

- Click a script to display its content.

- Click Select to associate the selected script with that point and selection key.

|5 |To remove a script association:

- Click .

  A prompt asks you to confirm the removal.

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-cassandra.adoc :here: provisioning/provisioning-web-interface/ :idprefix: managing-cassandra :leveloffset: 1 = Managing Cassandra :sortorder: 2 TIP: The following options are only required if using an Apache Cassandra database for storing any Sentinel data. == Configuration properties for Cassandra The configuration options when using Cassandra should match the configuration properties of the hector-ra resource adaptor entity. For example: image::sentinel-components/features/sip-features/sip-user-features/sentinel-em-cassandra-config.png[300, 300, link="/mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/docs/books-public/sentinel-documentation/2.9.0/sentinel-administration-guide/images/sentinel-components/features/sip-features/sip-user-features/sentinel-em-cassandra-config.png"] Click image to enlarge [NOTE] ==== The basic connection details (hosts and keyspace) should be identical to those configured on the hector-ra entity. The remaining options can be configured identically as well, or they may be different depending on your requirements. Read the Hector and Cassandra documentation for more information. ==== :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-feature-execution-scripts.adoc :here: provisioning/provisioning-web-interface/ :idprefix: managing-feature-execution-scripts :leveloffset: 1 = Managing Feature Execution Scripts :sortorder: 3 == Changing, adding, and deleting feature execution scripts To manage feature execution scripts: [cols="1h,20a"]

|1 |Select a script from the list to view and edit it.

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

| In tree editor mode, when you highlight a statement, icons display to move it up or down, or delete it: You can also use Alt+j or Alt+k to move a statement up or down, and Alt+Del to delete it.

| You can switch back and forth between the text editor and tree editor, and changes in either will be persisted back and forth (as long as they are valid). |3 |To add a new script:

- Click Add New.

  An Add New Feature Execution Script dialog box displays.

Click image to enlarge

- Enter the New script name.

- Write the script using the text editor or tree editor.

- Click Save. |4 |* To delete the selected script, click Delete Script.

  A prompt asks you to confirm the deletion.

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-subscriber-data.adoc :here: provisioning/provisioning-web-interface/ :idprefix: managing-subscriber-data :leveloffset: 1 = Managing Subscriber Data :sortorder: 4 == Scoping, loading, editing, adding, and deleting subscriber data To manage subscriber data: [cols="1h,20a"]

|1 |Subscriber data can be scoped to network operator or session type using the selection widget at the top.

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:

- Click Edit.

  The subscriber data record becomes editable.

- Make your changes, and click Save.

|4 |To add a new subscriber data record:

- Click Add New.

  Blank subscriber data fields display.

- Enter all details, and click Save.

|5 |To delete the selected subscriber data record:

- Click Delete.

  A prompt asks you to confirm the deletion.

- Click OK to delete the subscriber data record.

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/using-the-machine-api.adoc :here: provisioning/provisioning-web-interface/ :idprefix: using-the-machine-api :leveloffset: 1 = Using the Machine API :sortorder: 5 == Use RESTful HTTP The machine-provisioning API is available through RESTful HTTP. TIP: For a link to the API, select Sentinel ⇒ Machine API. NOTE: See Sentinel Provisioning REST API for more information. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/configuring-features-services-sentinel-core-promotions.adoc :here: provisioning/provisioning-web-interface/ :idprefix: configuring-features-services-sentinel-core-and-promotions :leveloffset: 1 = Configuring Features, Services, Sentinel Core and Promotions :sortorder: 6 You can use the configuration management pages (Feature Configuration, Service Configuration, Sentinel Core Configuration, and Promotion Configuration) to view, edit, add, and delete configuration data. [cols="1h,20a"]

|1 |Choose a feature from the dropdown list.

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:

- Click an entry in the list at left.

- Enter the details at right.

| Click a blue question mark icon to display help for a particular field:

- Click Save.

|4 |To add a new entry:

- Click Add New.

  Blank fields display.

- Enter details, and click Save. |5 |To delete a selection:

- Click Delete.

  A prompt asks you to confirm deleting.

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-mappers.adoc :here: provisioning/provisioning-web-interface/ :idprefix: managing-mappers :leveloffset: 1 = Managing Mappers :sortorder: 7 == Configuring mappings You can use this management page to view, add, and delete mappers and mapping sets. [cols="1s,3a"]

|To…​ |Do this:

|View mappings

|* Select one of the Mapper Sets at left.

+ Configured Mappings display at right.

Click image to enlarge

|Add a mapping

|* Click Add (in the Mappings pane).

+ Fields pop up for you to add mapping details.

- Enter the Mapping Name and, optionally, the Execution Point, Session Type, and Plan ID for the mapping.

- Click Add (to save and add another mapping) or Add and Close (to save and finish adding mappings).

|Delete mappings

|* Click the checkboxes to select mappings you want to delete.

- Click Delete (in the Mappings pane).

  A prompt displays for you to confirm deleting the selected mappings.

|Add a mapper set

|* Select a platform operator from the Mapper Sets list.

- Click Add (in the Mapper Sets pane).

  A popup prompts you to select a Network Operator.

- Select the network operator (or none to create a platform-level mapper set).

- Click Add.

|Delete a mapper set

|* Click to select the mapper set you want to delete.

- Click Delete (in the Mapper Sets pane).

  A prompt displays for you to confirm deleting the selected mapper set.

|Publish a mapper set

|* Click to select the set you want to publish.

- Click Publish (in the Mapper Sets pane).

  The next time Sentinel accesses this mapper set it will pick up any mapping changes you have made.

| Before any mapping changes can take effect, Sentinel must be notified by publishing the mapping sets. (If Rhino is restarted, Sentinel will also pick up any changes.)

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-plans-session-types-and-subscriptions.adoc :here: provisioning/provisioning-web-interface/ :idprefix: managing-plans-session-types-and-subscriptions :leveloffset: 1 = Managing Plans, Session Types and Subscriptions :sortorder: 8 == Scoping configuration data as part of the selection key You can use these management pages to view, add, edit, and delete plans, session types, and subscriptions— all of which let you scope Sentinel configuration data as part of the Sentinel configuration key. [cols="1h,20a"]

|1 |Select a network operator to view a list of plans, session types, or subscriptions configured for them; and select a particular plan, session type, or subscription to view its description.

Click image to enlarge

|2 |To add a plan, session type, or subscription for the selected operator:

- Click Add New.

  Blank Name and Description fields display.

- Enter a Name and Description for the plan, session type, or subscription.

- Click Save.

|3 |To delete the selected plan, session type, or subscription:

- Click Delete.

  A prompt asks you to confirm deleting.

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-normalization.adoc :here: provisioning/provisioning-web-interface/ :idprefix: managing-normalization :leveloffset: 1 = Managing Normalization :sortorder: 9 == Scoping and configuring normalization You can use this management page to add, edit, or delete normalization data. [cols="1h,20a"]

|1 |* Scope normalization data to the Network, Session Type, Plan ID, or Subscription ID, using the selection widget at the top.

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

  Normalization data entry fields display.

Click image to enlarge

- Enter details, and click Save.

|3 |To edit normalization data:

- Make your changes and click Save.

|4 |To delete normalization data:

- Click Delete.

  A prompt asks you to confirm the deletion.

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-promotions.adoc :here: provisioning/provisioning-web-interface/ :idprefix: managing-promotions :leveloffset: 1 = Managing Promotions :toc: macro :toclevels: 4 :toc-title: On this page…​ :sortorder: 10 toc::[] == What are promotion tables and buckets? Promotion tables configure active promotions, the conditions that apply, and the order in which to execute them. Promotion buckets hold a user’s available and reserved units for a specific promotion. == Configuring promotions === Scoping a promotion configuration Promotion configurations can be scoped to the Network, Session Type, Plan ID, or Subscription ID, using the selection widget at the top. image::sentinel-components/features/sip-features/sip-user-features/selection-widget.png[300, 300, link="/mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/docs/books-public/sentinel-documentation/2.9.0/sentinel-administration-guide/images/sentinel-components/features/sip-features/sip-user-features/selection-widget.png"] Click image to enlarge === Adding, editing, and deleting a promotion configuration To manage promotion configurations: [cols="1h,19a" width="95"]

|1 |* Click the Config tab.

+ If no promotion configuration exists at the selected level, an Add New button displays.

+

+ Click image to enlarge

+ (Otherwise, the existing promotion configuration displays.)

+

+ Click image to enlarge

|2 |To add a promotion configuration:

- Click Add New.

  Promotion configuration entry fields display.

- Enter details.

- Click Save.

|3 |To edit a promotion configuration:

- Make your changes.

- Click Save.

|4 |To delete a promotion configuration:

- Click Delete.

  A prompt asks you to confirm the deletion.

=== Editing, adding, and deleting promotion bucket configurations To manage promotion bucket configurations: [cols="1h,20a"]

|1 |* Click the Bucket Config tab.

+ A list of bucket configurations displays.

|2 |To edit a promotion bucket configuration:

- Click to select it.

  The bucket name and data source display.

  Click image to enlarge

- Select the new data source.

- Click Save.

|3 |To add a new promotion bucket configuration:

- Click Add New.

  Blank Bucket name and Data source fields display.

- Enter the new name, select a data source.

- Click Save.

|4 |To delete the selected promotion bucket configurations:

- Click Delete.

  A prompt asks you to confirm the deletion.

=== Editing, adding, and deleting SQL configurations To manage SQL configurations for promotions: [cols="1h,19a" width="95"]

|1 |* Click the SQL Config tab.

+ If there is no SQL configuration, an Add New button displays; otherwise existing SQL configuration data displays.

+

+ Click image to enlarge

|2 |To add an SQL configuration:

- Click Add New.

- Blank entry fields display.

- Enter details.

- Click Save.

|3 |To edit an SQL configuration:

- Enter details.

- Click Save.

|4 |To delete the selected SQL configuration:

- Click Delete.

  A prompt asks you to confirm the deletion.

=== Editing, adding, and deleting promotion tables To manage promotion tables: [cols="1h,20a"]

|1 |* Click the Promotion Tables tab.

+ A list of promotion tables displays.

+

+ Click image to enlarge

|2 |To add a promotion table:

- Click Add.

  A new promotion table displays at the top of the list.

|3 |To edit a promotion table:

- Click a field to make it editable.

- Make your changes.

- Click Save.

|4 |To delete a promotion table:

- Click .

  A prompt asks you to confirm the deletion.

=== Loading, editing, adding, and deleting promotion buckets To manage promotion buckets: [cols="1h,20a"]

|1 |* Click the Promotion Buckets tab.

|2 |To load a promotion bucket:

- Enter the SubscriberId and BucketName.

- Click Load.

  That promotion bucket displays.

  Click image to enlarge

|3 |To edit the loaded promotion bucket:

- Click Edit.

  That bucket’s details become editable.

- Make your changes, and click Save.

|4 |To delete the loaded promotion bucket:

- Click Delete.

  A prompt asks you to confirm the deletion.

|5 |To add a new promotion bucket:

- Click Add New.

  Fields display for you to enter details for the new promotion bucket.

  Click image to enlarge

- Enter the SubscriberId, BucketName, and other details.

- Click Save.

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-correlation-resource-adaptor-entities.adoc :here: provisioning/provisioning-web-interface/ :idprefix: managing-correlation-resource-adaptor-entities :leveloffset: 1 = Managing Correlation Resource Adaptor Entities :sortorder: 11 == Configuring Correlation Resource Adaptor Entities NOTE: For general information on the Correlation RA and its use in Sentinel, please see Correlation Resource Adaptor. To configure correlation resource adaptor entities: [cols="1h,20a"]

|1 |* Select an RA Entity from the drop-down list.

+ Resource adaptor entity correlation details display.

+

+ Click image to enlarge

- Enter correlation details, and click Save.

| You can configure and manage resource adaptor entities by clicking on the links to the right of the RA Entity dropdown list.

|2 |* Click the ID Pools tab.

+ Corellation ID pools display.

|3 |* Click an ID pool to display its details.

+ ID pool correlation details display.

+

+ Click image to enlarge

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-web-interface/managing-xcap-host-mappings.adoc :here: provisioning/provisioning-web-interface/ :idprefix: managing-xcap-host-mappings :leveloffset: 1 = Managing XCAP Host Mappings :sortorder: 12 == Changing, adding, and deleting XCAP host mappings To manage XCAP host mappings: [cols="1,3a" width="80"]

|To…​ |Do this:

|View and edit an XCAP host mapping |* Select from the XCAP Host Mappings list.

+ Mapping details display.

+

+ Click image to enlarge

- Make any changes.

- Click Save.

|Add a new XCAP host mapping

|* Click Add New.

+ An empty XCAP host mapping displays.

+

+ Click image to enlarge

- Enter details.

- Click Save.

| Delete the selected XCAP host mapping.

|* Click Delete Mapping.

+ A prompt asks you to confirm the deletion.

- Click OK.

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/provisioning-auditing.adoc :here: provisioning/ :idprefix: provisioning-auditing :leveloffset: 1 = Provisioning Auditing :sortorder: 5 The Sentinel provisioning system audits every write operation (create, update, and delete) that goes through it. 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 `log4j2.properties` file. ---- logger.audit.name=sentinel.audit logger.audit.level=INFO logger.audit.additivity=false logger.audit.appenderRef.audit.ref=AUDIT appender.AUDIT.type = RollingFile appender.AUDIT.name = AUDIT appender.AUDIT.fileName = ${rem.home}/sentinel-audit.log appender.AUDIT.layout.type = PatternLayout appender.AUDIT.layout.Pattern = "%d{yyyy-MM-dd HH:mm:ss,SSS}", "%c{1}", %m%n appender.AUDIT.maxFileSize = 10MB appender.AUDIT.maxBackupIndex=10 ---- If you wish to disable the audit messages completely then add the following settings to the REM or Tomcat `log4j.properties` file. ---- logger.audit.level=NONE ---- :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/provisioning/xcap-api.adoc :here: provisioning/ :idprefix: using-the-xcap-api :leveloffset: 1 = Using the XCAP API :sortorder: 6 The Sentinel REM extension provides a very basic XCAP API. More extensive XCAP server functionality is available in the Sentinel VoLTE product, but custom XCAP server functionality can be added fairly easily with the Sentinel SDK. [TIP] ==== Using Rhino Element Manager To use the Sentinel XCAP API, you will (at minimum) need to configure a Rhino instance using the Rhino Element Manager (REM). For general information on using REM, please see the Rhino Element Manager User Guide. ==== Below are details on: ==== * Managing XCAP host mappings * Accessing the XCAP API * Adding XCAP services ==== == Managing XCAP host mappings XCAP host mappings control which Rhino instance, REM user account are used when handling an XCAP request. For managing XCAP host mappings using the provisioning web interface, see Managing XCAP host mappings. XCAP host mappings can also be managed using the XCAP Server Configuration REST API. == Accessing the XCAP API To access the XCAP API: [cols="1h,20a"]

|1 |Ensure the Sentinel REM extension is installed in REM. |2 |Start REM. |3 |The base XCAP URI is http://localhost:8080/rem/sentinel/xcap (replace localhost with some other hostname if REM is not being run locally).

The only resource available in the XCAP server provided with Sentinel is the mandatory xcap-caps index at http://localhost:8080/rem/sentinel/xcap/xcap-caps/index.

| Access is not restricted as it is assumed XCAP requests have passed through a separate XCAP authentication proxy (AP) first.

Requests are filtered though, so only requests using a hostname that matches a valid XCAP host mapping configuration in REM will be accepted. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/sentinel-alarms.adoc :here: :idprefix: sentinel-alarms :leveloffset: 1 = Sentinel Alarms :sortorder: 5 == Alarms raised by Sentinel [cols="1*a"]

|

[cols="1*a"]

|

[cols="1*a"]

|

NOTE: Alarms may also be raised by the other components used by Sentinel (such as SIS, DB Query RA, and CDR RA). == Threshold alarms Sentinel produces a variety of statistics that can be used to configure threshold alarms in Rhino. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/index.adoc :here: charging-information/ :idprefix: charging-information :leveloffset: 1 = Charging Information :indexpage: Charging Information describes the format and content of CDR files, and the information present in Diameter Ro. == Topics * CDR Formats— describes the formats used for CDRs * Working with CDRs— describes tooling to extract the content of CDRs * Ro Interface AVPs— describes the population of AVPs on the Ro interface * Charging Content AVPs— describes the populated AVPs for both online and offline charging * Interim CDRs— describes Interim CDRs for offline charging * Sizing AVP CDRs— describes sizing requirements when using AVP CDRs :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/cdr-formats/index.adoc :here: charging-information/cdr-formats/ :idprefix: cdr-formats :leveloffset: 1 = CDR Formats :indexpage: Sentinel supports two CDR formats "out of the box". These are the AVP CDR format, and the legacy format. Note that Sentinel can be configured to use a user provided CDR format, or even no CDRs. == AVP CDRs An AVP CDR is an OpenCloud defined CDR that contains AVPs. This type of CDR is consistent with the approaches used in Diameter Ro and Diameter Rf interfaces. An AVP CDR contains AVPs that are standardised (e.g. 3GPP and IETF), or non-standardised (e.g. product specific or project specific). AVP CDRs can almost be considered an "on-disk" form of the content contained in the Rf interface. AVP CDRs are used by default in the Sentinel SIP service. The Sentinel SIP service can be configured to use the legacy format. == Legacy CDRs A legacy CDR is an OpenCloud defined CDR that is used in the Sentinel product set prior to (and during) the introduction of AVP CDRs. The product continues support for this format so that customers who use this format do not need migrate. Legacy CDRs remain in use by the Sentinel SS7 and Sentinel Diameter services. == Topics * AVP CDR Format— describes the formats used for AVP CDRs * Legacy CDR Format— describes the format used for Legacy CDRs :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/cdr-formats/avp-cdr-format.adoc :here: charging-information/cdr-formats/ :idprefix: avp-cdr-format :leveloffset: 1 = AVP CDR Format AVP CDRs have logical content, and an on-disk format. == Logical content Each CDR inside a CDR file has logical content. We use a BNF syntax to describe this logical content. ---- CDR ::= [ Subscription-Id ] [ IMS-Information ] [ User-Equipment-Info ] *[ Multiple-Services-Credit-Control ] [ OC-Call-Type ] [ OC-Service-Type ] [ OC-Charging-Result ] *[ OC-OCS-Session-Id ] [ OC-OCS-Session-Termination-Cause ] [ OC-Sentinel-Error ] *[ OC-Charging-Instance ] [ OC-Event-Id ] [ OC-Call-Id ] [ OC-End-Session-Cause ] [ OC-Session-Start-Time ] [ OC-Session-Established-Time ] [ OC-Session-End-Time ] [ OC-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; message AvpCdr { repeated AVP avps = 1; message AVP { required bytes avpData = 1; // The Diameter binary encoded AVP data required string interfaceName = 2; // The interface which the AVP is being written out as, e.g "Rf", "Ro" required string specRevision = 3; // E.g. "vcb0" optional string avpName = 4; } } ---- :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/cdr-formats/legacy-cdr-format.adoc :here: charging-information/cdr-formats/ :idprefix: legacy-cdr-format :leveloffset: 1 = Legacy CDR Format :toc: macro :toclevels: 4 :toc-title: On this page…​ The Legacy CDR format has an on-disk format defined using Google protocol buffers (aka `protobuf`). There is a common "types definition" schema file that is used by multiple Sentinel Services for their CDRs. These types are called "base types". Each Sentinel Service then defines its own CDRs using these types and defining its own types. toc::[] == Base types The base types are used in CDRs for Sentinel SS7, Sentinel Diameter Mediation. ---- package com.opencloud.sentinel.cdr; message CdrSessionCounters { repeated CdrSessionCounterAccess counters = 1; } message CdrSessionCounterAccess { required string subscriberId = 1; required string bucketName = 2; optional int64 cumulativeRequestedUnits = 3; optional int64 cumulativeGrantedUnits = 4; optional int64 cumulativeSentUsedUnits = 5; optional int64 cumulativeCommittedUsedUnits = 6; optional int64 cumulativeRequestedRefundUnits = 7; optional int64 cumulativeGrantedRefundUnits = 8; repeated CdrSessionSubCounterAccess subCounters = 9; } message CdrSessionSubCounterAccess { required string subCounterId = 1; optional int64 cumulativeRequestedUnits = 3; optional int64 cumulativeGrantedUnits = 4; optional int64 cumulativeSentUsedUnits = 5; optional int64 cumulativeCommittedUsedUnits = 6; optional int64 cumulativeRequestedRefundUnits = 7; optional int64 cumulativeGrantedRefundUnits = 8; repeated CdrSessionSubCounterAccess subCounters = 9; } message Time { required int64 milliseconds_since_epoch = 1; required sint32 zoneoffset_minutes = 2; } enum SentinelError { None = 1; OcsTimeout = 2; OcsCommunicationFailure = 3; SentinelOverload = 4; ProtocolError = 5; InternalError = 6; MappingError = 7; OtherError = 8; } ---- == Sentinel SS7 Service CDR format The Sentinel SS7 service defines two CDR formats, one for CAP calls, and the other for CAP3 SMS. === CAP Calls CAP call use the following format for its CDR files (out of the box). ---- package com.opencloud.sentinel.cdr; import "com/opencloud/sentinel/cdr/base-cdr-types.proto"; message Ss7CallCdr { optional string subscriber = 1; optional int32 initiatingDialogId = 2 [default = -1]; optional Time eventInitiated = 3; optional Time sessionInitiated = 4; optional Time sessionEstablished = 5; optional Time sessionEnded = 6; optional CallType callType = 7; optional string callingPartyNumber = 8; optional string calledPartyNumber = 9; optional string mscNumber = 10; optional int32 serviceKey = 11 [default = -1]; optional ConnectCause connectCause = 12; optional int32 releaseCause = 13; optional sint32 chargingResult = 14 [default = -1]; optional int64 cumulativeReported = 15; optional CdrSessionCounters sessionCounters = 21; repeated int32 ocsLatencySamples = 23 [packed=true]; repeated int32 announcementIDs = 25; optional int64 callReferenceNumber = 26; optional sint32 bearerService = 27 [default = -1]; optional sint32 teleService = 28 [default = -1]; optional ServiceType serviceType = 29 [default = Unknown]; optional SentinelError sentinelError = 30 [default = None]; optional string sentinelSelectionKey = 31; repeated string ocsSessionIDs = 32; repeated CallInformationReport callInformationReports = 33; optional bool creditHasBeenReauthorized = 34; optional int32 ocsSessionTerminationCause = 35; extensions 50 to max; enum CallType { MOC = 1; MOC_3RDPTY = 2; MTC = 3; MFC = 4; MOSMS = 5; MTSMS = 6; GPRS = 7; ACCOUNT_INQUIRY = 8; EMERGENCY_CALL = 9; } enum ServiceType { Unknown = 1; Voice = 2; Data = 3; Fax = 4; Video = 5; } enum ConnectCause { UnknownCause = 1; APartyAbandoned = 2; NoAnswer = 4; UserBusy = 5; RouteSelectFailure = 6; Answer = 7; Abort = 8; Error = 9; } message CallInformationReport { optional int32 legId = 1; optional int32 callAttemptElapsedTime = 2; optional int32 callConnectedElapsedTime = 3; optional Time callStopTime = 4; optional int32 releaseCause = 5; } } ---- === CAP3 SMS CAP3 SMS support ses the following format for its CDR files (out of the box). ---- package com.opencloud.sentinel.cdr; import "com/opencloud/sentinel/cdr/base-cdr-types.proto"; message Ss7SmsCdr { optional string subscriber = 1; optional int32 initiatingDialogId = 2 [default = -1]; optional Time eventInitiated = 3; optional Time sessionInitiated = 4; optional Time sessionEstablished = 5; optional Time sessionEnded = 6; optional SmsType callType = 7; optional string callingPartyNumber = 8; optional string calledPartyNumber = 9; optional string mscNumber = 10; optional int32 serviceKey = 11 [default = -1]; optional int32 releaseCause = 13; optional sint32 chargingResult = 14 [default = -1]; optional int64 cumulativeReported = 15; optional CdrSessionCounters sessionCounters = 21; repeated int32 ocsLatencySamples = 23 [packed=true]; optional int64 smsReferenceNumber = 26; optional SentinelError sentinelError = 30 [default = None]; optional string sentinelSelectionKey = 31; repeated string ocsSessionIDs = 32; optional int32 ocsSessionTerminationCause = 35; extensions 50 to max; enum SmsType { MOSMS = 1; MTSMS = 2; } } ---- == Sentinel Diameter Mediation Service CDR format The Sentinel Diameter Mediation service defines a CDR format. ---- package com.opencloud.sentinel.cdr; import "com/opencloud/sentinel/cdr/base-cdr-types.proto"; message DiameterChargingCdr { optional string subscriber = 1; optional int64 initiatingRequestId = 2 [default = -1]; optional Time eventInitiated = 3; optional Time sessionInitiated = 4; optional Time sessionEnded = 5; optional CdrSessionCounters sessionCounters = 6; repeated int32 ocsLatencySamples = 19 [packed=true]; optional string clientSessionId = 20; repeated string ocsSessionIDs = 21; optional string sentinelSelectionKey = 22; extensions 50 to max; } ---- :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/charging-content-avps/index.adoc :here: charging-information/charging-content-avps/ :idprefix: charging-content-avps :leveloffset: 1 = Charging Content AVPs :indexpage: :toc: macro :toclevels: 4 :toc-title: On this page…​ The population of AVPs for Sentinel SIP is described on this page. A definition of the AVPs used for the Sentinel Express product is provided on Sentinel AVP definitions. toc::[] == Detecting Online Charging The OC-Charging-Result AVP in a CDR indicates whether online (Diameter Ro) charging was used for a session. This may be used to determine if further action is needed when processing CDRs offline. * An `OC-Charging-Result` value of `-1` means that online charging was not used for the session. * Otherwise the value is set to the Diameter `Result-Code` AVP value. == Populated AVPs in the Multiple-Services-Credit-Control AVP The Multiple-Services-Credit-Control AVP is of type grouped, and is defined in RFC 4006. Section 7.1.4 of 3GPP TS 32.299 defines it with additional 3GPP specific parameters and states some IETF parameters are not used in the 3GPP. [cols="2,3,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | Requested-Service-Unit | IETF RFC 4006 | No | Yes | No | Used in the CCR. The CDR represents this information in the OC-Session-Counter AVP | Used-Service-Unit | IETF RFC 4006 and 3GPP TS 32.299 | No | Yes | No | Used in the CCR according to Populated AVPs in the Used-Service-Unit AVP. The CDR represents this information in the OC-Session-Counter AVP | Service-Identifier | IETF RFC 4006 | Yes | Yes | Yes | For Originating attempts the AVP has the value `1`. For Forwarded attempts the AVP has the value `2`. For Terminating attempts the AVP has the value `3`. For Network Initiated attempts the AVP has the value `4`. For Immediate Event Charging the AVP has the value `50`. | Rating-Group | IETF RFC 4006 and 3GPP TS 32.299 v12.11.0 section 7.1.10 | No | Yes | No | This AVP is set according to Session Counters and the `ratingGroup` session state field. | Reporting-Reason | 3GPP TS 32.299 v12.11.0 section 7.2.175 | No | Yes | No | | Trigger | 3GPP TS 32.299 v12.11.0 section 7.2.235 | No | No | No | | PS-Furnish-Charging-Information | 3GPP TS 32.299 v12.11.0 section 7.2.157 | No | No | No | | Refund-Information | 3GPP TS 32.299 v12.11.0 section 7.2.171 | No | No | No | | AF-Correlation-Information | 3GPP TS 32.299 v12.11.0 section 7.2.11 | No | No | No | | Envelope | 3GPP TS 32.299 v12.11.0 section 7.2.59 | No | No | No | | Envelope-Reporting | 3GPP TS 32.299 v12.11.0 section 7.2.61 | No | No | No | | Time-Quota-Mechanism | 3GPP TS 32.299 v12.11.0 section 7.2.228 | No | No | No | | Service-Specific-Info | 3GPP TS 32.299 v12.11.0 section 7.2.195 | No | No | No | | QoS-Information | 3GPP TS 29.212 | No | No | No |

The BNF syntax for this AVP in 32.299 v12.11.0 is as follows: ---- <Multiple-Services-Credit-Control> ::= < AVP Header: 456 > [ Granted-Service-Unit ] // not used in CCR [ Requested-Service-Unit ] * [ Used-Service-Unit ] [ Tariff-Change-Usage ] // not used in 3GPP * [ Service-Identifier ] [ Rating-Group ] * [ G-S-U-Pool-Reference ] // not used in CCR [ Validity-Time ] // not used in CCR [ Result-Code ] // not used in CCR [ Final-Unit-Indication ] // not used in CCR [ Time-Quota-Threshold ] // not used in CCR [ Volume-Quota-Threshold ] // not used in CCR [ Unit-Quota-Threshold ] // not used in CCR [ Quota-Holding-Time ] // not used in CCR [ Quota-Consumption-Time ] // not used in CCR * [ Reporting-Reason ] [ Trigger ] [ PS-Furnish-Charging-Information ] [ Refund-Information ] * [ AF-Correlation-Information] * [ Envelope ] [ Envelope-Reporting ] [ Time-Quota-Mechanism ] * [ Service-Specific-Info ] [ QoS-Information ] * [ AVP ] // not used in 3GPP ---- === Populated AVPs in the Used-Service-Unit AVP The Used-Service-Unit AVP is defined in IETF RFC 4006, and then its BNF is modified slightly in 3GPP TS 32.299 section 7.1.9. [cols="2,3,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | Reporting-Reason | 3GPP TS 32.299 v12.11.0 section 7.2.175 | No | No | No | | Tariff-Change-Usage | IETF RFC 4006 | No | No | No | | CC-Time | IETF RFC 4006 | No | Yes | No | Used by default as the unit type for SIP Sessions | CC-Money | IETF RFC 4006 | No | No typically | No | Not used out-of-the-box for Sentinel SIP | CC-Total-Octets | IETF RFC 4006 | No | Not typically | No | Not used out-of-the-box for Sentinel SIP | CC-Input-Octets | IETF RFC 4006 | No | Not typically | No | Not used out-of-the-box for Sentinel SIP | CC-Output-Octets | IETF RFC 4006 | No | Not typically | No |Not used out-of-the-box for Sentinel SIP | CC-Service-Specific-Units | IETF RFC 4006 | Not typically | No | Is used in Sentinel IP-SM-GW

The 3GPP definition (in v12.11.0) is ---- <Used-Service-Unit> ::= < AVP Header: 446 > [ Reporting-Reason ] [ Tariff-Change-Usage ] [ CC-Time ] [ CC-Money ] // not used in 3GPP [ CC-Total-Octets ] [ CC-Input-Octets ] [ CC-Output-Octets ] [ CC-Service-Specific-Units ] *[ Event-Charging-TimeStamp ] *[ AVP ] // not used in 3GPP ---- == Populated AVPs in the Service-Information AVP The Service-Information AVP is defined in 3GPP TS 32.299 v12.11.0. It is a grouped AVP. This table lists the AVPs grouped within Service-Information and how the product populates them. [cols="2,3,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | SMS-Information | 32.299 v12.11.0 section 7.2.211 | Yes | Yes | Yes | The Sentinel IP-SM-GW product populates this AVP | MMTel-Information | 32.299 v12.11.0 section 7.2.111 | Yes | Yes | Yes | The Sentinel VoLTE product populates this AVP | Subscription-Id | IETF RFC 4006 | Yes | No | Yes | 3GPP TS 32.299 v12.11.0 states that it should be set on the Rf interface, not the Ro interface (see section 7.2.149) | AoC-Information | 32.299 v12.11.0 section 7.2.15 | No | No | No | Sentinel does not implement the advice of charge service out-of-the-box | PS-Information | 32.299 v12.11.0 section 7.2.158 | No | No | Yes | PS-Information AVP contains EPC layer information. It is only added in ACRs as a means of sending the IMEI in the User-Equipment-Information AVP. | IMS-Information | 32.299 v12.11.0 section 7.2.77 | Yes | Yes | Yes | See the IMS-Information table for further details | MMS-Information | 32.299 v12.11.0 section 7.2.110 | No | No | No | Sentinel does not implement any MMS node roles out-of-the-box | LCS-Information | 32.299 v12.11.0 section 7.2.89 | No | No | No | | PoC-Information | 32.299 v12.11.0 section 7.2.144 | No | No | No | Sentinel does not implement the PoC service out-of-the-box | MBMS-Information | 32.299 v12.11.0 section 7.2.99 | No | No | No | Sentinel does not implement the MBMS service out-of-the-box | SMS-Information | 32.299 v12.11.0 section 7.2.211 | No | No | No | Sentinel does not implement the SMS service out-of-the-box | VCS-Information | 32.299 v12.11.0 section 7.2.242A | No | No | No | | MMTel-Information | 32.299 v12.11.0 section 7.2.111 | Yes | Yes | Yes | | ProSe-Information | 32.299 v12.11.0 section 7.2.154I | No | No | No | | Service-Generic-Information | 32.299 v12.11.0 section 7.2.191 | No | No | No | | IM-Information | 32.299 v12.11.0 section 7.2.69 | No | No | No | Sentinel does not implement IM services out-of-the-box | DCD-Information | 32.299 v12.11.0 section 7.2.50 | No | No | No |

The BNF for the AVP is defined in section 7.2.149. It is as follows: ---- Service-Information :: = < AVP Header: 873> * [ Subscription-Id ] [ AoC-Information ] [ PS-Information ] [ IMS-Information ] [ MMS-Information ] [ LCS-Information ] [ PoC-Information ] [ MBMS-Information ] [ SMS-Information ] [ VCS-Information ] [ MMTel-Information ] [ ProSe-Information ] [ Service-Generic-Information ] [ IM-Information ] [ DCD-Information ] ---- == Populated AVPs in the PS-Information AVP The PS-Information AVP is defined in 3GPP TS 32.299 v12.11.0. It is a grouped AVP. This table lists the AVPs grouped within PS-Information and how the product populates them. [cols="2,3,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | User-Equipment-Info | IETF RFC 4006 | No | No | Yes | The IMEI is used rather than the IMEISV, and the User-Equipment-Type AVP is set to IMEISV. For CCRs and CDRs this AVP is present as a top level AVP.

The BNF for the AVP is defined in section 7.2.158. It is as follows: ---- PS-Information :: = < AVP Header: 874> [ 3GPP-Charging-Id ] [ PDN-Connection-Charging-ID ] [ Node-Id ] [ 3GPP-PDP-Type ] * [ PDP-Address ] [ PDP-Address-Prefix-Length ] [ Dynamic-Address-Flag ] [ Dynamic-Address-Flag-Extension ] [ QoS-Information ] * [ SGSN-Address ] * [ GGSN-Address ] * [ TDF-IP-Address ] * [ SGW-Address ] * [ ePDG-Address ] [ CG-Address ] [ Serving-Node-Type ] [ SGW-Change ] [ 3GPP-IMSI-MCC-MNC ] [ IMSI-Unauthenticated-Flag ] [ 3GPP-GGSN-MCC-MNC ] [ 3GPP-NSAPI ] [ Called-Station-Id ] [ 3GPP-Session-Stop-Indicator ] [ 3GPP-Selection-Mode ] [ 3GPP-Charging-Characteristics ] [ Charging-Characteristics-Selection-Mode ] [ 3GPP-SGSN-MCC-MNC ] [ 3GPP-MS-TimeZone ] [ Charging-Rule-Base-Name ] [ ADC-Rule-Base-Name ] [ 3GPP-User-Location-Info ] [ User-Location-Info-Time ] [ User-CSG-Information ] [ Presence-Reporting-Area-Information ] [ 3GPP2-BSID ] [ TWAN-User-Location-Info ] [ 3GPP-RAT-Type ] [ PS-Furnish-Charging-Information ] [ PDP-Context-Type ] [ Offline-Charging ] * [ Traffic-Data-Volumes ] * [ Service-Data-Container ] [ User-Equipment-Info ] [ Terminal-Information ] [ Start-Time ] [ Stop-Time ] [ Change-Condition ] [ Diagnostics ] [ Low-Priority-Indicator ] [ MME-Number-for-MT-SMS ] [ MME-Name ] [ MME-Realm ] [ Logical-Access-ID ] [ Physical-Access-ID ] [ Fixed-User-Location-Info ] [ CN-Operator-Selection-Entity ] ---- === Populated AVPs in the IMS-Information AVP The IMS-Information AVP is defined in 3GPP TS 32.299 v12.11.0. It is a grouped AVP. This table lists the AVPs grouped within IMS-Information and how the product populates them. [cols="2,3,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | Event-Type | 32.299 v12.11.0 section 7.2.65 | Yes | Yes | Yes | | Role-Of-Node | 32.299 v12.11.0 section 7.2.177 | Yes | Yes | Yes | Sessions with sescase of `orig` and `orig_cdiv` are in `ORIGINATING_ROLE` | Node-Functionality | 32.299 v12.11.0 section 7.2.113 | Yes | Yes | Yes | Set to value `6` as `AS` | User-Session-Id | 32.299 v12.11.0 section 7.2.242 | Yes | Yes | Yes | Set to the Call-Id for the initial request | Outgoing-Session-Id | 32.299 v12.11.0 section 7.2.128A | No | No | No | | Session-Priority | 29.229 | Yes | Yes | Yes | Set to value `2` | Calling-Party-Address | 32.299 v12.11.0 section 7.2.33 | Yes | Yes | Yes | | Called-Party-Address | 32.299 v12.11.0 section 7.2.32 | Yes | Yes | Yes | | Called-Asserted-Identity | 32.299 v12.11.0 section 7.2.31 | Yes | Yes | Yes | | Number-Portability-Routing-Information | 32.299 v12.11.0 section 7.2.120 | No | No | No | | Carrier-Select-Routing-Information | 32.299 v12.11.0 section 7.2.34 | No | No | No | | Alternate-Charged-Party-Address | 32.299 v12.11.0 section 7.2.12 | No | No | No | | Requested-Party-Address | 32.299 v12.11.0 section 7.2.176 | Yes | Yes | Yes | This field is only included if different from the `Called-Party-Address` | Associated-URI | 32.299 v12.11.0 section 7.2.26 | No | No | No | | Application-Server-Information | 32.299 v12.11.0 section 7.2.24 | No | No | No | | Inter-Operator-Identifier | 32.299 v12.11.0 section 7.2.80 | Yes | Yes | Yes | | Transit-IOI-List | 32.299 v12.11.0 section 7.2.233B | No | No | No | | IMS-Charging-Identifier | 32.299 v12.11.0 section 7.2.75 | Yes | Yes | Yes | | SDP-Session-Description | 32.299 v12.11.0 section 7.2.184 | Yes | Yes | Yes | | SDP-Media-Component | 32.299 v12.11.0 section 7.2.180 | Yes | Yes | Yes | | Served-Party-IP-Address | 32.299 v12.11.0 section 7.2.187 | No | No | No | | Server-Capabilities | 29.229 | No | No | No | | Trunk-Group-ID | 32.299 v12.11.0 section 7.2.237 | No | No | No | | Bearer-Service | 32.299 v12.11.0 section 7.2.30 | No | No | No | | Service-Id | 32.299 v12.11.0 section 7.2.190 | No | No | No | | Service-Specific-Info | 32.299 v12.11.0 section 7.2.195 | No | No | No | | Message-Body | 32.299 v12.11.0 section 7.2.103 | No | No | No | | Cause-Code | 32.299 v12.11.0 section 7.2.35 | Yes | Yes | Yes | | Reason-Header |32.299 v12.11.0 section 7.2.164A | No |No | No | | Access-Network-Information | 32.299 v12.11.0 section 7.2.1 | Yes | Yes | Yes | The first value in the SIP P-Access-Network-Info header is included as the value for this AVP | Early-Media-Description | 32.299 v12.11.0 section 7.2.58 | Yes | Yes | Yes | The most recent Early Media offer/answer is included | IMS-Communication-Service-Identifier | 32.299 v12.11.0 section 7.2.76 | Yes | Yes | Yes | | IMS-Application-Reference-Identifier | 32.299 v12.11.0 section 7.2.74A | No | No | No | | Online-Charging-Flag | 32.299 v12.11.0 section 7.2.122 | No | No | No | | Real-Time-Tariff-Information | 32.299 v12.11.0 section 7.2.164 | No | No | No | | Account-Expiration | 32.299 v12.11.0 section 7.2.2 | No | No | No | | Initial-IMS-Charging-Identifier | 32.299 v12.11.0 section 7.2.79A | No | No | No | | NNI-Information | 32.299 v12.11.0 section 7.2.112A | No | No | No | | From-Address | 32.299 v12.11.0 section 7.2.67A | No | No | No | | IMS-Emergency-Indicator | 32.299 v12.11.0 section 7.2.76A | No | No | No | | IMS-Visited-Network-Identifier | 32.299 v12.11.0 section 7.2.77A | No | No | No | | Access-Transfer-Information | 32.299 v12.11.0 section 7.2.1A | No | No | No | | Related-IMS-Charging-Identifier | 32.299 v12.11.0 section 7.2.171B | No | No | No | | Related-IMS-Charging-Identifier-Node | 32.299 v12.11.0 section 7.2.171C | No | No | No | | Route-Header-Received | 32.299 v12.11.0 section 7.2.177A | No | No | No | | Route-Header-Transmitted | 32.299 v12.11.0 section 7.2.177B | No | No | No | | Instance-Id | 32.299 v12.11.0 section 7.2.70A | No | No | No | | TAD-Identifier | 32.299 v12.11.0 section 7.2.219A | No | No | No |

The BNF syntax for the IMS-Information AVP according to 3GPP TS 32.299 v12.11.0 is as follows ---- IMS-Information :: = < AVP Header: 876> [ Event-Type ] [ Role-Of-Node ] { Node-Functionality } [ User-Session-Id ] [ Outgoing-Session-Id ] [ Session-Priority ] * [ Calling-Party-Address ] [ Called-Party-Address ] * [ Called-Asserted-Identity ] [ Number-Portability-Routing-Information ] [ Carrier-Select-Routing-Information ] [ Alternate-Charged-Party-Address ] * [ Requested-Party-Address ] * [ Associated-URI ] [ Time-Stamps ] * [ Application-Server-Information ] * [ Inter-Operator-Identifier ] * [ Transit-IOI-List ] [ IMS-Charging-Identifier ] * [ SDP-Session-Description ] * [ SDP-Media-Component ] [ Served-Party-IP-Address ] [ Server-Capabilities ] [ Trunk-Group-ID ] [ Bearer-Service ] [ Service-Id ] * [ Service-Specific-Info ] * [ Message-Body ] [ Cause-Code ] * [ Reason-Header ] * [ Access-Network-Information ] * [ Early-Media-Description ] [ IMS-Communication-Service-Identifier ] [ IMS-Application-Reference-Identifier ] [ Online-Charging-Flag ] [ Real-Time-Tariff-Information ] [ Account-Expiration ] [ Initial-IMS-Charging-Identifier ] * [ NNI-Information ] [ From-Address ] [ IMS-Emergency-Indicator ] [ IMS-Visited-Network-Identifier ] * [ Access-Transfer-Information ] [ Related-IMS-Charging-Identifier ] [ Related-IMS-Charging-Identifier-Node ] [ Route-Header-Received ] [ Route-Header-Transmitted ] [ Instance-Id ] [TAD-Identifier] ---- == Populated OpenCloud AVPs The population of OpenCloud AVPs is described here. The definition of OpenCloud AVPs is provided in Sentinel AVP definitions. [cols="1,2,1,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments | OC-Sentinel-Selection-Key | OC-Sentinel-Selection-Key | Yes | No | Yes | n/a | OC-Play-Announcement-Id | OC-Play-Announcement-Id | Yes | No | Yes | n/a | OC-Call-Type | OC-Call-Type | Yes | No | Yes | Role-Of-Node AVP has similar meaning on the Ro interface | OC-Service-Type | OC-Service-Type | Yes | No | Yes | n/a | OC-Charging-Result | OC-Charging-Result | Yes | No | Yes | | OC-OCS-Session-Id | OC-OCS-Session-Id | Yes | No | Yes | This is the session ID in Ro | OC-OCS-Session-Termination-Cause | OC-OCS-Session-Termination-Cause | Yes | No | Yes | | OC-Sentinel-Error | OC-Sentinel-Error | Yes | No | Yes | | OC-Charging-Instance | OC-Charging-Instance | Yes | No | Yes | | OC-Event-Id | OC-Event-Id | Yes | No | Yes | | OC-Call-Id | OC-Call-Id | Yes | No | Yes | The Ro Session Id optional part includes the SIP Call ID | OC-End-Session-Cause | OC-End-Session-Cause | Yes | No | Yes | | OC-Start-Time | OC-Start-Time | Yes | No | Yes | | OC-End-Time | OC-End-Time | Yes | No | Yes | | OC-Session-Start-Time | OC-Session-Start-Time | Yes | No | Yes | | OC-Session-Established-Time | OC-Session-Established-Time | Yes | No | Yes | Included if an INVITE session is answered | OC-Session-End-Time | OC-Session-End-Time | Yes | No | Yes | | OC-Session-Counter | OC-Session-Counter | Yes | No | Yes | | OC-Interim-CDR-Trigger | OC-Interim-CDR-Trigger | Yes | No | Yes | | OC-Access-Network-MCC-MNC | OC-Access-Network-MCC-MNC| Yes | Yes | Yes | | OC-Visited-Network-MCC-MNC | OC-Visited-Network-MCC-MNC | Yes | Yes | Yes | | OC-IMSI-MCC-MNC | OC-IMSI-MCC-MNC | Yes | Yes | Yes |

:leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/charging-content-avps/sentinel-avp-definitions.adoc :here: charging-information/charging-content-avps/ :idprefix: sentinel-avp-definitions :leveloffset: 1 = Sentinel AVP Definitions :toc: macro :toclevels: 4 :toc-title: On this page…​ The following AVPs are OpenCloud defined AVPs used in the Sentinel Express product. All OpenCloud defined AVPs have a diameter vendor ID of 19808. toc::[] == OpenCloud defined AVPs === OC-Sentinel-Selection-Key The OC-Sentinel-Selection-Key AVP (AVP code 1001) is of type UTF8String and contains the Sentinel Selection Key for the session. No Parent AVP. === OC-Play-Announcement-Id The OC-Play-Announcement-Id AVP (AVP code 1002) is of type Integer32 and contains the ID of an announcement used during the session. No Parent AVP. === OC-Call-Type The OC-Call-Type AVP (AVP code 1003) is of type Enumerated and specifies the type of trigger for the session. It can be one of the following: * `MOC` = 1, the trigger was Originating * `MOC_3RDPTY` = 2, the trigger was a non-SIP third party call setup request (e.g. via HTTP) * `MTC` = 3, the trigger was Terminating * `MFC` = 4, the trigger was Forwarding * `EMERGENCY_CALL` = 9, the trigger was classified as emergency No Parent AVP. === OC-Service-Type The OC-Service-Type AVP (AVP code 1004) is of type Enumerated and specifies the initiating message for the session. It can be one of the following: * `UNKNOWN` = 1, the initiating reason is unknown * `SipCall` = 2, the session was initiated due to receipt of SIP INVITE * `Subscription` = 3, the session was initiated due to receipt of SIP SUBSCRIBE * `Message` = 5, the session was initiated due to receipt of SIP MESSAGE No Parent AVP. === OC-Charging-Result The OC-Charging-Result AVP (AVP code 1006) is of type Integer32. It contains the value of the Diameter CCA result-code AVP. In case there was no Ro session, it will have the value of -1. No Parent AVP. === OC-OCS-Session-Id The OC-OCS-Session-Id AVP (AVP code 1008) is of type UTF8String. It indicates a Session Id used to communicate with the OCS during the session. No Parent AVP. === OC-OCS-Session-Termination-Cause The OC-OCS-Session-Termination-Cause AVP (AVP code 1009) is of type Integer32. It communicates the reason that the OCS (or mediation layer) terminated the Ro session. It can be one of the following: * `NORMAL_SESSION_COMPLETION` = 0, the session terminated normally. * `ERROR_CCA` = 1, the session was terminated due to a CCA error response. * `CREDIT_LIMIT_REACHED` = 2, the session was terminated due to Credit-Limit-Reached. * `OCS_ABORT` = 3, the session was terminated due to an ASR received from the OCS. * `TCC_EXPIRED` = 4, the session was terminated due to the Sentinel Tcc timer expiring. * `CREDIT_CONTROL_FAILURE` = 5, the session was terminated due to a failure generating CCR. * `CLIENT_ABORT` = 6, the session terminated due to a client request, typically as a result of an abnormal event. No Parent AVP. === OC-Sentinel-Error The OC-Sentinel-Error AVP (AVP code 1010) is of type Enumerated. It can be one of the following: * `None` = 1 * `OcsTimeout` = 2 * `OcsCommunicationFailure` = 3 * `SentinelOverload` = 4 * `ProtocolError` = 5 * `InternalError` = 6 * `MappingError` = 7 * `OtherError` = 8 If there is a Credit Control Answer, and it has an Experimental Result Code, and that has an OpenCloud vendor ID, then this AVP is filled. No Parent AVP. === OC-Charging-Instance The OC-Charging-Instance AVP (AVP code 1011) is of type Grouped. An OC-Charging-Instance AVP represents an online charging instance used during the session. ---- OC-Charging-Instance ::= < AVP Header: 1011 > [ OC-Charging-Instance-Name ] *[ OC-Session-Counter ] ---- No Parent AVP. === OC-Charging-Instance-Name The OC-Charging-Instance-Name AVP (AVP code 1012) is of type UTF8String. It represents the name of an OC-Charging-Instance. Parent AVP: OC-Charging-Instance === OC-Session-Counter The OC-Session-Counter AVP (AVP code 1013) is of type Grouped. It represents a Session Counter used during the session. Parent AVP: OC-Charging-Instance ---- OC-Session-Counter ::= < AVP Header: 1013 > *[ OC-Session-Counter-Address ] [ OC-Cumulative-Committed-Used ] [ OC-Cumulative-Granted ] [ OC-Cumulative-Granted-Refund ] [ OC-Cumulative-Requested ] [ OC-Cumulative-Requested-Refund ] [ OC-Cumulative-Sent-Used ] [ OC-Cumulative-Suspended-Duration ] [ OC-Reported-Used ] [ OC-End-Time ] [ OC-Pending-Requested ] [ OC-Start-Time ] ---- === OC-Session-Counter-Address The OC-Session-Counter-Address AVP (AVP code 1014) is of type Grouped. It represents a Session Counter `address` field, as documented in Session counter structure. ---- OC-Session-Counter-Address ::= < AVP Header: 1014 > [ OC-Session-Counter-Address-Key ] [ OC-Session-Counter-Address-Value ] ---- Parent AVP: OC-Session-Counter === OC-Session-Counter-Address-Key The OC-Session-Counter-Address-Key AVP (AVP code 1015) is of type UTF8String. Parent AVP: OC-Session-Counter-Address === OC-Session-Counter-Address-Value The OC-Session-Counter-Address-Value AVP (AVP code 1016) is of type UTF8String. Parent AVP: OC-Session-Counter-Address === OC-Cumulative-Committed-Used The OC-Cumulative-Committed-Used AVP (AVP code 1017) is of type Integer64. It contains the value of the `cumulativeCommittedUsed` unit counter documented in Session counter structure. Parent AVP: OC-Session-Counter === OC-Cumulative-Granted The OC-Cumulative-Granted AVP (AVP code 1018) is of type Integer64. It contains the value of the `cumulativeGranted` unit counter documented in Session counter structure. Parent AVP: OC-Session-Counter === OC-Cumulative-Granted-Refund The OC-Cumulative-Granted-Refund AVP (AVP code 1019) is of type Integer64. It contains the value of the `cumulatedGrantedRefund` unit counter documented in Session counter structure. Parent AVP: OC-Session-Counter === OC-Cumulative-Requested The OC-Cumulative-Request AVP (AVP code 1020) is of type Integer64. It contains the value of the `cumulatedRequested` unit counter documented in Session counter structure. Parent AVP: OC-Session-Counter === OC-Cumulative-Requested-Refund The OC-Cumulative-Requested-Refund AVP (AVP code 1021) is of type Integer64. It contains the value of the `cumulativeRequestedRefund` unit counter documented in Session counter structure. Parent AVP: OC-Session-Counter === OC-Cumulative-Sent-Used The OC-Cumulative-Sent-Used AVP (AVP code 1022) is of type Integer64. It contains the cumulative used units sent to the OCS for the Session Counter. It contains the value of the `cumulativeSentUsed` unit counter documented in Session counter structure. Parent AVP: OC-Session-Counter === OC-Cumulative-Suspended-Duration The OC-Cumulative-Suspended-Duration AVP (AVP code 1023) is of type Integer64. It contains the value of the `cumulativeSuspendedDuration` field documented in Session counter structure. Parent AVP: OC-Session-Counter === OC-Reported-Used The OC-Reported-Used AVP (AVP code 1024) is of type Integer64. It contains the value of the `reportedUsed` field documented in Session counter structure. Parent AVP: OC-Session-Counter === OC-Pending-Requested The OC-Pending-Requested AVP (AVP code 1025) is of type Integer64. It contains the value of the `pendingRequested` unit counter documented in Session counter structure. Parent AVP: OC-Session-Counter === OC-Start-Time The OC-Start-Time AVP (AVP code 1026) is of type Time. It contains the value of the `startTime` field documented in Session counter structure. Parent AVP: OC-Session-Counter === OC-End-Time The OC-End-Time AVP (AVP code 1027) is of type Time. It contains the value of the `endTime` field documented in Session counter structure. Parent AVP: OC-Session-Counter === OC-Event-Id The OC-Event-Id AVP (AVP code 1028) is of type UTF8String. If the initial request for the Session was a `SIP SUBSCRIBE` or `SIP NOTIFY` request, this is set to the value of the `Event:` header in the initial request. If the initial request for the Session was a `SIP REFER` request, this is set to the `CSeq` of the REFER request. No parent AVP. === OC-Call-Id The OC-Call-Id AVP (AVP code 1029) is of type UTF8String. This is set to the Call-ID of the initial SIP request for the Session. No parent AVP. === OC-End-Session-Cause The OC-End-Session-Cause AVP (AVP code 1036) is of type Integer32. This is set to indicate the reason a service or feature ended the session. If the `LegManager.endSession` instruction is called with a cause value, the AVP value is set to the cause value. Otherwise, if the session state field `endSessionCause` is set, the AVP value is set to the session state value. No parent AVP. === OC-Interim-CDR-Trigger The OC-Interim-CDR-Trigger AVP (AVP code 1037) is a repeated AVP of type Grouped and appears only in interim CDRs. Each occurrence indicates a reason and a supplementary reason for writing an Interim CDR and the leg for which the reasons apply. ---- OC-Interim-CDR-Trigger ::= < AVP Header: 1037 > [ OC-Interim-CDR-Reason ] [ OC-Interim-CDR-Supplementary-Reason] [ OC-Interim-CDR-Leg ] ---- No parent AVP. === OC-Interim-CDR-Reason The OC-Interim-CDR-Reason AVP (AVP code 1038) is of type UTF8String. Parent AVP: OC-Interim-CDR-Trigger === OC-Interim-CDR-Leg The OC-Interim-CDR-Leg AVP (AVP code 1039) is of type UTF8String. Parent AVP: OC-Interim-CDR-Trigger === OC-Session-Start-Time The OC-Session-Start-Time AVP (AVP code 1040) is of type Time. It contains the time that the session’s Initial Request was processed. No parent AVP. === OC-Session-Established-Time The OC-Session-Established-Time AVP (AVP code 1041) is of type Time. It contains the time that the session was answered, that is the ACK to the 2xx-INVITE was processed. No parent AVP. === OC-Session-End-Time The OC-Session-End-Time AVP (AVP code 1042) is of type Time. It contains the time that the session was ended. No parent AVP. === OC-Interim-CDR-Supplementary-Reason The OC-Interim-CDR-Supplementary-Reason AVP (AVP code 1043) is of type UTF8String. Parent AVP: OC-Interim-CDR-Trigger === OC-Age-Of-Information The OC-Age-Of-Information AVP (AVP code 1060) is of type Integer64. The time in milliseconds of the source information. The value depends on which of the grouped AVP’s contains the OC-Age-Of-Information. Parent AVP: OC-IMSI-MCC-MNC b OC-Access-Network-MCC-MNC OC-Visited-Network-MCC-MNC === 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. Parent AVP: OC-IMSI-MCC-MNC bxref:sentinel-avp-definitions#oc-access-network-mcc-mnc[OC-Access-Network-MCC-MNC OC-Visited-Network-MCC-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. It is a grouped AVP formed by: * OC-MCC-MNC * OC-Age-Of-Information The OC-Age-Of-Information is the registration time. No parent AVP. === 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. It is a grouped AVP formed by: * OC-MCC-MNC * OC-Age-Of-Information The OC-Age-Of-Information is the registration time. No parent AVP. === 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 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. No parent AVP. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/interim-cdrs/index.adoc :here: charging-information/interim-cdrs/ :idprefix: interim-cdrs :leveloffset: 1 = Interim CDRs :indexpage: :toc: macro :toclevels: 4 :toc-title: On this page…​ The purpose, lifecycle, and features related to Interim CDRs are described on this page. toc::[ == Overview Interim CDRs are a CDR format used for recording CDRs at multiple points during the lifetime of a session. This format has several benefits over the once-per-session CDRs written by the session-based CDR features: . Improved failure characteristics. Interim CDRs are recording more frequently during a session, so any system failures will result in less records being lost. . Interop with offline charging systems. This format is designed to reflect the message content requirements for interaction with offline charging systems via the Rf interface. . More accurate. This format records changes in specific AVPs (e.g. SIP SDP AVPs) during the lifecycle of a session allowing changes in media state to be more accurately tracked. == Interim CDR content Interim CDRs are written as a collection of AVPs conforming to the definitions listed in Sentinel AVP definitions. In addition to the standard AVPs, Interim CDRs contain additional AVPs to facilitate interpretation and correlation of their content. These additions are summarized in the following table: [cols="2,3,2" options="header"]

| AVP | Description | Specification | Accounting-Record-Type | Lifecycle enum indicating when the record was written. See below table. | RFC 6733 | Accounting-Record-Number | Unique-per-session number starting at 0 indicating how many records have been written for this session. | RFC 6733 | OC-Interim-CDR-Reason | Contains the leg the Interim CDR relates to, and the reason it was written. | Sentinel AVP definitions

The `Accounting-Record-Type` AVP can have the following enumerated values: [cols="2,2" options="header"]

| Accounting-Record-Type | When written…​ | START_RECORD | When a session is established (answered). | INTERIM_RECORD | Mid-session, either in response to SDP changes or based on timer events (both configurable). | STOP_RECORD | When a session finishes. | EVENT_RECORD | When the last Interim CDR written is also the first one written, e.g. for recording of one-off SMS events.

== Interim CDR Correlation If the IMS Charging Identifier (ICID) is present during network interactions it will be included in all Interim CDRs produced for a session. When Running List CDRs, ICIDs present in a CDR file can be listed with `--list-icids`, or filtered with a specific ICID using `--filter-by-icid`. == Related features //// * README README README * Maintenance note: This entire section is overridden downstream in sentinel-volte-documentation. If you make updates here, also make them downstream! //// For configuring when Interim CDRs are written, refer to the Sip Interim Cdr feature documentation. Other features can inform the Sip Interim Cdr feature of important session state changes by writing values to the control fields defined by the `SipInterimCdrSessionState` session state interface. The features which affect the behaviour of the Sip Interim Cdr features are: [cols="2,3" options="header"]

| Feature | Behaviour | Determine Chargeable Leg Feature | Determines which leg to charge then records it to the `LegForCdrs` session state field. | SDP Monitor Feature | Detects when SDPs have changed and sets the `WriteCdrOnSDPChange` session state field. This instructs the Interim CDR feature to (if configured) write an interim CDR when SDPs have changed.

== Controlling when Interim CDRs are written The Interim CDR feature writes CDRs at specific points during a session. There are several mechanisms to control when interim CDRs are written including feature configuration and session state control fields, as described in the feature documentation. == Example call flow Below is an annotated call flow indicating where Interim CDRs are written during a typical SIP Mobile Originating session. image::generated/mo-with-ocs-interim-cdrs.png[] == Extending CDR content //// * README README README * Maintenance note: This entire section is overridden downstream in sentinel-volte-documentation. If you make updates here, also make them downstream! //// To customise the content included in Interim CDRs, refer to Customising CDRs from the SDK documentation. //// @startuml mo-with-ocs-interim-cdrs.png skinparam monochrome true hide footbox autonumber "[0]" title Originating case, Served user is A - 60 second InterimTimerPeriod participant Alice as A participant "Sentinel VoLTE" as V participant OCS as O participant Bob as B note over A The call is not a preconditions call Configuration says interim CDRs should be written for * sdp negotiations * timer driven end note A→ V : INVITE with SDP offer note over V Online charging enabled CCR Early-Media-Description-AVP shall include offer end note V → O : CCR-I V ← O : CCA-I success note over V The CCA grants say 3 mins of time so that we do not see CCR-U during this call end note V → B : INVITE V ← B : 183 with SDP answer A ← V : 183 with SDP answer V ← B : 200 OK A ← V : 200 OK A → V : ACK note over V Write a CDR Type = start Reason = call answered SDP session description AVPs and SDP media component AVPs shall reflect SDP answer Accounting-Record-Number= 0 end note V → B: ACK note over V 2.5 minute long call end note V → V: Timer expired note over V Write a CDR after 60 seconds Type = interim Reason = InterimCdrTimer fired SDP session description AVPs and SDP media component AVPs shall reflect SDP Answer Accounting-Record-Number = 1 end note V → V: Timer expired note over V Write a CDR after 60 more seconds Type = interim Reason = InterimCdrTimer fired SDP session description AVPs and SDP media component AVPs shall reflect SDP Answer Accounting-Record-Number = 2 end note A → V : BYE V → O: CCR-T V ← O: CCA-T note over V In CCR-T SDP session description AVPs and SDP media component AVPs shall reflect SDP Answer end note note over V Write CDR Type = Final Reason = "leg end" SDP session description AVPs and SDP media component AVPs shall reflect SDP Answer Accounting-Record-Number = 3 end note V → B : BYE V ← B : 200 OK A ← V : 200 OK @enduml //// :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/rf-interface-avps/index.adoc :here: charging-information/rf-interface-avps/ :idprefix: rf-interface-avps :leveloffset: 1 = Rf Interface AVPs :indexpage: The AVPs used by Sentinel SIP in the Accounting request are described. == Sentinel SIP population of Accounting Request The Accounting Request message is defined according to IETF RFC 6733, and the diameter Rf interface is defined in 3GPP TS 32.299. Sentinel products use the definition in 3GPP TS 32.299 v12.11.0 for ACR. This table indicates the top-level AVPs inside a ACR request and how the Sentinel SIP service populates them. [cols="1,2,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in ACR | Comments | Service-Context-Id | IETF RFC 4006 and refined by 3GPP TS 32.299 v12.11.0 section 7.1.12 | Yes | Yes | By default set to the value `session@opencloud.com`. For Sentinel SIP, the value is overridden to `12.32260@3gpp.org`. This includes the Release, service-context and domain. The value is overridden by the Accept SIP Feature and SIP Third Party HTTP Trigger Feature. | User-Name | IETF RFC 6733 | Yes | Yes | Not set in Sentinel Express | Session-Id | IETF RFC 6733 | Yes | Yes | The Session-Id optional part is set to the Call-ID of the initial request for the Session | Origin-Host | IETF RFC 6733 | No | Yes | Resource Adaptor entity configuration defines the value to be used for this AVP | Origin-Realm | IETF RFC 6733 | No | Yes | Resource Adaptor entity configuration defines the value to be used for this AVP | Destination-Realm | IETF RFC 6733 | No | Yes | This is set in Sentinel configuration, when selecting a CDF to use for the Session | Accounting-Record-Type | IETF RFC 6733 | Yes | Yes | | Accounting-Record-Number | IETF RFC 6733 | Yes | Yes | | Acct-Application-Id | IETF RFC 6733 | No | Yes |Set to the value `4L` | Vendor-Specific-Application-Id | IETF RFC 6733 | No | No | in volte documentation | User-Name | IETF RFC 6733 | Yes | Yes | This contains the Private Id from registration data | Destination-Host | IETF RFC 6733 | No | No | | Accounting-Sub-Session-Id | IETF RFC 6733 | No | No | | Acct-Session-Id | IETF RFC 6733 | No | No | | Acct-Multi-Session-Id | IETF RFC 6733 | No | No | | Acct-Interim-Interval | IETF RFC 6733 | Yes | Yes | | Accounting-Realtime-Required | IETF RFC 6733 | No | No | | Origin-State-Id | IETF RFC 6733 | No | No | | Event-Timestamp | IETF RFC 6733 | No | Yes | | Proxy-Info | IETF RFC 6733 | No | No | | Route-Record | IETF RFC 6733 | No | No | in volte documentation | Service-Context-Id | IETF RFC 4006 | Yes | Yes | | Service-Information | 3GPP TS 32.299 | No | Yes | Refer to Populated AVPs in the Service-Information AVP

The BNF for the ACR message according to 32.299 v12.11.0 section 6.2.2 is ---- <ACR> ::= < Diameter Header: 271, REQ, PXY > < Session-Id > { Origin-Host } { Origin-Realm } { Destination-Realm } { Accounting-Record-Type } { Accounting-Record-Number } [ Acct-Application-Id ] [ Vendor-Specific-Application-Id ] // not used in 3GPP [ User-Name ] [ Destination-Host ] [ Accounting-Sub-Session-Id ] // not used in 3GPP [ Acct-Session-Id ] // not used in 3GPP [ Acct-Multi-Session-Id ] // not used in 3GPP [ Acct-Interim-Interval ] [ Accounting-Realtime-Required ] // not used in 3GPP [ Origin-State-Id ] [ Event-Timestamp ] * [ Proxy-Info ] * [ Route-Record ] [ Service-Context-Id ] [ Service-Information ] * [ AVP ] ---- :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/ro-interface-avps/index.adoc :here: charging-information/ro-interface-avps/ :idprefix: ro-interface-avps :leveloffset: 1 = Ro Interface AVPs :indexpage: The AVPs used by Sentinel SIP in the credit control request are described. == Sentinel SIP population of Credit Control Request The Credit Control Request message is defined according to IETF RFC 4006, and some AVPs are removed and not used according to 3GPP TS 32.299. Sentinel products use the definition in 3GPP TS 32.299 v12.11.0 for CCR. This table indicates the top-level AVPs inside a CCR request and how the Sentinel SIP service populates them. [cols="1,2,1,1,3" options="header"]

| AVP Name | Specification reference | Included in CDR | Included in CCR | Comments | Service-Context-Id | IETF RFC 4006 and refined by 3GPP TS 32.299 v12.11.0 section 7.1.12 | Yes | Yes | By default set to the value `session@opencloud.com`. For Sentinel SIP, the value is overridden to `12.32260@3gpp.org`. This includes the Release, service-context and domain. The value is overridden by the Accept SIP Feature and SIP Third Party HTTP Trigger Feature. | User-Name | IETF RFC 4006 | Yes | Yes | Not set in Sentinel Express | Session-Id | IETF RFC 4006 | Yes | Yes | The Session-Id optional part is set to the Call-ID of the initial request for the Session | Origin-Host | IETF RFC 4006 | No | Yes | Resource Adaptor entity configuration defines the value to be used for this AVP | Origin-Realm | IETF RFC 4006 | No | Yes | Resource Adaptor entity configuration defines the value to be used for this AVP | Destination-Realm | IETF RFC 4006 | No | Yes | This is set in Sentinel configuration, when selecting an OCS to use for the Session | Auth-Application-Id | IETF RFC 4006 | No | Yes |Set to the value `4L` in volte documentation | Service-Context-Id | IETF RFC 4006 | Yes | Yes | | CC-Request-Type | IETF RFC 4006 | No | Yes | | CC-Request-Number | IETF RFC 4006 | No | Yes | | Destination-Host | IETF RFC 4006 | No | No | | Origin-State-Id | IETF RFC 4006 | No | No | | Event-Timestamp | IETF RFC 4006 | No | Yes | | Subscription-Id | IETF RFC 4006 | Yes | Yes | Set to the Served User, either as a SIP URI or Tel URI. This is populated via the SIP Subscriber Determination Feature. | Termination-Cause | IETF RFC 3588 | No | No | | Requested-Action | IETF RFC 4006 | No | Yes | | AoC-Request-Type | IETF RFC 4006 | No | No | | Multiple-Services-Indicator | IETF RFC 4006 | No | Yes | Set to `1` multiple services supported | Multiple-Services-Credit-Control | IETF RFC 4006 | Yes | Yes | In the case of AVP CDRs, if Ro charging is used then MSCC AVPs from the most recent CCA are written to the CDR. In the case of Ro charging the CCR’s MSCC AVP includes Populated AVPs in the Multiple-Services-Credit-Control AVP | CC-Correlation-Id | IETF RFC 4006 | No | No | | User-Equipment-Info | IETF RFC 4006 | Yes |Yes | The IMEI is used rather than the IMEISV, and the User-Equipment-Type AVP is set to IMEISV. | Proxy-Info | IETF RFC 4006 | No | No | | Route-Record | IETF RFC 4006 | No | No | | Service-Information | 3GPP TS 32.299 | No | Yes | Refer to Populated AVPs in the Service-Information AVP in volte documentation | User-Name | IETF RFC 6733 | Yes | Yes | This contains the Private Id from registration data

The BNF for the CCR message according to 32.299 v12.11.0 section 6.4.2 is ---- <CCR> ::= < Diameter Header: 272, REQ, PXY > < Session-Id > { Origin-Host } { Origin-Realm } { Destination-Realm } { Auth-Application-Id } { Service-Context-Id } { CC-Request-Type } { CC-Request-Number } [ Destination-Host ] [ User-Name ] [ CC-Sub-Session-Id ] // not used in 3GPP [ Acct-Multi-Session-Id ] // not used in 3GPP [ Origin-State-Id ] [ Event-Timestamp ] [ Subscription-Id ] [ Service-Identifier ] // not used in 3GPP [ Termination-Cause ] [ Requested-Service-Unit ] // not used in 3GPP [ Requested-Action ] *[ Used-Service-Unit ] // not used in 3GPP [ AoC-Request-Type ] [ Multiple-Services-Indicator ] *[ Multiple-Services-Credit-Control ] *[ Service-Parameter-Info ] // not used in 3GPP [ CC-Correlation-Id ] [ User-Equipment-Info ] *[ Proxy-Info ] *[ Route-Record ] [ Service-Information ] *[ AVP ] ---- :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/sizing-avp-cdrs/index.adoc :here: charging-information/sizing-avp-cdrs/ :idprefix: sizing-avp-cdrs :leveloffset: 1 = Sizing AVP CDRs :indexpage: :toc: macro :toclevels: 4 :toc-title: On this page…​ This section documents the storage requirements for AVP CDRs. toc::[] == Binary CDR log structure Each CDR log file can be broken down into the following parts: * Protobuf overhead - a small amount of type information about contained records. * A header section - a small amount of data written by the CDR RA including version, host, and timestamp information. * Zero or more AVP CDRs - these records will vary in individual size, and usually form the majority of a CDR log. * A footer - this is empty for Sentinel products. == Sizing analysis The combined size of the header, footer, and protobuf overhead is normally trivial (<1KB) compared to the size of each finished CDR log file. Individual CDR records will vary in size based on dynamic content such as hostnames, Sentinel selection key names, SDP content, and other similarly variable character data. As such, it is not possible to provide exact sizing for a given system without examining the CDR logs written while under a test load, but some approximations can be made. A basic CDR record containing the information normally written by Sentinel will be on the order of 2000-3000 bytes. With this in mind, the following sections provide rough estimates regarding how much storage would be required for specific scenarios. If Sentinel is configured to write Session CDRs (i.e. not writing Interim CDRs), then each session will write a single CDR on the order of 2000-3000 bytes. == Interim CDR Sizing This section documents the storage requirements for the AVP CDRs written by the CDR RA when Sentinel is configured to output Interim CDRs. === B2BUA CDR Sizing This scenario involves writing CDRs for a single leg of a two party call. Assuming a Start and End CDR are always written for the call, and assuming an average CDR size of 2500 bytes, each call will require a minimum of 5000 bytes. In addition, the Interim CDR feature can be configured to write CDRs periodically as a call progresses, or in response to SDP changes. Each of these events will produce additional records. Taking these additional timer driven and SDP driven records into account, a rough approximation of the CDR storage requirements can be made with a formula such as: `2500 * Sessions Per Second * (2 + (Average SDP Driven CDRs Per Session) + (Average Timer Driven Interim CDRs Per Session))` It isn’t possible to use average call length when calculating storage requirements for timer driven CDRs as the number of timer driven CDRs written per call is sensitive to actual rather than average call length. With the guideline above, we can perform approximations based on an example scenario: * No SDP changes outside of initial call setup. * 95% of calls last under the default Interim CDR timer threshold (5 minutes by default). * 5% of calls last for 59 minutes and trigger numerous timer driven Interim CDRs during that period. With a 5 minute interim CDR timer, this will mean 11 timer driven interim CDRs. * The overall system is running at 100 session per second. Using the above, we can assume that the average number of interim timer CDRs per call is `0.05 * 11`, or `0.55` per session. This results in an estimated storage requirement per second of: `2500 * 100 * (2 + 0 + 0.55) = 637500 bytes / second` or 2189MB / hour :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/working-with-cdrs/index.adoc :here: charging-information/working-with-cdrs/ :idprefix: working-with-cdrs :leveloffset: 1 = Working with CDRs :indexpage: NOTE: Sentinel writes binary CDRs using the CDR RA. Refer to CDR Resource Adaptor section of this guide for more information about Sentinel and the CDR RA. == List CDRs The Sentinel SDK contains a List CDRs tool, which can be used to print Sentinel’s binary CDRs files to a human readable format. The CDR files contain binary encoded Diameter AVPs files in addition to a header and footer. The List CDRs tool decodes the binary CDR file and all the Diameter AVPs which is contains, printing them to the console. It also supports printing the older 'legacy' CDR format which is not based on AVPs, as used by Sentinel version 2.4.x and earlier. How to use it in a nutshell: - Install the SDK normally using the SDK installer script, which will automatically install list-cdrs at `sentinel-express-sdk/tools/list-cdrs` - Run `sentinel-express-sdk/tools/list-cdrs/list-cdrs.sh CDRFILE1 [CDRFILE2]…​` This guide covers the installation options and customisation options available for List CDRs. == 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 :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/working-with-cdrs/installing-list-cdrs.adoc :here: charging-information/working-with-cdrs/ :idprefix: installing-list-cdrs :leveloffset: 1 = Installing List CDRs :sortorder: 1 == Installing the List CDRs tools using the SDK installer If you install the SDK using the `sentinel-express-sdk/build/bin/installer` script, then the installer will automatically install the list-cdrs tool at `/home/testuser/sentinel-express-sdk/list-cdrs/`. [role="small",subs="attributes,verbatim"] …​. $ ./build/bin/installer […​] Creating deployment module deploy-volte …​ done. […​] Configuration changes written. […​] Installing List CDRs tool …​ done. […​] …​. == Installing List CDRs from the SDK using Ant To install the List CDRs tool using the Ant script instead, use the `install-list-cdrs` Ant build target under the `sentinel-express-sdk/tools` directory: [role="small",subs="attributes,verbatim"] …​. $ cd /home/testuser/sentinel-express-sdk/tools $ ant install-list-cdrs Buildfile: /home/testuser/sentinel-express-sdk/tools/build.xml init-build-extensions: […​] install-list-cdrs: [echo] [echo] Retrieving List CDRs…​ [ivy:resolve] downloading https://repo.opencloud.come/artifactory/opencloud-internal-snapshots/opencloud/sentinel-core/2.9.0/sentinel-list-cdrs/2.9.0.0/sentinel-list-cdrs-package-2.9.0.0.zip …​ [ivy:resolve] …​.. (8971kB) [ivy:resolve] .. (0kB) [ivy:resolve] [SUCCESSFUL ] opencloud#sentinel-list-cdrs#sentinel-core/2.9.0;2.9.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 …​. NOTE: See Setting up Ant in the Sentinel Express SDK guide. == Installing List CDRs Standalone The above two approaches are automated ways of installing the List CDRs package (`sentinel-list-cdrs-package.zip`) into a particular location: `sentinel-express-sdk/tools/list-cdrs/`. Both the above methods place a List CDRs installer archive at `sentinel-express-sdk/tools/target/sentinel-list-cdrs-package.zip`. This `sentinel-list-cdrs-package.zip` archive can be moved to and unzipped into another location outside of the SDK and used as a standalone tool. To install the List CDRs package as a standalone tool, simply unzip the `sentinel-list-cdrs-package.zip` archive to your chosen destination directory. The mechanisms for invoking and configuration the List CDRs tools are the same as when running the tool inside the SDK. Simply substitute `/home/testuser/sentinel-express-sdk/tools/list-cdrs` with `/your/chosen/directory/list-cdrs`. == Uninstalling List CDRs If you want to uninstall the List CDRs tool, use the `uninstall-list-cdrs` Ant target under the `sentinel-express-sdk/tools` directory: [role="small",subs="attributes,verbatim"] …​. $ cd /home/testuser/sentinel-express-sdk/tools $ ant uninstall-list-cdrs Buildfile: /home/testuser/sentinel-express-sdk/tools/build.xml uninstall-list-cdrs: [echo] Uninstalling (deleting) the list-cdrs install from: /home/testuser/sentinel-express-sdk/tools/list-cdrs/ [delete] Deleting directory /home/testuser/sentinel-express-sdk/tools/list-cdrs BUILD SUCCESSFUL Total time: 0 seconds …​. Alternatively, just delete the `list-cdrs` directory: [role="small",subs="attributes,verbatim"] …​. $ rm -rf sentinel-express-sdk/tools/list-cdrs/ …​. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/working-with-cdrs/obtaining-cdrs.adoc :here: charging-information/working-with-cdrs/ :idprefix: obtaining-cdrs :leveloffset: 1 = Obtaining CDRs :sortorder: 2 == Obtaining CDR files The List CDRs tool is designed to read completed binary CDR files generated by Sentinel. Sentinel uses the CDR RA to write CDR files in a binary format. It typically writes these CDR files to the `cdr` directory inside the Rhino installation, and writes these binary CDR files using names such as `cdr_101_1468259745367.log`. The List CDRs tool can read these completed binary CDR files either in their raw binary format (e.g. `cdr_101_1468259745367.log`), or in gzip compressed format (e.g. `cdr_101_1468259745367.log.gz`). NOTE: Before a CDR file is completed, Sentinel may write a partial CDR file to disk, e.g. `cdr_101_cdr-stream_28929467492591509.tmp`. When a partially written CDR is ready to be rolled over, the CDR RA converts it to a completed binary CDR file, e.g. `cdr_101_1468259745367.log`. The List CDRs tool cannot read partially written CDR files. It can only read complete CDR files. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/working-with-cdrs/running-list-cdrs.adoc :here: charging-information/working-with-cdrs/ :idprefix: running-list-cdrs :leveloffset: 1 = Running List CDRs :sortorder: 3 To invoke the List CDRs tool, run the `list-cdrs.sh` script under the `sentinel-express-sdk/tools/list-cdrs` directory. Pass one or more file paths as arguments, each being a path to a completed binary CDR file generated by Sentinel. NOTE: If the `sentinel-express-sdk/tools` parent directory does not contain a `list-cdrs` directory, then the List CDRs tool needs to be installed. The Installing List CDRs page describes how to install the List CDRs tool. Calling the script with no arguments shows the expected syntax: [role="small",subs="attributes,verbatim"] …​. $ ./tools/list-cdrs/list-cdrs.sh Usage: list-cdrs.sh [--no-header] [--no-footer] [--no-protocol] [--ignore-error] [--output-file OUTPUTFILE] [--size-limit BYTES] [--cdr-filter FIELD=REGEX] CDRFILE [CDRFILE]…​ --no-header - Disable printing of CDR headers. --no-footer - Disable printing of CDR footers. --no-protocol - Disable printing of protocol and spec revisions in top level AVPs, e.g. "(Ro,vcb0)". --ignore-error - Continue processing CDRs files when encountering recoverable errors. --list-icids - List all unique IMS Charging Identifiers in the given CDR file(s), in order of first appearance. --filter-by-icid ICID - Print CDR message body only when CDR contains the given IMS Charging Identifier. ICID can be listed by "--list-icids" option. --output-file OUTPUTFILE - Append CDR output to OUTPUTFILE rather than to the console. --size-limit BYTES - CDR record size limit. Minimum and default value is 67108864 (64MB). Increase if encountering "Protocol message was too large" exception. --cdr-filter FIELD=REGEX - Print CDR message body only when the given FIELD matches the given regular expression. FIELD can be a field name, an AVP name, or an AVP path like "/IMS-Information/User-Session-Id". CDRFILE - A completed binary CDR file as produced by Sentinel. Both the new AVP based format (Sentinel 2.5 and later) and the older format (Sentinel 2.4 and earlier) are supported. CDR files can optionally be in gzip format, using a '.gz' suffix. Partially written CDR files (ending in ".tmp") are not supported. …​. An example invocation, showing how to print a CDR file: [role="small",subs="attributes,verbatim"] …​. $ ./tools/list-cdrs/list-cdrs.sh /path/to/cdr_101_1467865845057.log 2016-07-07T16:30:36.554+1200 Header { ra_name=CDR Generation, ra_vendor=OpenCloud, ra_version=2.3, ra_release=2.3.0.0-M1, ra_build=20160706024526, ra_revision=cdr-ra/2.3.0@d55f6a1, description=CDR session, rhino_node=101, ra_entity=cdr, hostname=mortadella } 2016-07-07T16:30:36.600+1200 AvpCdr { avps=[ Subscription-Id(Ro,vcb0)[ Subscription-Id-Type[2], Subscription-Id-Data[tel:34600000002] ], IMS-Information(Ro,vcb0)[ Role-Of-Node[ORIGINATING_ROLE(0)], Node-Functionality[AS(6)], User-Session-Id[08tE5q0fRdQRrus7F4FWqg], Session-Priority[PRIORITY_2(2)], Calling-Party-Address[tel:34600000002], Called-Party-Address[tel:34600000001], Time-Stamps[ SIP-Request-Timestamp[1467865834000], SIP-Response-Timestamp[1467865834000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 1000 1000 IN IP4 127.0.0.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0], Cause-Code[0], Early-Media-Description[ SDP-TimeStamps[ SDP-Offer-Timestamp[1467865834000], SDP-Answer-Timestamp[1467865834000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 1000 1000 IN IP4 127.0.0.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0] ] ], Service-Context-Id(Ro,vcb0)[12.32274@3gpp.org], OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:sipcall:mmtel-orig:], OC-Call-Type(Ext,Ext)[MOC(1)], OC-Service-Type(Ext,Ext)[SipCall(2)], OC-Charging-Result(Ext,Ext)[2001], OC-OCS-Session-Id(Ext,Ext)[diameterclient;diameterro-0;1529370976;0;08tE5q0fRdQRrus7F4FWqg], Session-Id(Ro,vcb0)[diameterclient;diameterro-0;1529370976;0;08tE5q0fRdQRrus7F4FWqg], OC-OCS-Session-Termination-Cause(Ext,Ext)[0], OC-Sentinel-Error(Ext,Ext)[None(1)], OC-Charging-Instance(Ext,Ext)[ OC-Charging-Instance-Name[scur_charging_instance], OC-Session-Counter[ OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Subscriber-Id], OC-Session-Counter-Address-Value[tel:34600000002] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Service-Id], OC-Session-Counter-Address-Value[1] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Cc-Unit-Type], OC-Session-Counter-Address-Value[Cc-Time] ], OC-Cumulative-Committed-Used[1000], OC-Cumulative-Granted[60000], OC-Cumulative-Granted-Refund[0], OC-Cumulative-Requested[60000], OC-Cumulative-Requested-Refund[0], OC-Cumulative-Sent-Used[1000], OC-Cumulative-Suspended-Duration[0], OC-Reported-Used[0], OC-Pending-Requested[0], OC-Start-Time[1467865834000], OC-End-Time[1467865836000] ] ], OC-Call-Id(Ext,Ext)[08tE5q0fRdQRrus7F4FWqg], MMTel-Information(Ro,vcb0)[ Supplementary-Service[ Service-Type[2] ], Subscriber-Role[ORIGINATING(0)] ] ] } 2016-07-07T16:30:38.937+1200 AvpCdr { avps=[ Subscription-Id(Ro,vcb0)[ Subscription-Id-Type[2], Subscription-Id-Data[tel:34600000002] ], IMS-Information(Ro,vcb0)[ Role-Of-Node[ORIGINATING_ROLE(0)], Node-Functionality[AS(6)], User-Session-Id[cXD7xzRmA1w4iWBzT9XMdQ], Session-Priority[PRIORITY_2(2)], Calling-Party-Address[tel:34600000002], Called-Party-Address[tel:34600000003], Time-Stamps[ SIP-Request-Timestamp[1467865837000], SIP-Response-Timestamp[1467865837000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 1000 1000 IN IP4 127.0.0.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0], Cause-Code[0], Early-Media-Description[ SDP-TimeStamps[ SDP-Offer-Timestamp[1467865837000], SDP-Answer-Timestamp[1467865837000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 1000 1000 IN IP4 127.0.0.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0] ] ], Service-Context-Id(Ro,vcb0)[12.32274@3gpp.org], OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:sipcall:mmtel-orig:], OC-Call-Type(Ext,Ext)[MOC(1)], OC-Service-Type(Ext,Ext)[SipCall(2)], OC-Charging-Result(Ext,Ext)[2001], OC-OCS-Session-Id(Ext,Ext)[diameterclient;diameterro-0;1529370976;2;cXD7xzRmA1w4iWBzT9XMdQ], Session-Id(Ro,vcb0)[diameterclient;diameterro-0;1529370976;2;cXD7xzRmA1w4iWBzT9XMdQ], OC-OCS-Session-Termination-Cause(Ext,Ext)[0], OC-Sentinel-Error(Ext,Ext)[None(1)], OC-Charging-Instance(Ext,Ext)[ OC-Charging-Instance-Name[scur_charging_instance], OC-Session-Counter[ OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Subscriber-Id], OC-Session-Counter-Address-Value[tel:34600000002] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Service-Id], OC-Session-Counter-Address-Value[1] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Cc-Unit-Type], OC-Session-Counter-Address-Value[Cc-Time] ], OC-Cumulative-Committed-Used[1000], OC-Cumulative-Granted[60000], OC-Cumulative-Granted-Refund[0], OC-Cumulative-Requested[60000], OC-Cumulative-Requested-Refund[0], OC-Cumulative-Sent-Used[1000], OC-Cumulative-Suspended-Duration[0], OC-Reported-Used[0], OC-Pending-Requested[0], OC-Start-Time[1467865837000], OC-End-Time[1467865838000] ] ], OC-Call-Id(Ext,Ext)[cXD7xzRmA1w4iWBzT9XMdQ], MMTel-Information(Ro,vcb0)[ Supplementary-Service[ Service-Type[2] ], Subscriber-Role[ORIGINATING(0)] ] ] } 2016-07-07T16:30:43.991+1200 AvpCdr { avps=[ Subscription-Id(Ro,vcb0)[ Subscription-Id-Type[2], Subscription-Id-Data[tel:34600000002] ], IMS-Information(Ro,vcb0)[ Role-Of-Node[TERMINATING_ROLE(1)], Node-Functionality[AS(6)], User-Session-Id[AhzD75RR1S7WP1_BN88Ajg], Session-Priority[PRIORITY_2(2)], Calling-Party-Address[tel:34600000002], Called-Party-Address[sip:conf-factory@localhost:5280], Requested-Party-Address[sip:conf-factory@localhost:5060], Time-Stamps[ SIP-Request-Timestamp[1467865835000], SIP-Response-Timestamp[1467865835000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 2000 1000 IN IP4 10.4.1.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0], Cause-Code[0], Early-Media-Description[ SDP-TimeStamps[ SDP-Offer-Timestamp[1467865838000], SDP-Answer-Timestamp[1467865838000] ], SDP-Session-Description[v=0], SDP-Session-Description[o=- 2000 1000 IN IP4 10.4.1.1], SDP-Session-Description[s=test-session], SDP-Session-Description[t=0 0] ] ], Service-Context-Id(Ro,vcb0)[12.32274@3gpp.org], OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:sipcall:mmtel-conf:], OC-Call-Type(Ext,Ext)[MTC(3)], OC-Service-Type(Ext,Ext)[SipCall(2)], OC-Charging-Result(Ext,Ext)[2001], OC-OCS-Session-Id(Ext,Ext)[diameterclient;diameterro-0;1529370976;1;daJvi_dNie_W_v-fzDOflg], Session-Id(Ro,vcb0)[diameterclient;diameterro-0;1529370976;1;daJvi_dNie_W_v-fzDOflg], OC-OCS-Session-Termination-Cause(Ext,Ext)[0], OC-Sentinel-Error(Ext,Ext)[None(1)], OC-Charging-Instance(Ext,Ext)[ OC-Charging-Instance-Name[scur_charging_instance], OC-Session-Counter[ OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Subscriber-Id], OC-Session-Counter-Address-Value[tel:34600000002] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Service-Id], OC-Session-Counter-Address-Value[3] ], OC-Session-Counter-Address[ OC-Session-Counter-Address-Key[Cc-Unit-Type], OC-Session-Counter-Address-Value[Cc-Time] ], OC-Cumulative-Committed-Used[8000], OC-Cumulative-Granted[63000], OC-Cumulative-Granted-Refund[0], OC-Cumulative-Requested[180000], OC-Cumulative-Requested-Refund[0], OC-Cumulative-Sent-Used[8000], OC-Cumulative-Suspended-Duration[0], OC-Reported-Used[0], OC-Pending-Requested[0], OC-Start-Time[1467865835000], OC-End-Time[1467865843000] ] ], OC-Call-Id(Ext,Ext)[daJvi_dNie_W_v-fzDOflg], MMTel-Information(Ro,vcb0)[ Supplementary-Service[ Service-Type[10], Associated-Party-Address[tel:34600000002], Service-Id[mmtelconf101MpAdqRMBdip0aIpqObY1hQ], Change-Time[1467865843000] ], Subscriber-Role[TERMINATING(1)] ] ] } 2016-07-07T16:30:45.057+1200 Footer {} …​. == Logging output The List CDRs tool writes its main output to the console, but it can be configured to write some extra debugging to a log file. It uses the log4j logging library, and its log4j configuration file is located at `sentinel-express-sdk/list-cdrs/log4j.properties`. By default, it will log to `sentinel-express-sdk/tools/list-cdrs/logs/list-cdrs.log`. It logs very little when using the default configuration — the log file will typically be empty unless configured for debug logging. To enable debug logging, change the log level on the last line of the `log4j.properties` file to `DEBUG`: [role="small",subs="attributes,verbatim"] …​. log4j.logger.sentinel.cdr=DEBUG …​. :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/working-with-cdrs/extension-avps.adoc :here: charging-information/working-with-cdrs/ :idprefix: extension-avps :leveloffset: 1 = Extension AVPs :sortorder: 4 == Built-in AVPs and extension AVPs The binary CDR format contains Diameter AVPs encoded in binary form, and the List CDRs tool decodes these binary AVPs before printing them in a human readable format. The tool has built-in knowledge of AVPs which are defined in Diameter protocols such as Rf and Ro. It can also be customized with knowledge of user defined extension AVPs, by providing definitions of those AVPs in YAML files. The List CDRs tool looks in the `list-cdrs/extension-avps` directory for YAML based files which define these extension AVPs. A default installation of the List CDRs tool contains a `DiameterExtension-AVP.yaml` file inside this directory, which defines OpenCloud’s extension AVPs. This means that by default, the List CDRs tool recognizes all the AVPs in the CDR files produced by Sentinel. == Known AVPs vs Undefined AVPs When encountering an AVP which it does not recognize, the List CDRs tool treats it as an Undefined AVP. Because the tool can’t see which type of AVP it is (e.g. `UTF8String` or `Integer32`), it prints the raw binary content of the AVP in hexadecimal format. This is how the List CDRs tool will print an extension AVP that it doesn’t recognize: [role="small",subs="attributes,verbatim"] …​. Undefined-AVP[code=1029,vendor=19808,hex=64 61 4a 76 69 5f 64 4e 69 65 5f 57 5f 76 2d 66 7a 44 4f 66 6c 67,ascii=daJvi_dNie_W_v-fzDOflg], …​. This is how the List CDRs tool prints that same extension AVP, when that AVP is configured as an extension AVP (see below): [role="small",subs="attributes,verbatim"] …​. OC-Call-Id[daJvi_dNie_W_v-fzDOflg], …​. == Built-in extension AVPs This is an excerpt from the default extension AVP configuration file at `list-cdrs/extension-avps/DiameterExtension-AVP.yaml`, showing the first two extension AVPs: [role="small",subs="attributes,verbatim"] …​. $ cat extension-avps/DiameterExtension-AVP.yaml !profiles DiameterExtension-AVP: id: name: 'Diameter Extension AVP' vendor: 'OpenCloud' version: '2.7' imports: null profiles: ? '' : AvpCode: 0 AvpName: null AvpType: null MandatoryRule: 1 ProtectedRule: 1 VendorId: 0 OC-Sentinel-Selection-Key: AvpCode: 1001 AvpName: OC-Sentinel-Selection-Key AvpType: UTF8String MandatoryRule: 1 ProtectedRule: 1 VendorId: 19808 OC-Play-Announcement-Id: AvpCode: 1002 AvpName: OC-Play-Announcement-Id AvpType: Integer32 MandatoryRule: 1 ProtectedRule: 1 VendorId: 19808 […​] …​. == Customisation of extension AVPs To configure your own custom AVP, add a new file with the same opening structure as `extension-avps/DiameterExtension-AVP.yaml`, but with your own extensions. NOTE: Be sure to use your own Vendor ID, which we’ll assume to be `19404` below for the sake of example. An example configuration file: [role="small",subs="attributes,verbatim"] …​. $ cat extension-avps/ACME-DiameterExtension-AVP.yaml !profiles DiameterExtension-AVP: id: name: 'Diameter Extension AVP' vendor: 'OpenCloud' version: '2.7' imports: null profiles: ? '' : AvpCode: 0 AvpName: null AvpType: null MandatoryRule: 1 ProtectedRule: 1 VendorId: 0 ACME-My-First-Custom-Code: AvpCode: 1000 AvpName: ACME-My-First-Custom-Code AvpType: UTF8String MandatoryRule: 1 ProtectedRule: 1 VendorId: 19404 ACME-My-Second-Custom-Code: AvpCode: 1000 AvpName: ACME-My-Second-Custom-Code AvpType: UTF8String MandatoryRule: 1 ProtectedRule: 1 VendorId: 19404 […​] …​. After you have created such a file you will also have to add the AVP names to the `Charging` profile in the `DiameterExtensions` profile table, which lives in the file `extension-avps/DiameterExtensions.yaml`. The profile consists of an array that lists all of the desired AVPs in the format `<profile table name>/<profile name>`. So for the two AVPs from the example above you would have to add these two lines to the `Charging` profile: …​. - DiameterExtension-AVP/ACME-My-First-Custom-Code - DiameterExtension-AVP/ACME-My-Second-Custom-Code …​. Note that the profile to use for the supported extension AVP list is configured with the `ExtensionAvpSet` property of the Diameter RA. See Configuring Extension AVPs for the full documentation of these profile tables. The required fields for each AVP: AvpCode:: The code of the AVP. If using your own vendor code, then this AVP code is within your own namespace. AvpName:: The name of the AVP. AvpType:: The type of the AVP. See the available AVP types below. MandatoryRule:: The "M" bit or Mandatory bit. Indicates whether support of the AVP is mandatory on the receiving end. Valid values are: * 0 - MUST * 1 - MAY * 2 - MUSTNOT ProtectedRule:: The "P" bit, indicating the need for encryption. Valid values are: * 0 - MUST * 1 - MAY * 2 - MUSTNOT VendorId:: The Vendor ID of the company which has defined this AVP. The available AVP types:: * `OctetString` * `Integer32` * `Integer64` * `Unsigned32` * `Unsigned64` * `Float32` * `Float64` * `Grouped` * `Address` * `Time` * `UTF8String` * `DiameterIdentity` * `DiameterURI` * `Enumerated` * `IPFilterRule` * `QoSFilterRule` * `Undefined` :leveloffset!: :ocdoc_current_file: /mnt/ephemeral0/workspace/product/sentinel/sentinel-documentation/release-2.9.0/Auto/sentinel-documentation/target/generated/sentinel-administration-guide/charging-information/working-with-cdrs/installing-protobuf.adoc :here: charging-information/working-with-cdrs/ :idprefix: installing-protobuf :leveloffset: 1 = Installing Protobuf :sortorder: 5 Protobuf 2.3.0 is required to build and extend CDR modules included with the SDK. The SDK infrastructure makes this version available for download from an Ant target. NOTE: Protobuf 2.3.0 can be downloaded as a standalone package *https://s3-ap-southeast-2.amazonaws.com/ocaws-downloads/third-party/google/protobuf/protobuf-2.3.0.tar.gz[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: [role="small",subs="attributes,verbatim"] …​. $ 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 …​. NOTE: 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: [role="small",subs="attributes,verbatim"] …​. $ 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: [role="small",subs="attributes,verbatim"] …​. $ rm -rf sentinel-express-sdk/tools/protobuf-2.3.0/ …​. :leveloffset!:

1. Noldus, Rogier (2006), "CAMEL: Intelligent Networks for the GSM, GPRS and UMTS Network", John Wiley & Sons, Ltd
2. Noldus, Rogier (2006), "CAMEL: Intelligent Networks for the GSM, GPRS and UMTS Network", John Wiley & Sons, Ltd