About the IP Short Message Gateway

The IP Short Message Gateway (IPSMGW) implements transport layer interworking for SMS over IP. It is based on 3GPP TS 24.341, and implements suitable SMS interworking as part of GSMA IR.92 version 9.0

Topics

This document includes the following topics:

Topic Explains…​

Getting Started

how to install the product

Features

the behaviour and configuration of each feature

Mappers

the behaviour of each mapper

TCAP Application Context Negotiation

how different phases of MAP are supported

Charging Information

the format and content of CDR files, and the information present in Diameter Ro

SIP Transports and Routing

how SIP requests are routed to and from the IP-SM-GW

Resource Adaptors

details of Resource Adaptors used by the IP-SM-GW

Cassandra Storage

how data is stored in the Cassandra Database

IFCs

details of the IFCs that are used for IP-SM-GW routing

License Requirements

license requirements for running IP-SM-GW

Getting Started

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

In this section…​

Preparing to Install Sentinel IPSMGW

Before you install Sentinel IPSMGW, 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 IPSMGW, or

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

In both cases you need to get a license.

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

A Cassandra database is required for an IPSMGW installation.

An OCSS7 Stack is required for an IPSMGW installation.

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

Download the Sentinel IPSMGW SDK package

To get the latest Sentinel IPSMGW SDK package go to https://repo.opencloud.com/artifactory/opencloud-sentinel-ipsmgw-2.9.0/opencloud/sentinel-ipsmgw/trunk/ipsmgw-sdk/ Choose the version with the highest release number.

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

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

Get required software

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

Software Download Link Documentation Link

Java JDK 8, update 172 or later

http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.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.2.0 or later - optional - to be used when installing and configuring Rhino manually

Rhino 2.6.2 SDK from Artifactory

Rhino Documentation

Rhino Element Manager 2.6.2.0 or later

REM Download Page

REM Documentation

Sentinel IP-SM-GW SDK including out of the box installer

Sentinel IPSMGW SDK, from Artifactory

Sentinel IPSMGW documentation space

Sentinel IP-SM-GW plugin for Rhino Element Manager

Sentinel IPSMGW EM Extension, from Artifactory

Installing the IPSMGW Element Manager Module

Cassandra Database, version 3.1.11 or later version from the 3.1.x series.

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

http://cassandra.apache.org/doc/latest/getting_started/index.html

OCSS7, version 2.2.0.0 or later

OCSS7 Package from Artifactory

https://docs.opencloud.com/ocdoc/books/ocss7/2.2.0/ocss7-home/index.html

Install and configure Rhino and the JVM

Optionally you can install and configure Rhino and the JVM for use with Sentinel IPSMGW. 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 IPSMGW 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

3

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

SLEE successfully started on node(s) [101]

4

Stop Rhino by executing in the RHINO_HOME directory:

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

Configure Rhino and the JVM

If you want to install Sentinel IPSMGW in 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 IPSMGW install, the default Rhino 2.6.2 management database size is insufficient and should be increased to at least 300MB. To do this, edit RHINO_HOME/config/rhino-config.xml on all nodes, increasing the <committed-size> in the following section:

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

JVM

You’ll also need to configure the JVM:

In RHINO_HOME/config/config_variables:

  • 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 IPSMGW is 1/4th of the total heap size (for example, 512m when the HEAP_SIZE is 2048m).

In RHINO_HOME/config/jvm_args:

  • The MaxPermGen size should be increased from its default, to at least 384MB. To do this in Rhino 2.6.2, modify the flags -XX:MaxPermSize= and -XX:PermSize=.

  • These JVM settings are recommended for IPSMGW:

    • -XX:MaxTenuringThreshold=2

    • -XX:SurvivorRatio=16

    • -XX:CMSInitiatingOccupancyFraction=60

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 xmltag <security-permission-spec> and add the following entry, replacing <IP ADDRESS> with your installer’s IP address:

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

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

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

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

This applies the Rhino and JVM configuration.

Get a license

Warning To install Sentinel IPSMGW you need a license to run SIS, CGIN, and Sentinel IPSMGW from OpenCloud. In order to obtain a license file, please contact OpenCloud. A full overview of license requirements can be found of this page: License Requirements.

If you allow the installer to install both Rhino SDK and Sentinel IPSMGW 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 IPSMGW.

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

Cassandra Database

Install and configure a Cassandra Storage with the opencloud_thirdparty_reg and opencloud_ipsmgw_routing_info keyspaces.

OCSS7 Stack

Install and configure an OCSS7 stack. Refer to OCSS7 Quick Start.

OpenCloud product dependencies

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

Product Series

Rhino

2.6.2.x

REM

2.6.2.x

SIP

2.6.0.x

CGIN

2.0.0.x

OCSS7

2.2.0.x

SIS

2.6.2.x

Diameter

3.1.2.x

CDR-RA

2.3.0.x

HTTP-RA

2.5.0.x

DB-Query-RA

1.4.0.x

FSM Tool

1.2.0.x

CQL RA

1.2.0.2

Installing Sentinel IPSMGW Services

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

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

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

The installer prepares configuration for a single node Sentinel IPSMGW system, with a single peer for various other network elements such as:

  • Interrogating Call Session Control Function (I-CSCF)

  • Home Location Register (HLR)

  • Cassandra storage for Third Party Registration data

For more advanced configurations, such as clustering or multiple signalling peers, familiarity with the Rhino platform, SIS and Sentinel products is recommended.

To install Sentinel IPSMGW services in interactive mode:

For further information on installation read:

1. Unzip ipsmgw-sdk.zip

To unzip ipsmgw-sdk.zip:

1

Copy the downloaded install zip file to a machine where Rhino and Sentinel IPSMGW will run.

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

2

Unzip.

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

2. Run the installer

Tip The installer prompts you for various configuration settings, such as the SIP URI for the MRF. You can review and change settings prior to installation so don’t worry if you got something wrong first time.

The install program is split into several "phases".

These are:

  • initialisation of the environment

  • question and answer (in interactive mode)

  • review settings (in interactive mode)

  • execution of installation

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

To run the installer:

1

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

testuser@machine$ cd ~/sentinel-ipsmgw/ipsmgw-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 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.

If the user presses the y key then the SDK will be taken offline.

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. Additional letters and numbers will be appended to it to identify specific releases, snapshots and milestones when an artifact is actually published.

5

Rhino details

The installer then prompts for details of the Rhino installation used for this installation of IPSMGW.

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] >
Note The tcapsim-gt-table.txt file is used for simulation tools. When integrating into a network the default contents of the file should be kept, and a real SS7 stack used (e.g. OpenCloud SS7).

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, it will prompt for the path to the Rhino client directory and check if you are using a Rhino SDK or a production cluster.

Enter the path to your Rhino client directory > /home/testuser/rhino/client

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 the basic SDK configuration 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

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

Creation of a deployment module

The installer will now create a suitable deployment module. This may take several minutes.

8

General configuration

Details of the IPSMGW environment - hosts, ports, addresses etc

The SCCP address of the HLR. This value is used as a template address if 'Use MSISDN as HLR Address' is configured. In this case the configured digits are replaced by the subscriber MSISDN in the outbound HLR address.
Examples: type=C7,ri=pcssn,pc=5,ssn=6 or type=C7,ri=gt,digits=0,ssn=6,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0
HLR address [type=C7,ri=pcssn,pc=5,ssn=6] >

Within the MAP Proxy and ATM Registration features, controls whether to address the outbound HLR leg
using a GT address formed from the subscriber MSISDN, using the configured address as a template.
Use MSISDN as HLR Address y/[N] >

A Template SCCP address used for routing to SMSC, address will be modified based on the received MSC address.
Example: type=C7,ri=gt,digits=0,ssn=8,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0
Template SMSC address [type=C7,ri=gt,digits=0,ssn=8,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0] >

The originating SCCP address of the Sentinel IP-SM-GW.
Example: type=C7,ri=pcssn,pc=5,ssn=147
Originating Sentinel address [type=C7,ri=pcssn,pc=5,ssn=147] >

The international SCCP address of the Sentinel IP-SM-GW.
Example: address=653333333,nature=INTERNATIONAL,numberingPlan=ISDN
IP-SM-GW Sentinel address [address=653333333,nature=INTERNATIONAL,numberingPlan=ISDN] >

The TCAP invoke timeout (in milliseconds).
Invoke timeout [5000] >

The domain used to compose SIP URIs from the MSISDN.
Terminating domain [opencloud.com] >

The Address of the Interrogating Call Session Control Function. The hostname part should either be a resolvable name or the IP address of the I-CSCF.
Example: sip:127.0.0.1:5052;lr;transport=tcp
I-CSCF URI [sip:127.0.0.1:5052;lr;transport=tcp] >

The SIP transport used to determine the local SIP URI, which is used as the address of IPSMGW
Valid values are: 'udp' or 'tcp'.
SIP transport [udp] >

The delivery order to use for MT deliveries
Valid values are: CS_THEN_PS or PS_THEN_CS or CS_ONLY or PS_ONLY
Delivery Order [PS_THEN_CS] >

Charging can be enabled separately for MT deliveries over PS and CS, and for MO.
Do you want to enable charging over PS for MT deliveries? y/[N] >
Do you want to enable charging over CS for MT deliveries? y/[N] >
Do you want to enable charging for MO deliveries? y/[N] >
Note Template SMSC Address added in 2.7.0.3

9

Sentinel Registrar

Details of the Cassandra database used for Third Party Registration data

Please enter a comma separated list of Cassandra contact points in the form "host1,host2"
Cassandra Contact Points [localhost] >

Please enter the port Cassandra is listening on
Cassandra Port [9042] >

10

IPSMGW Cassandra

IPSMGW uses Cassandra to save routing information that can be shared across nodes.

Please enter a comma separated list of Cassandra contact points in the form "host1,host2"
Cassandra Contact Points [localhost] >

Please enter the port Cassandra is listening on
Cassandra Port [9042] >

11

Sh Cache Microservice RA

Configuration that is used by the Sh Cache Microservice RA.

The URL for the Sh Cache Microservice.
Server URL [http://localhost:8088] >

The URL for the Sh Cache Microservice. This is what Sh Cache Microservice requests are sent to.

Whether to use a proxy server.
Proxy Enabled y/[N] >

If yes, the installer will next ask to configure the proxy server.

The hostname of the proxy server.
Proxy Host [localhost] >

Hostname of the proxy server.

The port of the proxy server.
Proxy Port [3128] >

Port of the proxy server.

The URL that notifications from Sh Cache Microservice will be sent to.
This hostname must be able to be resolved by ShCM hosts.
Notification URL [http://localhost:8089] >

The notification URL.

The local port the RA will listen on for notification requests.
This is allowed to differ from the port in 'http.notificationURL',
as the local port may not be visible to other nodes depending on the network topology.
Notification Port [8089] >

The port to listen on for notification requests.

Subscription expiry time in seconds.
Subscription Expiry Time [3600] >

Expiry time for subscriptions to UE Reachability For IP.

12

Correlation RA

Configuration that is used by the Correlation RA to generate MT Correlation IDs(fake IMSIs).

The name of the Correlation ID Pool
Pool name [OpenCloud] >
Mobile Country Code (MCC) [001] >
Mobile Network Code (MNC) [01] >

13

SIP SIS RA Listen Address

This specifies the host that you want to receive SIP traffic on.

This is the hostname or IP address that you want to receive SIP traffic on.
SIP SIS RA Host [localhost] >

If installing on a production Rhino with multiple nodes running on the same host, the installer will report that the SIP RA OffsetPort functionality is enabled, with the port offset set to the lowest node ID. The port will default to 5060, modified as described in the configuration. As an example, if nodes 101 and 102 are running on host1, and node 201 is running on host2, the ports used will be 5060-101+101=5060 for node 101, 5060-101+102=5061 for node 102, and 5060-101+201=5160 for node 201.

Port offset for SIP SIS RA listen addresses
===========================================

  Offsetting SIP SIS RA listen ports by nodeId - 101

Otherwise, the port offset functionality will not be enabled and port 5060 will be used by default.

Port offset for SIP SIS RA listen addresses
===========================================

SIP SIS RA 'port offset' functionality not required, as there are no hosts with multiple nodes running

14

OCSS7 Server list for CGIN MAP RA

This specifies the OCSS7 server list for the cginmapra entity related to the sccp address. It has to contain the port.

This is a comma separated list of hostname or IP address and the port of OCSS7 SGC nodes to connect to. eg localhost:13021,localhost:13022
OCSS7 SGC node Host and Port list [localhost:13021] >

15

Diameter Ro and CCA Questions - if any charging options chosen at step 6

This value is placed into the Origin-Host AVP.
Host [diameterclient] >

The Diameter hostname for Sentinel IP-SM-GW. It is used in the Origin-Host AVP of outgoing diameter messages.

This installer allows setting up a simple configuration with a single peer for the OCS. If you need a configuration with multiple peers, you can either do so after the installation finishes by following the Diameter documentation, or editing the following file now:
[path-to-config-file]/DiameterConfig.xml
Do you want to set up a simple configuration? [Y]/n >

If yes, the installer will provide a series of prompts for setting up a basic diameter configuration (where there is a single OCS server); if no, you will need to manually configure diameter peers for the charging system.

Peer URI [aaa://diameterserver:3868;transport=tcp] >

URI of the online charging server.

Diameter peer address [diameterserver] >

Diameter address of the online charging server.

Realm name [example.com] >

Diameter Realm for the online charging system.

16

PS Delivery configuration

Details for the PS Delivery feature

The Timer to decide whether PS Delivery has failed (in milliseconds).
Delivery Failure Timer [5000] >

The RP-Error codes that will stop fallback if PS_THEN_CS is used.
The special value of '-1' will mean no error codes are used.
Example: 21,22
Fallback Avoidance Codes [22] >

17

PS Delivery Per Node URI

This specifies the URI for each node that PSDelivery will set as the From: address in outgoing MESSAGE requests.

If installing on a cluster, this question will be repeated for each node specified at the start of the installation process.

The SIP Local URI of Rhino node 101.
Example: sip:127.0.0.1:5060
Node 101 SIP Local URI [sip:127.0.0.1:5060] >

18

CS Delivery configuration

Error handling behaviour for the CS Delivery feature

The Delivery Error codes that will stop fallback if CS_THEN_PS is used.
The special value of '-1' will mean no error codes are used.
Example: 0,1
Fallback Avoidance Codes [0] >

19

IPSMGW SCCP Whitelist GT Entries

This defines a whitelist of incoming SCCP origin addresses that will not be rejected by the IPSMGW SCCP Whitelist feature when triggered by an OpenRequest.

Comma separated list of SCCP Whitelist GT Prefixes.
The special value of '-' will mean no whitelist is provisioned and all SCCPs will be accepted.
Example: 64123,64124
SCCP Whitelist GT Prefix List [-] >

20

IPSMGW CDR RA Configuration

The configuration properties of the CDR resource adaptor. See Configuration for more details.

Approximate maximum size in bytes before a new CDR file is started.
After a CDR is written, the total file size is compared to MaxSize.
If the current file size is larger, it is completed.
If MaxSize is 0, no size-based rollover is done.
MaxSize [100000000] >

Number of CDRs to be written to a CDR file before a new file is started.
The line count does not include the header and footer lines, if enabled.
If MaxLines is 0, no line-based rollover is done.
MaxLines [0] >

Number of milliseconds of operation before time-based file rollover.
If a CDR file is used for more than MaxInterval seconds without being rolled over due to line- or size-based limits, it is completed anyway.
If CreateEmptyFiles is True, at least one CDR file is created every MaxInterval seconds, even if no CDRs are written.
MaxInterval [600000] >
Note The CDR resource adaptor executes a script at $RHINO_HOME/archive-cdr-log.sh at CDR rollover, as described in the CDR resource adaptor documentation. This script should be provided by the user, and should be set as executable by Rhino.

21

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


General configuration
=====================

  HLR Address: type=C7,ri=pcssn,pc=5,ssn=6
  Use MSISDN as HLR Address: false
  Template SMSC Address: type=C7,ri=gt,digits=0,ssn=8,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0
  Sentinel Originating Address: type=C7,ri=pcssn,pc=5,ssn=147
  Sentinel IP-SM-GW Address: address=653333333,nature=INTERNATIONAL,numberingPlan=ISDN
  HLR Invoke Timeout (ms): 5000
  Terminating domain: opencloud.com
  I-CSCF URI: sip:127.0.0.1:5052;lr;transport=tcp
  SIP transport: udp


Sentinel Registrar
==================

  Cassandra Contact Points: localhost
  Cassandra Port: 9042

Sh Cache Microservice RA
=================

  Server URL: http://localhost:8088
  Proxy Enabled: false
  Notification URL: http://localhost:8089
  Notification Port: 8089
  Subscription Expiry Time: 3600

MT Correlation ID
=================

  Profile name: OpenCloud
  MCC: 001
  MNC: 01


Port offset for SIP SIS RA listen addresses
===========================================

Not offsetting SIP SIS RA listen port


Listen Address for SIP SIS RA
=============================

  SIP SIS RA Host: localhost


OCSS7 Server list for CGIN MAP RA
==============================

  OCSS7 SGC node Host and Port list: localhost:13021


Diameter (Ro & CCA)
==============================

  Host: diameterclient
  Peer URI: aaa://diameterserver:3868;transport=tcp
  Peer address: diameterserver
  Realm name: example.com


PS Delivery configuration
=========================

  PS Delivery Fallback Timer (ms): 5000
  RP-Error Fallback Avoidance Codes: [22]

PS Delivery Per Node URIs
=========================

Node 101 SIP Local URI: sip:127.0.0.1:5060

Accept these values? [Y]/n >

CS Delivery configuration
=========================

  Delivery Fallback Avoidance Codes: [0]


IPSMGW SCCP Whitelist GT Entries
================================

64125,64124

IPSMGW CDR RA configuration
===========================

  MaxSize: 100000000
  MaxLines: 0
  MaxInterval (ms): 600000
  ArchiveCommand:

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.

22

Execution phase

Now that the installer has gathered all necessary information it provides the user with the option to install the IPSMGW TAS now.

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.

If 'Y' is selected the installer proceeds to install Sentinel IPSMGW into Rhino (or Rhino SDK).

Publishing deployment module ... 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.
Running post-installation tasks ...done.
Installation completed successfully in 11 minutes and 27 seconds. Rhino has been left running to finish applying configuration changes.

The installation has now completed successfully.

Important A properties file called install.properties is automatically created in the ipsmgw-sdk directory when the interactive installer is run. It stores all the data entered during the install. You can 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 is passed to the installer program

testuser@machine$ cd ~/sentinel-ipsmgw/ipsmgw-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 ipsmgw-sdk/cgin/cgin-connectivity-full-CGIN_VERSION directory. The SIS is extracted into the ipsmgw-sdk/sis/SIS_VERSION directory. Here CGIN_VERSION and SIS_VERSION are the release versions for each product respectively (e.g. 1.5.4.1 and 2.5.4.1)

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

Background information

The installer sits on top of the Sentinel IPSMGW SDK infrastructure

The installer works by creation of a 'deployment module' for Sentinel IPSMGW. The module is named "deploy-ipsmgw" and is located in the root of the Sentinel IPSMGW SDK directory.

A deployment module can be created through the use of the sdkadm create-deployment-module command. The values that the user enters (or passes in when using non-interactive mode) are written into the various configuration files in this deployment module.

During an install, the deployment module is first published, then 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 IPSMGW 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 modification of the deployment module, and publishing it, 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 ipsmgw-sdk/build/target/log directory. This output is more verbose than the user sees when running the installer.

Each time an install is done, a file called install.log is created in this directory. If there is a previous install.log file, that it is moved to install_date.log. The value of "date" is the time of the last write timestamp in the file. i.e. running the installer three times results in three installer log files.

Post-Installation Instructions

Configure the MCC and MNC in SipSentinelConfiguration

There are two required configuration values in SIP Sentinel Configuration which must be configured by hand after installation.

The MCC and MNCs fields are used by Generate MT Correlation Id when a real IMSI could not be retrieved from the HLR.

These can be set through either REM or the rhino-console.

Create init.d scripts

There are two init.d scripts for Ubuntu Linux which make starting and stopping Rhino and REM easier (linked below):

  • rhino — for Rhino

  • rem — for REM running on Apache Tomcat

Note: These are illustrative and useful for Proof of concept rather than production environments.

To set these up:

1

Copy the script to the host server’s /etc/init.d/ folder:

sudo cp rhino /etc/init.d

2

Make the script executable:

sudo chmod +x /etc/init.d/rhino

3

Refresh, with the update-rc.d command:

sudo update-rc.d rhino defaults 99

Restart Rhino

Finally, restart Rhino by executing the following commands in a terminal, from the Rhino install directory.

./stop-rhino.sh --nice
./start-rhino.sh
Tip If you chose to set up the Rhino init.d script, you can use these commands to stop and start it.

Init.d Sample Scripts for IPSMGW

Note These sample scripts are illustrative init.d scripts for Rhino and REM

For production installations use production Rhino’s own init.d scripts rather than these.

Sample Rhino script

#!/bin/bash
#
# Manage the Rhino SLEE.
# Put this file in /etc/init.d and symlink that in /etc/rc?.d

RHINO_HOME=/home/ubuntu/ipsmgw-sdk/rhino-sdk/RhinoSDK
RHINO_USER=ubuntu

case "$1" in
start)
	# This command will fail nicely if that file is not there, so
	#  checking for that file's existence is not necessary.
        echo "Starting the Rhino SLEE"
	sudo su - ${RHINO_USER} -c ${RHINO_HOME}/start-rhino.sh > /dev/null 2>&1 &
        # logs will be in ${RHINO_HOME}/work/log
	;;

stop)
        echo "Stopping the Rhino SLEE"
        [ -d ${RHINO_HOME} ] && [ -x ${RHINO_HOME}/stop-rhino.sh ] \
	    && ${RHINO_HOME}/stop-rhino.sh --nice
	;;

*)
	echo "Usage: $0 { start | stop }"
	exit 1
	;;
esac
exit 0

Sample REM script

#!/bin/sh
#
# Rhino Element Manager start/stop script.
#
#

# Location of the Rhino Element Manager
REM_HOME=/home/ubuntu/ipsmgw-sdk/rhino-sdk/RhinoSDK/apache-tomcat-*
RHINO_USER=ubuntu

usage()
{
    echo "Usage: $0 {start|stop}"
    exit 1
}

#
# Main
#

# Parameter check

[ $# -gt 0 ] || usage

case "$1" in
  start)
        # Start REM
        sudo su - "$RHINO_USER" -c "$REM_HOME/bin/catalina.sh start"
        echo "REM Starting"

        ;;

  stop)
        # Stop REM
        sudo su - "$RHINO_USER" -c "$REM_HOME/bin/catalina.sh stop"
        echo "REM Stopping"
        ;;

  *)
        usage
        exit 2
        ;;

esac

exit 0

Installing the IPSMGW Element Manager Module

The IPSMGW Element Manager module is distributed as a Rhino Element Manager (REM) plugin.

Note The IPSMGW Element Manager module should be installed if the REM instance is only used to provision Sentinel-IPSMGW. If REM will be used to provision both Sentinel-VoLTE and Sentinel-IPSMGW installations then only the Sentinel VoLTE provisioning module should be installed. The Sentinel VoLTE provisioning module is capable of provisioning both Sentinel-IPSMGW and Sentinel-VoLTE installations. See Installing the Sentinel VoLTE Provisioning Module.

It requires a standalone distribution of REM 1.5.0.4 or later. REM can be installed with Jetty or Apache Tomcat. For IPSMGW, the Apache Tomcat method is required.

You’ll need these files to install the IPSMGW Element Manager module:

  • apache-tomcat-<version>.zip

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

  • ipsmgw-element-manager-<version>.em.jar

Below are the procedures to:

Set up Tomcat

To set up Apache Tomcat for the IPSMGW Element Manager 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 IPSMGW Element Manager Module:

1

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

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

Customize plugin logging

1

Unzip log4j.properties from rem.war:

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

2

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

log4j.rootLogger=INFO, FILE, CONSOLE

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

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

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

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

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

3

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

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

4

Remove temporary files:

cd ..
rm -rf rem-tmp

Import Rhino trust certificate

This can also be done using the REM web UI.

1

Import a Rhino Trust Certificate into REM:

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

Security considerations

Below are recommendations for securely running the IPSMGW Element Manager Module.

Use https

Be aware that the IPSMGW Element Manager 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.

Virtualized Deployment Requirements

Sentinel IPSMGW is supported in a virtualized environment, details presented here provide a guide to the scope of that support and how Sentinel IPSMGW should be setup in that environment.

VMWare Supported

VMWare vSphere ESXi 5.1 and 6 is supported and certified. vCenter is not a mandatory requirement.

Operating System Support

Please refer to the Platforms section of the Rhino Compatibility Guide for supported operating systems.

Hyper-threading support

Hyper-threading is supported and used to maximize performance throughput.

Uncontended RAM Required

Sentinel IPSMGW does make use of Uncontended RAM.

Uncontended disk I/O Required

Sentinel IPSMGW does not require Uncontended disk I/O.

Dedicated Storage Array Required

Sentinel IPSMGW does not require dedicated storage. CDR files and Rhino logs should be partitioned separately and managed to avoid failure or data loss due to space utilization.

CPU Contention Supported

CPU Contention is supported, however %ready numbers should be kept below 5% to avoid significant impact on overall application performance. It is strongly recommended that VMs are bound to physical CPU sockets to ensure predictable latency.

Fault Tolerance

A rhino cluster provides support for both high availability and fault tolerance internally. Sentinel IPSMGW does not make use of the Rhino replication but does use the high availability systems. The cluster as a whole can tolerate failure of individual nodes with no support from the virtual machine. Live replication of virtual machines (FT Model) will interfere with Rhino’s internal clustering mechanisms.

VMWare Fault Tolerance

Sentinel IPSMGW does not support VMWare Fault Tolerance.

VMWare vSphere High Availability

Sentinel IPSMGW provides is own HA clustering based upon the Rhino SLEE Architecture.

VMWare vSphere App High Availability

Sentinel IPSMGW does not support App High Availability.

VMWare vMotion

Sentinel IPSMGW does not support VMWare vMotion.

VMWare vSphere Data Protection

Sentinel IPSMGW supports Data Protection with the exception of RAM.

Stretched Clustering

Sentinel IPSMGW supports Stretched Clustering.

VMWare VM Suspend/Resume

Sentinel IPSMGW does not support Suspend/Resume.

VMWare VM Snapshots

Sentinel IPSMGW does not support Snapshots.

VMWare VM Clone

Sentinel IPSMGW does not support Cloning.

VMWare power management options supported

Sentinel IPSMGW supports all power management.

VMWare clock synchronization

Sentinel IPSMGW does not require clock synchronization.

SR-IOV

Sentinel IPSMGW does not require SR-IOV.

Test Lab Minimum Virtual Host Requirements

1 vCPU, 8Gb RAM, 30Gb HD, 0 IOPS (Disk I/O is not normally a significant requirement as it’s not used except for logging and installation/configuration changes. Under normal operation a rhino node produces very little logging, but can use > 100Mb/s during severe error conditions under load).

Production Minimum Virtual Host Requirements

1 Rhino node per VM, 1 CPU (bound) @2.4+Ghz, 12Gb java heap, 30Gb HD, 0 IOPS. A quorum node is much lighter weight, and would require a vm with 1 vcpu, 512Mb ram, 0 IOPS.

System capacity/performance for each production system

1.08M BHCA, + 10.8K Conference attempts.

Scalability

Linear to 2.4Ghz, No scaling improvement over 2.4Ghz. (At Maximum load @ 2.4GHz, we reach saturation of Java CMS collector).

Virtual host resource changes while running

Sentinel IPSMGW does not support host resource changes while running.

Virtual network interface requirements

IPSMGW Sentinel requires 1 network interface for each mgmt/signalling interface.

Signalling bandwidth requirements

Sentinel IPSMGW requires 500kbps/BHCA.

Latency added by signalling

Sentinel IPSMGW adds 20ms at 50th percentile.

Features

This page presents summaries and links to more detailed descriptions of Sentinel IP Short Message Gateway (IPSMGW) features.

Common features

These are common features that are used in several flows

Feature What it does

instructs the Sentinel core to accept the incoming dialog.

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

records various information from incoming messages needed by the AVP CDR feature.

uses information from the incoming TCAP message request or Sh Push Notification Result to determine the MSISDN and set it in session state

uses information from the incoming TCAP message request or Sh Push Notification Result and sets the plan ID in the Sentinel selection key in Session State field. The plan ID affects which features will run for the call on the current AS instance.

sets the session state field SessionType to map or Sh_PNR.

selects the behaviour of the IPSMGW when a SIP Message request is received.

analyses the contents of an incoming Tcap Message to determine if it contains a SINGLE_COMPONENT_TYPE or MULTIPLE_COMPONENT_TYPES.

analyses the contents of an incoming Tcap Message to determine if it contains SRIForSM result SUCCESS or FAILURE (AbsentSubscriber).

sets the network operator element of the Sentinel selection key

defines immediate event charging of MO- and MT-FSMs delivered over the PS and CS networks for Sentinel as an IPSMGW.

clears all pending requests and ends all legs.

determines Mobile Country Code (MCC), Mobile Network Code (MNC), and ISO Country Code values for the subscriber.

uses an MSISDN to fetch the IMSI from the HLR via a SendRoutingInfoForSMRequest

proxies MAP messages between two network elements, typically a Serving MSC (SMSC) and an MSC.

modifies outbound messages sent between two network elements, typically a Serving MSC (SMSC) and an MSC.

uses an IMSI to send a ReadyForSM to the HLR and handles the response

instructs the Sentinel core to reject the incoming dialog.

rejects OpenRequests from SCCP addresses it does not recognize based on a provisioned whitelist.

Mobile Originated Features

These features relate to the SMS Submission path from the UE to the network.

Feature What it does

submits an SMS Over IP request to the SMSC.

updates the Orig-Address of outbound MAP MT-ForwardSM requests to allow CAP charging of the session.

sends an SMS Submit Report to an SMS over IP capable UE

Mobile Terminated Features

These features relate to the SMS Delivery path from the network to the UE.

Feature What it does

modifies the MSC address in Send Routing Info For SM responses to be the configured address of the IPSMGW. This ensures that subsequent MAP MT Forward Short Message requests are sent to the IPSMGW.

stores SMS Routing information retrieved from an HLR in Cassandra. The stored data includes additional correlation information.

retrieves Circuit Switched routing information from the Cassandra Database and stores it into session state.

reads Third Party Registration information stored in the Cassandra Database, and writes it into session state.

delivers an SMS encapsulated in SIP (SMS Over IP) to the UE

delivers a Short Message towards the MSC or SGSN, performing TCAP application context negotiation as necessary

generates a correlation IMSI when responding to a SRI request. It uses the Correlation Resource Adaptor to allocate an IMSI based on the MCC and MNC.

increments (or creates) a row in the Cassandra cluster for the current MSISDN, to be used as the RP Message Reference, writing the value into session state.

links incoming SIP delivery reports with the sentinel session that the delivery report is responding to.

Preserve Call Id Over B2BUA

The SIP B2BUA feature can be configured to preserve the Call-ID header across both legs of a B2BUA’d session. Certain MT flows require the correlation of an incoming request with an existing IP-SM-GW session. This is achieved using the In-Reply-To header of the incoming request. Depending on network configuration this may require the preservation of the Call-ID header when B2BUA’ing the MESSAGE request onwards. By default and in typical deployments, this behavior is not configured. It should only be configured if required. For more information on this configuration option read the B2BUA Feature Configuration documentation.

Short Message Memory Available Features

These features relate to the Short Message Memory Available Submission path from the UE to the network. This occurs when the UE indicates that it has memory available to receive short messages, having previously indicated that it did not have available memory.

Feature What it does

extracts the MSISDN from a SMMA message, then sends an RP-ACK to the SMMA request

Registrar features

These features relate to Third Party Registration

Feature What it does

sets a session state field based on the presence of the “+g.3gpp.smsip” parameter in first party SIP Register request Contact headers and the subscriber MSISDN session state field.

sends a MAP AnyTimeModification request to HLR to set the IP-SM-GW address and set active flag to true when a user registers.

USSI features

These features relate to processing USSI requests.

Feature What it does

analyses an incoming INVITE request to determine if it is a USSI request.

handles the SIP side of the USSI conversation.

converts USSD text to/from encoded forms

generates and sends a USSD request to an HLR, and handles the result

Common Features

These are common features that are used in several flows

Feature What it does

instructs the Sentinel core to accept the incoming dialog.

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

records various information from incoming messages needed by the AVP CDR feature.

uses information from the incoming TCAP message request or Sh Push Notification Result to determine the MSISDN and set it in session state

uses information from the incoming TCAP message request or Sh Push Notification Result and sets the plan ID in the Sentinel selection key in Session State field. The plan ID affects which features will run for the call on the current AS instance.

sets the session state field SessionType to map or Sh_PNR.

selects the behaviour of the IPSMGW when a SIP Message request is received.

analyses the contents of an incoming Tcap Message to determine if it contains a SINGLE_COMPONENT_TYPE or MULTIPLE_COMPONENT_TYPES.

analyses the contents of an incoming Tcap Message to determine if it contains SRIForSM result SUCCESS or FAILURE (AbsentSubscriber).

sets the network operator element of the Sentinel selection key

defines immediate event charging of MO- and MT-FSMs delivered over the PS and CS networks for Sentinel as an IPSMGW.

clears all pending requests and ends all legs.

determines Mobile Country Code (MCC), Mobile Network Code (MNC), and ISO Country Code values for the subscriber.

uses an MSISDN to fetch the IMSI from the HLR via a SendRoutingInfoForSMRequest

proxies MAP messages between two network elements, typically a Serving MSC (SMSC) and an MSC.

modifies outbound messages sent between two network elements, typically a Serving MSC (SMSC) and an MSC.

uses an IMSI to send a ReadyForSM to the HLR and handles the response

instructs the Sentinel core to reject the incoming dialog.

rejects OpenRequests from SCCP addresses it does not recognize based on a provisioned whitelist.

AVP CDR

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

It runs once when a session is ending and creates a CDR based on information gathered from session state, and then writes it out using the cdr-ra.

Tip

By default, Sentinel runs IpsmgwAvpCdr in the post SIP end session feature execution script. For example:

featurescript PostEndSession {
    run IpsmgwAvpCdr
}

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IpsmgwAvpCdr

No

N/A

Stateless

POJO

Session state inputs and outputs

Inputs

If any of these fields are unset the feature will skip writing them to the CDR file.

This feature uses the same session state fields as the Sentinel SIP AVP CDR feature. This page will only discuss the additions to the fields described there.

Name Type Description Where set

SubmitReportType

Enumerated

The submit report type for the MOFSM plan ID. One of SUCCESS, INVALID_SMS, COMMUNICATION_ERROR, U_ABORT, P_ABORT, INVOKE_TIMEOUT, MO_FORWARD_SM_ERROR, or SS7_STACK_ERROR.

MO Submission feature

MSISDN

String

The MSISDN of a subscriber

Fetch Routing Info Cassandra feature, MO Submission feature, SMMA Response feature, Store Routing Info Cassandra feature

IMSI

String

The IMSI of a subscriber

Fetch Routing Info Cassandra feature

MTCorrelatedId

String

The MT correlated ID

Fetch Routing Info Cassandra feature, Generate MT Correlation Id feature

PSDeliveryStatus

Enumerated

The PS delivery status; one of NOT_ATTEMPTED, FAILED, or SUCCEEDED

PS Delivery feature

CSDeliveryStatus

Enumerated

The CS delivery status; one of NOT_ATTEMPTED, FAILED, or SUCCEEDED

CS Delivery feature

Impu

String

The IMPU of a subscriber

CDR Info feature

OrigSccpAddress

String

The origination SCCP address of a call

CDR Info feature

DestSccpAddress

String

The destination SCCP address of a call

CDR Info feature

Functionality

This features uses the information from the session state fields mentioned above and constructs a protobuf message out of it for output. See AVP CDR Format for the format of these messages.

Also see Charging Information for general information about the contents of CDRs and CCRs.

Note This feature only supports writing binary CDRs. If the cdr-ra is configured to write string CDRs the feature will fail to execute.

Feature responses

Response Reason

featureHasFinished

feature has finished

Accept Dialog

This feature instructs the Sentinel core to accept the incoming dialog.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWAcceptDialog

No

MTFSM_PS_CS,MTFSM_CS_PS,MTFSM_PS,MTFSM_CS

Stateless

POJO

Configuration

The feature uses the Shared Configuration Profile. The following attributes are used:

Attributes Type Meaning
UseGtAsCallingParty

Boolean

When accepting an OpenRequest, the SCCP responder address in the OpenAccept will, by default, be set to the value of the SCCP called party in the OpenRequest. If UseGtAsCallingParty is set to true, and if the received sccp-called-party contains a global title, the responder address will be modified in the following way:
The Translation Type is set to 0
The Routing Indicator will be set to gt
The Point Code will be unset
The National indicator will be set to false.

This is useful when the inbound sccp-called-party has been modified by a network element to use PCSSN routing, but GT routing is required for establishing the TCAP dialog.

Behaviour

This feature instructs the Sentinel core to accept the incoming dialog.

CDR Info

This feature records various information from incoming messages needed by the AVP CDR feature.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

CDRInfo

No

N/A

Stateless

POJO

Statistics

The feature has no statistics.

Configuration

The feature has no configuration.

Outputs

Name Type Description

Impu

String

The IMPU determined from an incoming SIP response on an MTFSM plan ID

OrigSccpAddress

String

The origination SCCP address taken from an incoming dialog TCAP message

DestSccpAddress

String

The destination SCCP address taken from an incoming dialog TCAP message

Behaviour

The feature examines incoming SIP and TCAP messages and extracts information from them. This information is saved in session state fields to make it available to the AVP CDR feature that runs at the end of a session.

Determine Is SMS Over IP

This feature selects the behaviour of the IPSMGW when a SIP Message request is received.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWDetermineIsSMSOverIP

No

Any

Stateless

POJO

Statistics

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

Name Description
IsSMSOverIP

Incremented when a SIP MESSAGE’s Content-Type is application/vnd.3gpp.sms

SentSuccess

Incremented when a 'success' final response is sent (e.g. 202)

SentError

Incremented when a 'error' final response is sent (e.g. 403)

SessionIsMOFSM

Incremented when MESSAGE’s RP-DATA direction is from MobileStation to Network

Configuration

The feature has no configuration.

Behaviour

If the SIP Message Request body does not include an SMS, the default product configuration has the IP-SM-GW act as a Routing B2BUA, thereby sending the SIP Message request towards the S-CSCF.

The Content-Type header is checked to see if it is application/vnd.3gpp.sms, and if so this indicates that the request is SMS over IP related. The session state field IsSMSOverIP set to true. If the Content-Type header does not match the feature finishes execution.

Next the body of the SIP Message Request is parsed as an RP Message. If parsing is unsuccessful the feature sends a 403 response, increments the SentError statistic and finishes execution.

Assuming that parsing is successful, the feature then checks the RP Message Type Indicator for directionality of MS to Network. If the direction is Network to MS it is a message type that the IP-SM-GW does not process, so the feature finishes execution and the IP-SM-GW will act as a Routing B2BUA.

Assuming the direction is MS to Network, the following occurs:

  • if the RP Message Type indicates RP-DATA, the feature sets the Sentinel Selection Key’s PlanID field to the value "MOFSM". This corresponds to the MO Submission Flows, and Mobile Originated Features.

  • if the RP Message Type indicates RP-SMMA, the feature sets the Sentinel Selection Key’s PlanID field to the value "SMMA". This corresponds to the Short Message Memory Available Flows.

  • if the RP Message Type indicates RP-ACK, or RP-ERROR, the feature sets the Sentinel Selection Key’s PlanID field to the value "MTFSM_DR". This corresponds to the Delivery Report portion of the MT Delivery Flows.

Determine MSISDN

This feature uses information from the incoming TCAP message request or Sh Push Notification Result to determine the MSISDN and set it in session state

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWDetermineMSISDN

No

SRI4SM and Sh_PNR

Stateless

POJO

Statistics

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

Name

Description

FailedToDetermineMSISDN

Incremented when the MSISDN can’t be determined

IgnoringTrigger

Incremented when the trigger is not TCAP OpenRequest or Sh UEReahabilityForIP PNR

Configuration

The feature has no configuration.

Behaviour

The feature checks if the trigger message is a TCAP OpenRequest message or a Sh UEReahabilityForIP Push Notification Result. In each case the MSISDN session state field is set to the extracted MSISDN.

Determine Network Operator

Description

Feature name

IPSMGWDetermineNetworkOperator

Applicable contexts

IPSMGW service

Prerequisite features

None

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

Error scenarios

Scenario Handling

Sessionstate SentinelSelectionKey is null

Report featureCannotStart

Trigger is null

Report featureCannotStart

Trigger event not a TCAPMessage or Push notification request

Report featureCannotStart

TCAP open request is null

Report featureCannotStart

DestinationAddress in DialogOpenRequestEvent is null

Report featureCannotStart

Could not match DestinationAddress in IPSMGWDetermineNetworkOperatorGlobalTitleAddress

Increment CouldNotDetermineNetworkOperator
Report featureFailedToExecute

Feature responses

Response Reason

featureCannotStart

Trigger event must be DialogOpenRequestEvent or PushUEReachabilityForIPResult, 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

Behaviour

The following logic is used for determining the Network Operator

  • If the trigger is a push notification request that is not associated with a subscription by this service, then the default network operator is used

  • If the destinationSccpAddress.GT is not available, then the default network operator is used

  • If the destinationSccpAddress.GT is available but not found in the network operator selection table, then the default network operator is used

  • If the destinationSccpAddress.GT is found in the network operator selection table, then the network operator value from the matched selection table record is used.

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=5, 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 Lists 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}_IPSMGWDetermineNetworkOperator_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:IPSMGWDetermineNetworkOperator:GlobalTitleAddress

${PLATFORMOPERATOR}_IPSMGWDetermineNetworkOperator_AddressListEntryTable

Feature-specific Address List entry table

${SELECTIONKEY}:IPSMGWDetermineNetworkOperator:GlobalTitleAddress:${ADDRESS}

SentinelConfigurationTable

Sentinel configuration table (contains DefaultNetworkOperator)

SentinelConfiguration

Provisioning interfaces

The feature is provisioned using the Sentinel Features REST API.

Determine SRIForSM Result Failure

This feature analyses the contents of an incoming Tcap Message to determine if it contains SRIForSM result SUCCESS or FAILURE (AbsentSubscriber).

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

DetermineSRIForSMFailureResult

No

N/A

Stateless

POJO

Session Input variables

The feature reads the following fields in Session State

Session State variable name Variable type Comments
MTFSMDeliveryOrder

com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder

In the absentSubscriber case, If CS_ONLY, will set LookupIMSRegistration to false

Session Output variables

The feature sets the following fields in Session State

Session State variable name Variable type Comments
LookUpIMSRegistration

Boolean

SRI4SMResult

enum

Indicates if the SendRoutingInfoForSM request has succeeded. Allowed values are NOT_ATTEMPTED, SUCCESS, and FAILED

SRI4SMError

TcapError

The TcapError received in response to the SendRoutingInfoForSMRequest

Statistics

The feature has no statistics.

Behaviour

The feature checks if the trigger message is a TCAP Message, if it is then it analyses the components to determine if the Tcap Message contains a SRIForSM response and sets the following session state fields:

  • SRI4SMResult SUCCESS or FAILURE depending on whether a TCOperationResult or TCError

  • LookupIMSRegistration if a TCError AbsentSubscriber was received.

Both are used subsequently in feature scripts to control behaviour, LookupIMSRegistration is used to indicate whether subscriber data should be read from Cassandra (IMS Registration). If the subscriber is IMS registered or the SRIForSM result indicated success then delivery will be attempted.

SRI4SM_SipThirdPartyAccess_PartyResponse:
    FeatureScriptSrc: featurescript SipThirdPartyAccessPartyResponse {
      run IPSMGWMapProxy
      run DetermineSRIForSMFailureResult
      if session.LookupIMSRegistration {
          run IPSMGWRegistrationLookupFromCassandra
      }
      if session.isSMSOverIPRegistered or session.SRI4SMResult.SUCCESS {
          run IPSMGWModifySRILeg
          run IPSMGWGenerateMTCorrelationId
          run IPSMGWStoreRoutingInfoCassandra mode "store"
          run IPSMGWAdjustRoutingInfoResponse
      }
    }

Determine Session Plan

This feature uses information from the incoming TCAP message request or Sh Push Notification Result and sets the plan ID in the Sentinel selection key in Session State field. The plan ID affects which features will run for the call on the current AS instance.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWDetermineSessionPlan

No

N/A

Stateless

POJO

Session Input variables

The feature reads the following fields in Session State

Session State variable name Variable type Comments
SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::) For selecting IPSMGWSharedConfig profile to retrieve DeliveryOrder

MTFSMDeliveryOrder

com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder

If already set, will not be updated

Session Output variables

The feature sets the following fields in Session State

Session State variable name Variable type Comments
MTFSMDeliveryOrder

com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder

DeliveryOrder retrieved from configuration

Statistics

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

Name

Description

ReceivedSRI4SM

Incremented when OpenRequest is shortMsgGatewayContext

ReceivedMOFSM

Incremented when OpenRequest is shortMsgMO_RelayContext

ReceivedMTFSM

Incremented when OpenRequest is shortMsgMT_RelayContext

ReceivedPNR

Incremented when the trigger is a Sh UEIPReachability PNR

ReceivedUnknownACN

Incremented when OpenRequest is none of the context above

ReceivedUnknownTrigger

Incremented when the trigger is not TCAP OpenRequest

Configuration

The feature has no configuration.

Behaviour

The feature checks if the trigger message is a TCAP OpenRequest message or a Sh UEReahabilityForIP Push Notification Result. If it is a TCAP OpenRequest message, then the PlanId selection key field is set to SRI4SM, MOFSM, MTFSM_<DeliveryOrder> [1] or UnknownACN. The configured DeliveryOrder is set in the MTFSMDeliveryOrder session state field unless MTFSMDeliveryOrder was already set. If it is a Sh Push Notification Result, then the PlanId selection key field is set to Sh_PNR. Otherwise the feature does not set the PlanId field of the SentinelSelectionKey session state field.

Plan ID selection circumstances

Session Trigger Resulting PlanId

MAP shortMsgGatewayContext_v1_ac
MAP shortMsgGatewayContext_v2_ac
MAP shortMsgGatewayContext_v3_ac

SRI4SM

MAP shortMsgMO_RelayContext_v1_ac
MAP shortMsgMO_RelayContext_v2_ac
MAP shortMsgMO_RelayContext_v3_ac

MOFSM

MAP shortMsgMT_RelayContext_v1_ac
MAP shortMsgMT_RelayContext_v2_ac
MAP shortMsgMT_RelayContext_v3_ac

One of:
MTFSM_PS
MTFSM_CS
MTFSM_PS_CS
MTFSM_CS_PS

Sh UEReachabilityForIP Push Notification Result

Sh_PNR

Determine Session Type

This feature sets the session state field SessionType to map or Sh_PNR.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWDetermineSessionType

No

N/A

Stateless

POJO

Statistics

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

Name Description
ReceivedTcap

Incremented when a TCAP message is received

ReceivedPnr

Incremented when a Sh UEReachabilityForIP PNR is received

ReceivedUnknownTrigger

Incremented when message received is not a TCAP message or Sh PNR

Configuration

The feature has no configuration.

Behaviour

The feature checks if the trigger message is a TCAP message or a Sh UEReahabilityForIP Push Notification Request. If it is a TCAP message, then the session state field SessionType is set to map. If it is a Push Notification Request, then the session state field PlanId is set to Sh_PNR. Otherwise the feature leaves the SessionType session field state unset.

Determine Tcap Message Components

This feature analyses the contents of an incoming Tcap Message to determine if it contains a SINGLE_COMPONENT_TYPE or MULTIPLE_COMPONENT_TYPES.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

DetermineTcapMessageComponents

No

N/A

Stateless

POJO

Session Input variables

The feature has no session input variables.

Session Output variables

The feature sets the following fields in Session State

Session State variable name Variable type Comments
TcapMessageComponents

Enum

possible values, SINGLE_COMPONENT_TYPE or MULTIPLE_COMPONENT_TYPES

Statistics

The feature has no statistics.

Configuration

The feature has no configuration.

Behaviour

The feature checks if the trigger message is a TCAP Message,if it is then it analyses the components to determine if the Tcap Message contains either a SINGLE_COMPONENT_TYPE or MULTIPLE_COMPONENT_TYPES (TCOperationResult and TCOperationInvoke) and sets a session state field. The value of the session state field can then be used subsequently in feature scripts to select which features to run. The following excerpt demonstrates how the feature and session state field can be used in feature scripts.

SRI4SM_SipThirdPartyAccess_PartyRequest:
    FeatureScriptSrc: featurescript SipThirdPartyAccessPartyRequest {
        run IPSMGWMapProxy
        run DetermineTcapMessageComponents
        if session.TcapMessageComponents.MULTIPLE_COMPONENT_TYPES {
            run IPSMGWGenerateMTCorrelationId
            run IPSMGWStoreRoutingInfoCassandra mode "store"
            run IPSMGWAdjustRoutingInfoResponse
        } else {
            run IPSMGWStoreRoutingInfoCassandra mode "store"
        }
    }

End Session

This feature clears all pending requests and ends all legs.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWEndSession

No

MTFSM_PS_CS,MTFSM_CS_PS,MTFSM_PS

Stateless

POJO

Configuration

The feature has no configuration.

Behaviour

This feature instructs the Sentinel core to immediately clear all pending requests, and enqueue an EndSession instruction on all legs.

Fetch IMSI

This feature uses an MSISDN to fetch the IMSI from the HLR via a SendRoutingInfoForSMRequest

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWFetchIMSI

No

SMMA, Sh_PNR, register

Stateless

POJO

Feature parameters

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

Name Allowed Values Description

mode

fetch and response

This is used to determine what action the feature should take when run.

Session Input variables

The feature reads the following fields in Session State

Session State variable name Variable type Comments
MSISDN

String

The MSISDN to use in the SendRoutingInfoForSM operation

Session Output variables

The feature sets the following fields in Session State

Session State variable name Variable type Comments
IMSI

String

The IMSI retrieved from the SendRoutingInfoForSM response

SRI4SMResult

enum

Indicates if the SendRoutingInfoForSM request has succeeded. Allowed values are NOT_ATTEMPTED, SUCCESS, and FAILED

SRI4SMError

TcapError

The TcapError received in response to the SendRoutingInfoForSMRequest

Statistics

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

Name Description
SavedIMSI

Incremented when we successfully retrieve the IMSI from the HLR

SentSRIForSM

Incremented when the SRIForSM is sent to the HLR

FailedToSendSRIForSM

Incremented when the SRIForSM fails to be sent to the HLR

Configuration

The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is IPSMGWSharedConfigProfileTable.

The following attributes are available

Attributes Type Meaning
HlrAddress

String

Address of the HLR to request the IMSI from, used when establishing the MAP dialog if UseMsisdnAsHlrAddress is not configured

UseMsisdnAsHlrAddress

Boolean

Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured HlrAddress

SentinelOriginatingAddress

String

Address of Sentinel used when establishing the MAP dialog

SentinelIPSMGWAddress

String

The IP-SM-GW address that the feature will include it in MAP SendRoutingInfoForSMRequest request to send to HLR

SriSmDeliveryNotIntended

Boolean

If true, specify the SmDeliveryNotIntended flag when performing an SRI for SM IMSI-only query (i.e. during SMMA callflows).

Using MSISDN as HLR Address

The Fetch IMSI feature can optionally address the HLR leg using a GT address formed from the inbound subscriber MSISDN, as opposed to using the destination addresses configured in the IPSMGWMapProxyConfigProfileTable profile table described above.

This behaviour can be enabled or disabled by setting the UseMsisdnAsHlrAddress attribute in the Shared Configuration Profile.

MAP Application Context

The feature uses MAP Application Context shortMsgGatewayContext_v2_ac. This application context was added in GSM MAP Phase 2.

Important If SriSmDeliveryNotIntended is set to true, the feature will create a MAP v3 dialog instead of a v2 dialog. Only enable this configuration if this parameter is supported by the configured HLR.

Behaviour

When run with mode fetch the FetchIMSI feature will read the MSISDN out of session state. It is then used to send a SendRoutingInfoForSMRequest to the HLR. The request always has the SM-RP-PRI flag set to TRUE, and optionally has smDeliveryNotIntended set to "only IMSI requested" (based on the SriSmDeliveryNotIntended configuration flag).

When run with mode response the feature will look for the receipt of the SendRoutingInfoForSMResponse, it extracts the IMSI and sets it in session state. If the SendRoutingInfoForSMRequest results in an error response then it will set the SRI4SMResult and SRI4SMError session state fields instead.

If the feature is run without a mode parameter it returns a Feature Error.

IPSMGW Extract Network Info Feature

This feature determines Mobile Country Code (MCC), Mobile Network Code (MNC), and ISO Country Code values for the subscriber.

This data can then be included in Credit Control Requests (CCR)s by mappers and Call Detail Records (CDR)s by the AVP CDR feature.

This feature is an extension of the Sentinel SIP Extract Network Info feature. It implements the same behaviour as that feature for SIP message triggers, but also includes behaviour for dealing with TCAP message triggers.

Feature cheat sheet

Feature Script Name

IPSMGWExtractNetworkInfo

Call-Type

Orig or Term

Session Plan

default, MOFSM, SMMA, MTFSM_PS_CS, MTFSM_CS_PS, MTFSM_PS, MTFSM_DR, MTFSM_CS

Execution Points

Post_SipAccess_SubscriberCheck, Post_SubscriptionSubscriberCheck, Post_SipTransaction_SubscriberCheck, Post_SipThirdPartyAccess_SubscriberCheck

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

For SIP message triggers only:

Session State Inputs and Outputs

This feature uses all of the session state fields of its parent feature. For a list of these, see that features documentation.

In addition, it uses the following fields:

Inputs

Name Type Purpose

IMSI

String

The IMSI for the current subscriber.

Outputs

Name Type Description

ImsiMccMnc

com.opencloud.sentinel.common.MccMnc

The MCC and MNC that the feature extracts from the IMSI.

Statistics

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

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.

IgnoringTrigger

Counter

Incremented when trigger is not a TCAP message or SIP request.

TcapTrigger

Counter

Incremented when the feature is triggered on a TCAP message.

SipRequestTrigger

Counter

Incremented when the feature is triggered on a SIP request.

ImsiMccMncFound

Counter

Incremented when MCC and MNC is found in IMSI.

UnableToDetermineImsiMccMnc

Counter

Incremented when an MCC and MNC for the IMSI cannot be determined.

Configuration

This feature uses the same configuration profiles as the Extract Network Info feature. See:

Provisioning interfaces

The feature is provisioned using the Sentinel IP-SM-GW feature REST API.

Behaviour

SIP Request Triggers

When triggered by a SIP request, this feature will execute its parent feature’s behaviour as described here: Extract Network Info - Behaviour

TCAP Message Triggers

The IPSMGWExtractNetworkInfo feature extracts MCCs and MNCs from:

  • The access and visited network info headers found in registration records. This requires the Registration Lookup From Cassandra feature to run before this feature.

  • The IMSI. This requires the Fetch IMSI feature to run before this feature.

The resulting information is recorded in session state for use by the AVP CDR Feature feature when writing a CDR, as well as the charging features when forming charging requests.

The following OpenCloud extension AVPs are used to communicate MCC and MNC information in CCRs and CDRs:

  • OC-ACCESS-NETWORK-MCC-MNC

  • OC-VISITED-NETWORK-MCC-MNC

  • OC-IMSI-NETWORK-MCC-MNC

  • 3GPP-IMSI-NETWORK-MCC-MNC

For Sentinel AVP definitions, please refer to Sentinel AVP Definitions in the Sentinel Administration guide.

Other Triggers

For all other triggers, the feature will do nothing.

IPSMGW IEC Feature

The IPSMGW IEC charging feature defines immediate event charging of MO- and MT-FSMs delivered over the PS and CS networks for Sentinel as an IPSMGW.

Description

Feature script name

IPSMGWIECFeature

Applicable contexts

SIP service

Prerequisite features

PS Delivery or CS Delivery or MO Submission

Feature execution points

SipAccess_ChargingAbort SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_ServiceTimer SipInstructionExecutionFailure SipThirdPartyAccess_SubscriberCheck SipThirdPartyAccess_PartyRequest SipThirdPartyAccess_PartyResponse SipTransaction_SubscriberCheck SipTransaction_Request SipTransaction_PartyResponse

The IPSMGW IEC feature covers immediate event charging using a charge/refund model. The feature is responsible for:

  • creating the reservation charging instance (IPSMGWChargingFeatureUtil.DEFAULT_IEC_CHARGING_INSTANCE) and default session counter on a pending delivery.

  • 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 an SMS will be delivered by one of IPSMGW’s delivery or submission features. On the incoming MO SIP MESSAGE, or MT-FSM DialogTcapMessage, the IEC feature will trigger a direct debit, suspending the outgoing message until a charging response is received, before allowing the message to be sent. If a response to the message is received which indicates failure, a refund will be issued, unless a fallback is attempted that also has charging enabled.

For a high level overview of Sentinel charging see Sentinel SIP Charging Architecture

Note

Currently, IPSMGW only supports one charging instance per Sentinel session, though this instance may have multiple session counters.

Tip All of IPSMGW’s charging features make use of Sentinel’s comprehensive charging API — see Using the SIP Charging Manager

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWIECFeature

No

MTFSM_PS,MTFSM_CS,MTFSM_CS_PS,MTFSM_PS_CS

Stateless

SBB

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

SentinelIPSMGWAddress
com.opencloud.slee.resources.in.datatypes.cc.AddressString

MAP-CommonDataTypes.AddressString

The value that the feature will use as the MSC-address in outgoing messages. Written to SessionState for retrieval by charging mappers.

N/A

IPSMGWChargingCounterAddress
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 feature only treats one counter as the immediate 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.

PSDeliveryStatus
com.opencloud.sentinel.ipsmgw.sessionstate.mt.PSDeliveryStatus

NOT_ATTEMPTED/FAILED/SUCCEEDED

Outcome of last PS Delivery attempt

N/A

CSDeliveryFailed

boolean

Whether the CS Delivery feature delivery attempt failed

N/A

MoSubmissionFailed

boolean

Whether the MOSubmission feature delivery attempt failed

N/A

PSDeliveryTimerID
javax.slee.facilities.TimerID

The ID of the PS Delivery timer

Used in determining whether to do a refund after a delivery failure

Timer event is ignored

IECChargingInstructed

boolean

Whether there has already been a charging instruction in this session

N/A

IECRefundInstructed

boolean

Whether there has already been a refund instruction in this session

N/A

LatestClientRequest
org.jainslee.resources.diameter.ro.types.vcb0.CreditControlRequest

Credit-Control-Request

Determine whether an incoming CCA is a direct debit

N/A

Outputs

Name Format Description

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

UserSessionId

String

The MT SIP session ID

InboundSipRequest
org.jainslee.resources.sip.SipRequest

The incoming SIP request in MO deliveries

Used to extract information for use in a CCR

InboundDialogTcapMessage
com.opencloud.sentinel.ipsmgw.eventmanager.tcapmessage.DialogTcapMessage

The incoming TCAP message in MT deliveries

Used to extract information for use in a CCR

IECChargingInstructed

boolean

Set after a DIRECT_DEBIT CCR has been sent to the OCS

IECRefundInstructed

boolean

Set after a REFUND_ACCOUNT CCR has been sent to the OCS

Charging API interactions

The charging API interactions fall under the following categories:

  • charging instructions issued on the IPSMGWChargingFeatureUtil.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 feature is first triggered on an incoming message, if there is a delivery message pending, it creates the default IEC charging instance, under the name IPSMGWChargingFeatureUtil.IPSMGW_IEC_CHARGING_INSTANCE. It then maps the request to a session counter address written to the session state field IPSMGWChargingCounterAddress. This is the default session counter on which all subsequent IEC based charging is performed.

Initial debit

On any trigger other than an incoming message request, the feature checks whether the IPSMGWChargingFeatureUtil.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 IPSMGWChargingCounterAddress. If either check fails, the feature ends immediately on the assumption that IEC is not enabled.

The feature will instruct the charging instance to send a direct debit message to the OCS. It will suspend the outgoing delivery leg until the OCS authorises the request.

The Ro Credit-Control-Request is generated using the IPSMGWChargingInstanceToCCR mapper.

Refund

If the feature is triggered on a non-success response to a chargeable event, and no fallback attempts are left, the 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 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 feature. Generally speaking, user features need not interact directly with this counter.

Mappers

This feature relies on two mappers:

  • The first converts the initial message to a SessionCounterAddress.
    The default implementations are MTFSMToSessionCounterAddress and `SipRequestToSessionCounterAddress`SipRequestToSessionCounterAddress:

    // a mapper that takes a DialogTcapMessage or SipRequest and generates a SessionCounterAddress.
    final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper(
            getSessionState().getSentinelSelectionKey(),
            argClass,
            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

MAP Proxy

This MAP Proxy feature proxies MAP messages between two network elements, typically a Serving MSC (SMSC) and an MSC.

Description

The MAP proxy acts as an intermediary between two network elements, typically an SMSC and MSC. The MAP proxy manages two TCAP legs, one to each network element, and forwards messages received on each leg to the other linked leg.

map proxy
Figure 1. The MAP Proxy Feature

The SCCP address of the destination network element is found by searching the feature configuration using the Sentinel Selection Key and the TCAP Application Context of the initial Dialog Open Request.

Tip

The IPSMGW uses the Map Proxy feature in Sending Routing Info For SM call flows.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWMapProxy

Yes

SRI4SM

Stateless

POJO

Session Input variables

The feature reads the following fields in Session State

Session State variable name Variable type Comments
MSISDN

String

The MSISDN to use for addressing the HLR by GT

Statistics

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

Name Description
NewProxyLeg

Incremented when a new proxy scenario is started

NoLegForTriggerAci

Incremented when the proxy feature is triggered but there is no leg associated with the triggering ActivityContextInterface. This may happen if the triggering leg is detached by some other feature before the IPSMGWMapProxy feature starts

NoProxyLeg

Incremented when the proxy feature is triggered but there is no associated leg to proxy messages to. This may happen if the proxy leg is detached, or unlinked by some other feature before the IPSMGWMapProxy feature starts

FailedtoCreateNewProxyLeg

Incremented when there is any error creating a new proxy leg

LegExistsOnNewProxyLeg

Incremented when a new proxy leg cannot be created because a leg with the requested name already exists

ProxyLegAlreadyLinked

Incremented when there is an error linking the proxy leg to the triggering leg because the legs are already linked

Configuration

The IPSMGWMapProxy can proxy to different destinations based on the triggering TCAP Application Context and the value of the Sentinel Selection key.

The first Profile Table used to hold feature configuration is Shared Configuration Profile. The following attributes are used:

Attributes Type Meaning
UseMsisdnAsHlrAddress

Boolean

Address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured DestinationAddress

UseGtAsCallingParty

Boolean

When accepting an OpenRequest, the SCCP responder address in the OpenAccept will, by default, be set to the value of the SCCP called party in the OpenRequest. If UseGtAsCallingParty is set to true, and if the received sccp-called-party contains a global title, the responder address will be modified in the following way:
The Translation Type is set to 0
The Routing Indicator will be set to gt
The Point Code will be unset
The National indicator will be set to false.

This is useful when the inbound sccp-called-party has been modified by a network element to use PCSSN routing, but GT routing is required for establishing the TCAP dialog.

The second Profile Table used to hold feature configuration is IPSMGWMapProxyConfigProfileTable. Entries in the table are indexed by a Sentinel Selection key that is qualified by a TCAP Application Context. The following attributes are available

Attributes Type Meaning
DestinationAddress

String

The SCCP Address of the destination MSC, used when UseMsisdnAsHlrAddress is not configured

In the example below, the IPSMGWMapProxy feature is configured so 'shortMsgGatewayContext' triggers for MAP 1, 2 or 3 are proxied to 'type=C7,ri=pcssn,pc=5,ssn=6'.

Profile Name DestinationAddress

${platform.operator.name}:::::map:shortMsgGatewayContext-v3-ac

type=C7,ri=pcssn,pc=5,ssn=6

${platform.operator.name}:::::map:shortMsgGatewayContext-v2-ac

type=C7,ri=pcssn,pc=5,ssn=6

${platform.operator.name}:::::map:shortMsgGatewayContext-v1-ac

type=C7,ri=pcssn,pc=5,ssn=6

Using MSISDN as Destination Address

The MAP Proxy feature can optionally address the HLR leg using a GT address formed from the inbound subscriber MSISDN, as opposed to using the destination addresses configured in the IPSMGWMapProxyConfigProfileTable profile table described above.

This behaviour can be enabled or disabled by setting the UseMsisdnAsHlrAddress attribute in the Shared Configuration Profile.

Modify SRI Leg

This Modify SRI Leg feature modifies outbound messages sent between two network elements, typically a Serving MSC (SMSC) and an MSC.

Description

The Modify SRI Leg feature acts as an intermediary between two network elements, typically an SMSC and MSC. The feature modifies outbound Send Routing Info for SM requests, and/or discards outbound InformSC requests based on configuration. This is primarilly intended for use with the Map Proxy Feature to ensure that outbound SendRoutingInfoForSM messages have SM RP PRI set to true, and to ensure InformSC requests are not proxied.

Tip

The IPSMGW uses the Modify SRI Leg feature in Sending Routing Info For SM call flows.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWModifySRILeg

Yes

SRI4SM

Stateless

POJO

Statistics

IPSMGWModifySRILeg statistics can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWModifySRILeg
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=2.9.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=2.9.0].feature.IPSMGWMapProxy

Name Description
InformSCDiscarded

Incremented when an outbound InformSC is discarded.

SMRPPRIForced

Incremented when an outbound SentRoutingInfoForSM request has the Sm_RP_PRI field forced to true.

GPRSSupportIndicatorRemoved

Incremented when an outbound SentRoutingInfoForSM request has the GPRS Support indicator removed.

Configuration

The feature configuration is in a Profile Table called IPSMGWModifySRILegConfigProfileTable. Entries in the table are indexed by a Sentinel Selection key. The following attributes are available

Attributes Type Meaning
DiscardInformSC

boolean

If true, discard outbound InformSC components

ForceSMRPPRI

boolean

If true, force Sm_RP_PRI to be set to true in SendRoutingInfoForSM requests

In the example below, the IPSMGWModifySRILeg feature is configured so InformSC messages are discarded, but SendRoutingInfoForSM messages are sent unmodified.

Profile Name

DiscardInformSC

ForceSMRPPRI

${platform.operator.name}::::

true

false

Ready For SM

This feature uses an IMSI to send a ReadyForSM to the HLR and handles the response

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWReadyForSM

No

SMMA, Sh_PNR, register

Stateless

POJO

Session Input variables

The feature reads the following fields in Session State

Session State variable name Variable type Comments
IMSI

String

The IMSI to use in the ReadyForSM operation

MSISDN

String

The MSISDN to use for addressing the HLR by GT

SRI4SMResult

enum

Indicates if the SendRoutingInfoForSM request has succeeded. Allowed values are NOT_ATTEMPTED, SUCCESS, and FAILED

Session Output variables

The feature sets the following fields in Session State

Session State variable name Variable type Comments
ReadyForSMResult

enum

Indicates if the ReadyForSM request has succeeded. Allowed values are NOT_ATTEMPTED, SUCCESS, and FAILED

ReadyForSMError

TcapError

The TcapError received in response to the ReadyForSM

Statistics

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

Name Description
SentReadyForSM

Incremented when the ReadyForSM message is successfully sent to the HLR

FailedToSendReadyForSM

Incremented when the ReadyForSM message fails to be sent to the HLR

NoIMSIAvailable

Incremented when the IMSI was not available from session state

SRI4SMFailed

Incremented when the SendRoutingInfoForSMRequest failed and the feature cannot do anything as a result

Configuration

The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is IPSMGWSharedConfigProfileTable.

The following attributes are available

Attributes Type Meaning
HlrAddress

String

Address of the HLR to send the ReadyForSM request, used when establishing the MAP dialog if UseMsisdnAsHlrAddress is not configured

UseMsisdnAsHlrAddress

boolean

Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured HlrAddress

SentinelOriginatingAddress

String

Address of Sentinel used when establishing the MAP dialog

InvokeTimeout

int

The timeout in milliseconds for the response from HLR. Used in the TCAP layer for the invoke timeout. Default is 5000

Using MSISDN as HLR Address

The Ready For SM feature can optionally address the HLR leg using a GT address formed from the inbound subscriber MSISDN, as opposed to using the destination addresses configured in the IPSMGWMapProxyConfigProfileTable profile table described above.

This behaviour can be enabled or disabled by setting the UseMsisdnAsHlrAddress attribute in the Shared Configuration Profile.

MAP Application Context

The feature uses MAP Application Context mwdMngtContext_v2_ac. This application context was added in GSM MAP Phase 2.

Behaviour

When triggered on a TCAP message the feature checks that an IMSI is present in session state field named IMSI. It then initiates a ReadyForSM operation to the HLR with an alert reason of:

  • Memory Available if session Plan Id is SMMA

  • MS Present if session Plan Id is Sh_PNR or register

When the ReadyForSM operation completes, the feature sets the ReadyForSMResult session state field based on the response, SUCCESS if the ReadyForSM operation is successful, FAILED if the ReadyForSM operation returns an error or a timeout. It also sets the ReadyForSMError session state field with the TcapError if the response was a failure.

Reject Dialog

This feature instructs the Sentinel core to reject the incoming dialog.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWRejectDialog

No

Any

Stateless

POJO

Configuration

The feature has no configuration.

Behaviour

This feature instructs the Sentinel core to reject the incoming dialog.

SCCP Whitelist

Description

Feature name

IPSMGWSCCPWhitelist

Applicable contexts

IPSMGW service

Prerequisite features

None

The IPSMGW SCCP Whitelist Feature rejects OpenRequests from SCCP addresses it does not recognize based on a provisioned whitelist.

Request from non-GT addresses will be allowed without checking the whitelist. If a whitelist is not found, the feature ends immediately, allowing call processing to continue. If the whitelist is then found to be empty, the feature ends, allowing call processing to continue. If the originating address contains GT digits, it will match those against the provisioned whitelist using the list’s configured address search mode. If a match is not found, the incoming leg is released via endSession.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWSCCPWhitelist

No

SRI4SM,MTFSM_PS_CS,MTFSM_CS_PS,MTFSM_PS,MTFSM_CS

Stateless

POJO

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

Report featureCannotStart, featureHasFinished

Outputs

No session state outputs

Error scenarios

Scenario Handling

Trigger event not a TCAPMessage

Report featureCannotStart

TCAP open request is null

Report featureCannotStart

Sessionstate SentinelSelectionKey is null

Report featureCannotStart

Trigger is null

Report featureCannotStart

OrigAddr in DialogOpenRequestEvent is null

Report featureCannotStart

Feature responses

Response Reason

featureCannotStart

Trigger event must be DialogOpenRequestEvent, SessionState SentinelSelectionKey is not set, unsupported trigger, originating SCCP address not present in DialogOpenRequestEvent

featureHasFinished

feature has finished

Configuration

The feature uses the following profile table to configure IPSMGWSCCPWhitelist.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:IPSMGWSCCPWhitelist:AddressList

${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable

Sentinel Address List entry table

${SELECTIONKEY}:IPSMGWSCCPWhitelist:AddressList:${ADDRESS}

Provisioning interfaces

The feature is provisioned using the Sentinel Sentinel Core REST API.

Mobile Originated Features

These features relate to the SMS Submission path from the UE to the network.

Feature What it does

submits an SMS Over IP request to the SMSC.

updates the Orig-Address of outbound MAP MT-ForwardSM requests to allow CAP charging of the session.

sends an SMS Submit Report to an SMS over IP capable UE

MO Submission

This feature submits an SMS Over IP request to the SMSC.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWMOSubmission

No

MOFSM

Stateless with FSM encoded into session state

POJO

Statistics

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

Name Description
OpenRequestSent

Incremented when OpenRequest is sent to SMSC

FailedToSendOpenRequest

Incremented when the feature fails to send OpenRequest to SMSC

ForwardSMSent

Incremented when a MO ForwardSMReq is sent to SMSC

ForwardSMSuccessResponse

Incremented when the feature gets the MO ForwardSMResp from SMSC

Configuration

The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is IPSMGWSharedConfigProfileTable.

The following attributes are available

Attributes Type Meaning
HlrAddress

String

Address of the HLR to request the MSRN from, used when establishing the MAP dialog

TemplateSmscAddress

String

Contains a Template SMSC SCCP Address, where the digits are replaced by the received SMSC address

SentinelOriginatingAddress

String

Address of Sentinel used when establishing the MAP dialog

SentinelIPSMGWAddress

String

The IP-SM-GW address that the feature will include it in MAP AnyTimeModification request to send to HLR

InvokeTimeout

int

The timeout in milliseconds for the response from HLR. Used in the TCAP layer for the invoke timeout. Default is 5000

SmsContentSizeThreshold

int

The maximum number of octets that a SMS message is allowed to contain to send the message as part of the TC_BEGIN as described below

ChargingOptions

String[]

If this array contains the value IEC_MO_PS, charging is enabled for MO submission flows.

MAP Application Context

The feature uses MAP Application Context shortMsgMO_RelayContext_v2_ac. This application context was added in GSM MAP Phase 2.

Behaviour

The feature is triggered upon receipt of a SIP Message request.

The feature first checks that the SIP Message request’s Content-Type header is "application/vnd.3gpp.sms". If not, the feature finishes execution.

If the SIP Message request has a Content-Type header of "application/vnd.3gpp.sms" the feature extracts the body and parses it into an RP Message of the appropriate type. If the RP Message can be parsed, the feature extracts the SMSC address from the parsed RP Message. The feature then extracts the SMSC Address from the parsed RP Message. The further behaviour of the feature depends on whether online charging is enabled or not. If online charging is not enabled the feature immediately sends a 202 Accepted response to the SIP Message request, otherwise it will only send it after a successful online charging response.

sms-submission-initial

Once the SMS has been accepted, the feature passes the SMS into the SMSC. This is through the use of the MAP MO Forward SM operation, on the shortMsgMO_RelayContext_v2_ac MAP Application Context.

A general overview of the feature behaviour is depicted in the diagram below.

sms-submission-overview

Submitting the SMS to the SMSC

There are two different flows where the feature can submit the SMS. Note both of these flows assume that the 202 response above has been sent.

The first is for an SMS that is sufficiently small according to the configured SmsContentSizeThreshold attribute to fit both the MAP_OPEN request and content of the MAP_MO_FORWARD_SHORT_MESSAGE request in a single TCAP Message.

sms-submission-smallsms

The second is for an SMS that is too large to fit both the MAP_OPEN request and content of the MAP_MO_FORWARD_SHORT_MESSAGE request in a single TCAP Message.

sms-submission-largesms

MO Submission Location

This feature updates the Orig-Address of outbound MAP MT-ForwardSM requests to allow CAP charging of the session.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWMOSubmissionLocation

No

MOFSM

Stateless

POJO

Prerequisite features

This feature must run after:

Session state inputs and outputs

Inputs

Name Type Purpose

PaniMccsMncs

List<com.opencloud.sentinel.common.MccMnc>

A list of MCC and MNC data for the session. The PaniMccsMncs field is normally set by IPSMGW Extract Network Info.

IsoCountryCode

String

The ISO Country Code for the session. The IsoCountryCode field is normally set by IPSMGW Extract Network Info.

Statistics

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

Name Description
UseGeneratedGTAsOutgoingOriginatingAddress

Incremented when a GT is successfully generated from the IsoCountryCode

UseUnknownGTAsOutgoingOriginatingAddress

Incremented when a GT can not be generated from the IsoCountryCode

Configuration

The feature is configured with configuration scoped according to a Sentinel Selection Key. The MOSubmissionLocation feature refers to two tables for configuration. The Profile Table is used to hold feature configuration is MOSubmissionLocationProfileTable.

The following attributes are available

Attributes Type Meaning
UseGeneratedGTAsOriginatingAddress

Boolean

Modify the OrigAddress of the outbound MTForwardSM request

The second Profile Table CapChargingProfileTable holds CAP Charging specific configuration. The following attributes are used:

Attributes Type Meaning
ChargingGTFormatString

String

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.

UnknownChargingGT

String

The Charging GT to use when one could not be generated because the user’s location could not be determined

Behaviour

The feature retrieves the TCAP leg IPSMGWMOSubmission created by the MO Submission feature. If the leg is available the feature attempts to generate a Charging GT using the ChargingGTFormatString and sets the OrigAddress of the outboud TCAP message with the generated value. If this fails, the feature uses the UnknownLocationChargingGT for the OrigAddress.

Generating Charging GTs

The feature uses the CAP Charging Component to generate Charging GTs based on location data.

Provisioning interfaces

The feature is provisioned using the Sentinel IP-SM-GW feature REST API.

MO Submit Report

This feature sends an SMS Submit Report to an SMS over IP capable UE

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWMOSubmitReport

Yes

MOFSM

Stateless

POJO

Statistics

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

Name Description
ErrorSendingMessage

Incremented when the feature fails to send SIP MESSAGE containing smsSubmitReport

SentAck

Incremented when the feature sends one RP-ACK in the SIP MESSAGE

SentError

Incremented when the feature sends one RP-ERROR in the SIP MESSAGE

ReceivedOk

Incremented when the feature receives the successful response for the MESSAGE request

ReceivedError

Incremented when the feature receives non-successful response for the MESSAGE request

Configuration

The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is Shared Configuration Profile. The following attributes are used:

Attributes Type Meaning
ICSCFURI

String

The I-CSCF SIP URI that will be used to route outbound SIP MESSAGE requests (see SIP Transports and Routing)

Behaviour

The feature is triggered after the MO Submission feature has finished.

The feature checks session state to determine the outcome of MO Submission to the SMSC.

In the case that MO Submission was successful it formulates a SIP Message request containing an RP-ACK towards the initiating UE. In the case that there were parsing or other issues in MO Submission it formulates a SIP Message request containing an RP-ERROR towards the initiating UE (SM-over-IP sender).

The details of these requests are as follows.

Generic header setting

Regardless of whether or not the Submit Report towards the UE (SM-over-IP sender) indicates a successful or failed submission attempt the following headers are set

Header Setting or manipulation

Request URI

Contains a public user identity of the SM-over-IP sender

Route header

Set to the I-CSCF URI, with the loose routing parameter added

Content-Type

set to "application/vnd.3gpp.sms"

It reads the P-Asserted-Identity, P-Preferred-Identity and From headers of the original SMS over IP Message request in order to set the Request URI of the Submit Report.

Creation of an RP-ACK Submit report

In addition to the generic header setting, an RP-ACK Submit report sets headers as follows

Header Setting or manipulation

P-Asserted-Identity

Contains the SIP URI of the IP-SM-GW

Request-Disposition

set to "fork"

Message body

Contains an RP-ACK in content transfer encoding of type "binary"

The RP Message Reference in the RP-ACK matches the Message Reference in the RP-Submit.

mosubmitreport-ack

Creation of an RP-ERROR Submit report

In addition to the generic header setting, an RP-ERROR Submit report sets the body of the SIP Message request to contain an RP-ERROR, with content transfer encoding of type "binary".

The RP Message Reference in the RP-ERROR matches the Message Reference in the RP-Submit.

The setting of the RP-ERROR’s RPCause value is as follows

Source error cause RP Error Cause value

Could not parse the SMS body from the SM-over-IP sender

PROTOCOL_ERROR

MO Forward SM resulted in TC_UserAbort

NETWORK_OUT_OF_ORDER

MO Forward SM resulted in TC_ProviderAbort

NETWORK_OUT_OF_ORDER

MO Forward SM resulted in an InvokeTimeout

NETWORK_OUT_OF_ORDER

MO Forward SM error MAPErrors.facilityNotSupported

REQUESTED_FACILITY_NOT_IMPLEMENTED

MO Forward SM error MAPErrors.systemFailure

NETWORK_OUT_OF_ORDER

MO Forward SM error MAPErrors.unexpectedDataValue

SEMANTICALLY_INCORRECT_MESSAGE

MO Forward SM error Delivery Failure with Delivery Failure Cause of memoryCapacityExceeded

MEMORY_CAPACITY_EXCEEDED

MO Forward SM error Delivery Failure with Delivery Failure Cause of equipmentProtocolError

PROTOCOL_ERROR

MO Forward SM error Delivery Failure with Delivery Failure Cause of equipmentNotSM_Equipped

REQUESTED_FACILITY_NOT_IMPLEMENTED

MO Forward SM error Delivery Failure with Delivery Failure Cause of unknownServiceCentre

UNASSIGNED_NUMBER

MO Forward SM error Delivery Failure with Delivery Failure Cause of sc_Congestion

CONGESTION

MO Forward SM error Delivery Failure with Delivery Failure Cause of invalidSME_Address

SHORT_MESSAGE_TRANSFER_REJECTED

MO Forward SM error Delivery Failure with Delivery Failure Cause of subscriberNotSC_Subscriber

UNIDENTIFIED_SUBSCRIBER

mosubmitreport-error

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentSubmitReport

boolean

N/A

True if the feature has sent a submit report - otherwise the feature will send one if appropriate

N/A

Outputs

Name Type Description

SentSubmitReport

boolean

True if a submit report was sent by the feature

Mobile Terminated Features

These features relate to the SMS Delivery path from the network to the UE.

The SMS delivery path for the IP-SM-GW includes two initiation points:

  1. receipt of Send Routing Info for SM

  2. receipt of MT Forward Short Message

For information related to the delivery policies implemented, please refer to About SMS delivery in the Administration guide.

Feature What it does

modifies the MSC address in Send Routing Info For SM responses to be the configured address of the IPSMGW. This ensures that subsequent MAP MT Forward Short Message requests are sent to the IPSMGW.

stores SMS Routing information retrieved from an HLR in Cassandra. The stored data includes additional correlation information.

retrieves Circuit Switched routing information from the Cassandra Database and stores it into session state.

reads Third Party Registration information stored in the Cassandra Database, and writes it into session state.

delivers an SMS encapsulated in SIP (SMS Over IP) to the UE

delivers a Short Message towards the MSC or SGSN, performing TCAP application context negotiation as necessary

generates a correlation IMSI when responding to a SRI request. It uses the Correlation Resource Adaptor to allocate an IMSI based on the MCC and MNC.

increments (or creates) a row in the Cassandra cluster for the current MSISDN, to be used as the RP Message Reference, writing the value into session state.

links incoming SIP delivery reports with the sentinel session that the delivery report is responding to.

Preserve Call Id Over B2BUA

The SIP B2BUA feature can be configured to preserve the Call-ID header across both legs of a B2BUA’d session. Certain MT flows require the correlation of an incoming request with an existing IP-SM-GW session. This is achieved using the In-Reply-To header of the incoming request. Depending on network configuration this may require the preservation of the Call-ID header when B2BUA’ing the MESSAGE request onwards. By default and in typical deployments, this behavior is not configured. It should only be configured if required. For more information on this configuration option read the B2BUA Feature Configuration documentation.

Adjust Routing Info Response

This feature modifies the MSC address in Send Routing Info For SM responses to be the configured address of the IPSMGW. This ensures that subsequent MAP MT Forward Short Message requests are sent to the IPSMGW.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWAdjustRoutingInfoResponse

No

SRI4SM

Stateless

POJO

Configuration

The feature is configured using the IPSMGW Service configuration. The Profile Table used to hold feature configuration is Shared Configuration Profile. The following attributes are relevant

Attributes Type Meaning
SentinelIPSMGWAddress

String

The value that the feature will use as the MSC-address in outgoing messages.

Behaviour

The feature is triggered upon receipt of a third-party response message. The message is unmodified if it is not a successful Send Routing Info For SM response. The feature handles the following application contexts: shortMsgGatewayContext_v1_ac, shortMsgGatewayContext_v2_ac, shortMsgGatewayContext_v3_ac

When processing a v1/v2 MAPSendRoutingInfoForSMRes, the feature will set the MSC address in the outgoing message to the value of the SentinelIPSMGWAddress configured in the IPSMGW service config profile. When processing a v3 MAPRoutingInfoForSM_Res, the feature will set outgoing message’s 'GPRS Supported' indicator to false and set the NetworkNodeNumber and AdditionalNumber to the value of the SentinelIPSMGWAddress.

This ensures that the MAP MT Forward Short Message is then delivered to the IPSMGW.

CS Delivery

This feature delivers a Short Message towards the MSC or SGSN, performing TCAP application context negotiation as necessary

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWCSDelivery

No

MTFSM_CS,MTFSM_CS_PS,MTFSM_PS_CS

Stateful

POJO

MAP Phases and Application Contexts

The feature can be triggered by MAP Forward Short Message on the terminating path, for MAP Phases 1, 2 and 2+. This is referred to as MT Forward Short Message or MT-FSM for short.

The MAP Phases 1, 2 and 2+ are sometimes referred to as "v1, v2 and v3" however such language is not strictly correct.

From a TCAP Application Context perspective:

  1. MAP Phase 2 defines shortMsgMT_RelayContext_v2_ac - this is sometimes referred to as "v2"

  2. MAP Phase 2+ defines shortMsgMT_RelayContext_v3_ac - this is sometimes referred to as "v3"

  3. and MAP Phase 1 does not use a TCAP Application Context. In the software this case is represented by a synthetic application context shortMsgMT_RelayContext_v1_ac. It is synthetic because it does not exist on the wire. This case is sometimes referred to as MAP "v1".

Statistics

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

Name Description
AttemptedV1Open

Incremented when the feature has sent an OpenRequestV1. This corresponds to receipt of a TCAP TC_BEGIN without an Application Context.

AttemptedV2Open

Incremented when the feature has sent an OpenRequestV2. This corresponds to a TCAP TC_BEGIN with an Application Context from MAP Phase 2.

AttemptedV3Open

Incremented when the feature has sent an OpenRequestV3. This corresponds to receipt of a TCAP TC_BEGIN with an Application Context from MAP Phase 2+.

FallbackToV1

Incremented when the feature has received an U-Abort instructing fallback to MAP Phase 1.

FallbackToV2

Incremented when the feature has received an U-Abort instructing fallback to MAP Phase 2.

SuccessfullyDeliveredV1

Incremented when the MSC responds to a v1 MTFSM with an error-less dialog close.

SuccessfullyDeliveredV2

Incremented when the MSC responds to a v2 MTFSM with an error-less dialog close.

SuccessfullyDeliveredV3

Incremented when the MSC responds to a v3 MTFSM with an error-less dialog close, optionally with an MTFSM-res.

ErrorDeliveringV1

Incremented when the MSC responds to a v1 MTFSM with an error.

ErrorDeliveringV2

Incremented when the MSC responds to a v2 MTFSM with an error, or when the MSC responds to a v2 dialog open with a refuse that does not indicate negotiation is possible.

ErrorDeliveringV3

Incremented when the MSC responds to a v3 MTFSM with an error, or when the MSC responds to a v3 dialog open with a refuse that does not indicate negotiation is possible.

FailedToSendOpen

Incremented when the feature has failed to send any version of OpenRequest.

FailedToSendMTFSM

Incremented when the MTFSM cannot be sent after the dialog has been accepted.

SentReportSMDeliveryStatus

Incremented when the feature has sent ReportSMDeliveryStatus request to HLR.

FailedToSendReportSMDeliveryStatus

Incremented when the feature has failed to generate ReportSMDeliveryStatus request

ReportSMSucceeded

Incremented when the HLR responds to a ReportSMDeliveryStatus request with an error-less dialog close.

ReportSMFailed

Incremented when the HLR responds to a ReportSMDeliveryStatus request with an error.

SystemError

Incremented when the feature sends a generated SystemError as a response to the SMSC.

Configuration

The feature is configured with configuration scoped according to a Sentinel Selection Key. Two Profile Tables are used for configuration. The first profile Table used to hold feature configuration is Shared Configuration Profile. The following attributes are used:

Attributes Type Meaning
SentinelOriginatingAddress

String

The OriginatingAddress used to represent Sentinel when sending the forwardSM on to the destination MSC

InvokeTimeout

Long

Timeout in ms when invoking MAP operations, for example 5000ms.

DeliveryOrder

Enum

If PS Delivery will run after CS Delivery, there is no need to send error report to SMSC on CS delivery failure

UseMsisdnAsHlrAddress

Boolean

Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured HlrAddress

TemplateSmscAddress

String

Contains a Template SMSC SCCP Address, where the digits are replaced by the received SMSC address

The second Profile Table used to hold feature configuration is IPSMGWCSDeliveryConfigProfileTable. The following attributes are used:

Attributes Type Meaning
DeliveryFallbackAvoidanceCodes

int[]

A list of error codes that if matched from the SM-DeliveryFailure will stop a PS fallback

Behaviour

This feature is responsible for Circuit Switched delivery of a Short Message.

CS delivery is triggered in two ways:

  1. Upon receipt of a ForwardSM message from the SMSC if a CS_ONLY or CS_THEN_PS DeliveryOrder is specified in Shared Configuration Profile

  2. A failed PS Delivery attempt where DeliveryOrder is PS_THEN_CS

After validating configuration and session state inputs, the CS Delivery feature takes the received ForwardSM (regardless of whether or not PS Delivery was attempted) and begins the TCAP Application Context Negotiation Flows.

ForwardSM

The feature uses the negotiated dialog for delivery of the ForwardSM, as described below:

CS_ONLY or PS_THEN_CS

When the DeliveryOrder specified in Shared Configuration Profile is CS_ONLY or PS_THEN_CS, for a ForwardSM sent to MSC:

If Then

Charging is performed and returns a failure

Error returned to SMSC in MT-FSM response

Context negotiation fails

System Error or OpenRefuse sent to SMSC

MSC replies with Success

ForwardSM Success sent to SMSC

MSC replies with Error

ForwardSM Error sent to SMSC

If Then

The error with out of memory capacity error reason

ReportSMDeliveryStatus sent to HLR with SM-DeliveryOutcome=memoryCapacityExceeded.

The error with AbsentSubscriber(ph1) or AbsentSubscriberSM(ph2 and 3).

ReportSMDeliveryStatus sent to HLR with SM-DeliveryOutcome=absentSubscriber, and copy across the absentSubscriberDiagnostic (if present) and additionalAbsentSubscriberDiagnostic(if present) into the ReportSMDeliveryStatus

Other errors for CS_ONLY delivery

Do not send ReportSMDeliveryStatus to HLR

Other errors for PS_THEN_CS delivery

ReportSMDeliveryStatus sent to HLR with SM-DeliveryOutcome=absentSubscriber

CS_THEN_PS

When the DeliveryOrder specified in Shared Configuration Profile is CS_THEN_PS, for a ForwardSM sent to MSC:

If Then

Charging is performed and returns a failure

Error returned to SMSC in MT-FSM response

Context negotiation fails

PS-Delivery is initiated

MSC replies with Success

ForwardSM Success sent to SMSC

MSC replies with Error other than a SM-DeliveryFailure

PS-Delivery is initiated

if then

The error is AbsentSubscriber(ph1) or AbsentSubscriberSM(ph2 and 3)

ReportSMDeliveryStatus created with SM-DeliveryOutcome=absentSubscriber

Other errors

Do not send ReportSMDeliveryStatus to HLR.

MSC replies with a SM-DeliveryFailure

If Then

The Delivery Failure Case matches a configured DeliveryFallbackAvoidanceCodes

ForwardSM Failure sent to SMSC, ReportSMDeliveryStatus with SM-DeliveryOutcome=memoryCapacityExceeded sent to HLR only when failure with out of memory capacity error reason.

The Delivery Failure Case does not match a configured DeliveryFallbackAvoidanceCodes

PS-Delivery is initiated, ReportSMDeliveryStatus logic will refer to PS-Only Delivery.

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

MSISDN

String

The MSISDN to use in the ReportSMDeliveryStatus operation, and to use for GT routing if configured

Unable to send ReportSMDeliveryStatus messages, and to route on GT if configured

SRI4SMResAppContext

String

One of the following values shortMsgGatewayContext_v1_ac, shortMsgGatewayContext_v2_ac, shortMsgGatewayContext_v3_ac

This identifies the version of the saved SRI4SM to extract the MSC address from.

NoRoutingInfoException: "Unable to fetch SRI from session state"

SRI4SMResV1

MAPSendRoutingInfoForSMRes

The full SRI4SMResV1 message

Used to extract the MSC address from

NoRoutingInfoException: "Unable to fetch SRI from session state"

SRI4SMResV2

MAPSendRoutingInfoForSMRes

The full SRI4SMResV2 message

Used to extract the MSC address from

NoRoutingInfoException: "Unable to fetch SRI from session state"

SRI4SMResV3

MAPRoutingInfoForSM_Res

The full SRI4SMResV3 message

Used to extract the MSC address from

NoRoutingInfoException: "Unable to fetch SRI from session state"

MTFSMDeliveryOrder

com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder

One of CS_ONLY, PS_ONLY, CS_THEN_PS, PS_THEN_CS

Current DeliveryOrder based on configuration and available routing info, correpsonding to current selection key plan Id.

Schedule MTFSM error response assuming that PS Delivery will not be attempted

Note Only one of SRI4SMResV1, SRI4SMResV2, or SRI4SMResV3 will ever have any data in it.

Outputs

Name Type Description

CSDeliveryAttempted

boolean

True if an OpenRequest was sent out in a delivery attempt

CSDeliveryFailed

boolean

True if the feature failed to do a successful delivery for any reason

FallbackAllowed

boolean

True if no SM-DeliveryFailure was received, or if the error cause in the SMDeliveryFailure was not a configured 'DeliveryFallbackAvoidanceCodes' value

SM Delivery Failure Cause Mappings

These are the SM-EnumeratedDeliveryFailureCause values that may used in the feature’s DeliveryFallbackAvoidanceCodes configuration. Other values may be configured but are unlikely to appear in a SM-DeliveryFailure message.

Cause Value

memoryCapacityExceeded

0

equipmentProtocolError

1

equipmentNotSM_Equipped

2

unknownServiceCentre

3

sc_Congestion

4

invalidSME_Address

5

subscriberNotSC_Subscriber

6

Delivery Report Handover

This feature links incoming SIP delivery reports with the sentinel session that the delivery report is responding to.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWDeliveryReportHandover

No

MTFSM_DR

Stateless

SBB

Prerequisite features

Session input and output variables

Session input variables

None

Session output variables

None

Statistics

IPSMGWGenerateMessageReference statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → IPSMGW Delivery Report Handover Feature SBB
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=2.9.0].SbbID[name=ipsmgw-delivery-report-handover-feature,vendor=OpenCloud,version=2.9.0]"

Statistic Incremented when…​
ACNameBindingError

The incoming delivery report was not matched against an existing ApplicationContextInterface

ACNameBindingFound

The incoming delivery report was successfully matched against an existing ApplicationContextInterface

Configuration

The feature has no configuration.

Behaviour

The Delivery Report Handover feature is run as part of the PS delivery leg in the MT SMS flow. The PS Delivery feature will send an SMS over IP message. The call id of this message will be used to store the activity context of the session, using the Activity Context naming facility. On receipt of the message, the endpoint will generate a delivery report (with a message-type-indicator of RP_ACK or RP_ERROR) to indicate success or failure of the MT message. This delivery report message will be classified by the Determine Is SMS Over IP feature, and will trigger the Delivery Report Handover feature.

When the Delivery Report Handover feature is triggered on an incoming SIP Delivery Report, the feature extracts the value of the 'InReplyTo' header from the incoming SIP MESSAGE and searches for Application Contexts registered against that value in the ACI Naming Facility.

  • If a match is found, the triggering message is handed over to the original session - the PS delivery feature will be triggered in the original session, and it will process the Delivery Report. The session in which the Delivery Report Handover feature is running will be ended.

  • If no match is found, the session is ended with a 404.

Fetch Routing Info Cassandra

This feature retrieves Circuit Switched routing information from the Cassandra Database and stores it into session state.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWFetchRoutingInfoCassandra

Yes

MTFSM_PS,MTFSM_CS,MTFSM_PS_CS,MTFSM_CS_PS

Stateless

POJO

Session Input variables

The feature reads the following fields in Session State

Session State variable name Variable type Comments
MTFSMDeliveryOrder

com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder

One of CS_ONLY, PS_ONLY, CS_THEN_PS, PS_THEN_CS Current DeliveryOrder based on configuration and available routing info, correpsonding to current selection key plan Id. Set PSDeliveryStatus to FAILED and report featureHasFinished

Session output variables

The IPSMGWFetchRoutingInfoCassandra feature populates the following fields in the Session State

Session State variable name Variable type Comments
MSISDN

String

The MSISDN

IMSI

String

The MT Correlation ID/IMSI used as the key for the row

SRI4SMArgV1

MAPSendRoutingInfoForSMArg

The encoded java object representing v1 SRI4SM arg, if the application context was v1

SRI4SMArgV2

MAPSendRoutingInfoForSMArg

The encoded java object representing v2 SRI4SM arg, if the application context was v2

SRI4SMArgV3

MAPRoutingInfoForSM_Arg

The encoded java object representing v3 SRI4SM arg, if the application context was v3

SRI4SMResV1

MAPSendRoutingInfoForSMRes

The encoded java object representing v1 SRI4SM result, if the application context was v1

SRI4SMResV2

MAPSendRoutingInfoForSMRes

The encoded java object representing v2 SRI4SM result, if the application context was v2

SRI4SMResV3

MAPRoutingInfoForSM_Res

The encoded java object representing v3 SRI4SM result, if the application context was v3

SRI4SMResAppContext

String

A string of the application context name

CorrelatedMTFSM

boolean

Set to true if the lookup from Cassandra returned a matching row.

MTFSMDeliveryOrder

DeliveryOrder

Set to PS_ONLY when no CS routing info was present in cassandra row

SentinelSelectionKey

SentinelSelectionKey

Plan Id field will be set to MTFSM_PS when no CS routing info was present in cassandra row

Statistics

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

Name Description
FetchRoutingInfoSuccess

Incremented when a matching record is returned from Cassandra

FetchRoutingInfoFailure

Incremented when a matching record is not returned from Cassandra

Configuration

The feature uses the IPSMGWRoutingInfoCassandraConfigProfileTable profile to configure whether tracing is enabled for Cassandra queries.

Behaviour

The feature is triggered on MAP MT Forward Short Message (MT-FSM) requests. The IMSI in the MT-FSM is used as the 'mtcorrelationid' primary key field when querying Cassandra. The contents of the query result are written into session state, and used to facilitate delivery of the SMS.

If a row is not found, an UnidentifiedSubscriber error is returned to the SMSC and the feature ends.

If a row is found, the Store Routing Info Cassandra feature has written all available CS routing data to Cassandra using the schema detailed here.

If the row includes circuit switched routing information for SMS (i.e. the SRI request and response), the feature ends. If the row does not include CS routing info or the any of the CS routing info fields such as the arg or the res could not be decoded, but PS is one of the options in the current MTFSMDeliveryOrder session state field, the plan Id in the selection key is set to MTFSM_PS and the MTFSMDeliveryOrder is set to PS_ONLY - otherwise an unidentifiedSubscriber error is sent in response to the MT-FSM.

Generate MT Correlation Id

This feature generates a correlation IMSI when responding to a SRI request. It uses the Correlation Resource Adaptor to allocate an IMSI based on the MCC and MNC.

The generated correlation IMSI is saved in session state and saved in the cassandra database by Store Routing Info Cassandra feature for further inspection when delivering a Short Message.

For quick overview see Flows for SMS delivery.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWGenerateMTCorrelationId

Yes

SRI4SM

Stateless

POJO

Behaviour

The feature is triggered by a SRI_SM response (Version 1, 2 or 3) from the HLR. In the successful case, it extracts the MCC and MNC from the IMSI in the SRI_SM response. Once the MNC and MCC are extracted, the feature requests a correlation IMSI from the Correlation Resource Adaptor, providing in the MNC and MCC. If the SRI_SM failed, it uses the MCC and MNC configured in the SipSentinelConfigurationTable. If the Correlation RA allocates an IMSI successfully, the feature checks if the correlation IMSI is already in use by querying the Cassandra database. If the correlation IMSI is not in use, the feature stores the correlation IMSI into Session State and finishes execution. If the correlation IMSI is in use, the feature requests another correlation IMSI from the Correlation RA. The process is retried up to MaxGenerationAttempts number of times.

An SMSC may use a correlation IMSI for some period of time after the SRI-SM transaction completes. However the correlation IMSI will be returned to the pool after a configured time period. Therefore the "in-use" check is performed by this feature. See Store Routing Info Cassandra to understand when the correlation IMSI is erased from the database.

Configuration

The feature uses the IPSMGWGenerateMTCorrelationIdConfigProfileTable and the SIP Sentinel Configuration for its configuration.

IPSMGWGenerateMTCorrelationIdConfigProfileTable

Profile field Variable type Description

ThreeDigitMNC

Boolean

Indicates how many digits of the original IMSI is used to generate the correlation IMSI. Normally 5 or 6. MCC is always 3 digits, MNC can be 2 or 3.

MaxGenerationAttempts

int

Number of attempts to generate the correlation IMSI

CassandraTracing

Boolean

If True enables the cassandra tracing.

The correlation IMSI pool configuration is described on the Configuring a Correlation RA entity page.

Session input and output variables

Session input variables

There are no session input variables used by the feature. All inputs are from the feature configuration and the SRI-SM response.

Session output variables

Session State variable name Variable type Comments

MTCorrelatedId

String

The correlation IMSI

Statistics

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

Statistic Incremented when…​
FoundIMSI

could retrieve the IMSI from the SRI-SM response message

FoundMtCorrelationId

could generate a correlation IMSI from correlation RA

MtCorrelationIdInUse

the generated IMSI is already in use

MtCorrelationIdValid

the generated IMSI is available (not in use) and set in session state

ErrorGeneratingMtCorrelationId

fatal exception is raised

Retries

the number of attempts required to allocate a non in-use correlation IMSI, values greater than 1 a retry was needed

Generate Message Reference

This feature increments (or creates) a row in the Cassandra cluster for the current MSISDN, to be used as the RP Message Reference, writing the value into session state.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWGenerateMessageReference

No

MTFSM

Stateless

POJO

Prerequisite features

This feature must run after Fetch Routing Info Cassandra.

Session input and output variables

Session input variables

Session State variable name Variable type

MSISDN

String

Session output variables

Session State variable name Variable type Comments

MessageReference

int

The int to use for the next outgoing RpDATA - from 0 to 255

FailedToGenerateMessageReference

boolean

The flag set to true whenever the feature fails to generate a message reference

Configuration

The feature reads configuration from the Profile Table named IPSMGWGenerateMessageReferenceConfigProfileTable. The profile name is scoped according to Sentinel Selection Key.

Attributes Type Meaning
ConsistencyLevel

String

Cassandra consistency to be applied to the queries. Valid values are LOCAL_QUORUM (default), or QUORUM

QueryTimeoutSeconds

int

The number of seconds to wait for a response from Cassandra (default 10)

MaxRetries

int

The number of retries due to Compare and Set failure. Default 3

MinRetryDelayMillis

int

The minimum number of milliseconds between retries due to Compare and Set failure. Default 50, minimum of zero.

MaxRetryDelayMillis

int

The maximum number of milliseconds between retries due to Compare and Set failure. Default 250.

Behaviour

The feature queries the Cassandra Database using a Primary Key of the MSISDN of the Served User and the schema detailed here. The resulting value is stored into the MessageReference session state variables for use by other features.

As multiple SMS may be delivered to the same MSISDN simultaneously, the feature uses an atomic Compare and Set (CAS) statement when creating/incrementing the message reference. The use of CAS is governed by a retry loop, so that a single failure to create/increment the message reference does not cause the message delivery to fail (as when simultaneous CAS operations execute, one operation succeeds and the others fail). The MaxRetries, MinRetryDelayMillis, and MaxRetryDelayMillis ensure that the loop is bounded in number of iterations, and is able to be tuned as desired. When a CAS operation fails, a random delay (between MinRetryDelayMillis and MaxRetryDelayMillis) occurs before the executing thread will attempt another CAS operation. A value of zero for MinRetryDelayMillis means that the thread will immediately attempt the next CAS operation.

The feature has Configuration controls around the Compare and Set loop.

If the feature fails to generate the message reference for any reason, it resumes the SMSC leg and sends back an error response, while flagging the failure in session state.

Statistics

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

Statistic Incremented when…​
FailedToExecuteCassandraStatement

A cassandra query could not be executed successfully - could be caused by the RA or the Database - turn on finer tracing for details

InsertFailed

This is not a cassandra exception as in the case of FailedToExecuteCassandraStatement - instead it implies that the insert was not applied, probably due to the row already existing

UpdateFailed

This implies that the UPDATE failed, either due to the CAS condition failing (ie the existing value was not as expected, implying that another session had already updated the field, or the row having already been removed since the last read)

RetriesExhausted

The configured number of compare and set retries has been reached without successfully setting the message reference counter in cassandra

Retries

The number of compare and set re-attempts

NoRowsReturned

Even after successfully incrementing the counter, no value could be retrieved - this could only occur if the Database was modified

Success

The message reference counter was successfully incremented and retrieved from Cassandra

PS Delivery

This feature delivers an SMS encapsulated in SIP (SMS Over IP) to the UE

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWPSDelivery

Yes

MTFSM_PS,MTFSM_PS_CS,MTFSM_CS_PS

Stateless

POJO

Statistics

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

Name Description
SentMessage

Incremented when a SIP MESSAGE containig RP-Message is sent to the UE

DeliverySucceeded

Incremented when a delivery report indicating success is received

DeliveryFailed

Incremented when any 3xx or greater response is received for the SIP MESSAGE or when a delivery report indicating failure is received

DeliveryTimedOut

Incremented when the timer that is armed on sending the SIP MESSAGE gets fired

NotAttemptedCreditLimitReached

Incremented when a CreditLimitReached Direct Debit CCA is received. The PS Delivery attempt is aborted, with an Sm-DeliveryFailure sent back to the SMSC

NotAttemptedChargingFailure

Incremented when a general charging error occurs. The PS Delivery attempt is aborted, with an Sm-DeliveryFailure sent back to the SMSC

SubscriptionFailed

Incremented when an attempt to subscribe to UEReachabilityForIP notifications fails

SentReportSMDeliveryStatus

Incremented when a ReportSMDeliveryStatus message is sent to the UE

FailedToSendReportSMDeliveryStatus

Incremented when there was an error trying to send a ReportSMDeliveryStatus message

ReportSMSucceeded

Incremented when a ReportSMDeliveryStatus success response is received

ReportSMFailed

Incremented when a ReportSMDeliveryStatus error response is received

Configuration

The IPSMGWPSDelivery feature configuration is scoped according to a Sentinel Selection Key. The IPSMGWPSDelivery feature refers to three Profile Tables for configuration.

The first Profile Table is Shared Configuration Profile. The following attributes are used:

Attributes Type Meaning
ICSCFURI

String

The I-CSCF SIP URI that will be used to route outbound SIP MESSAGE requests (see SIP Transports and Routing)

SipTransport

String

The SIP transport for the IPSMGW’s own SIP URI, used in the From and P-Asserted-Identity headers of outbound requests (see SIP Transports and Routing)

SubscribeToUEReachabilityForIP

Boolean

If true, request UEReachabilityForIP notifications from the HSS on certain PS Delivery failures.

DeliveryOrder

Enum

If CS Delivery will run after PS Delivery, there is no need to send error report to SMSC on PS delivery failure

UseMsisdnAsHlrAddress

Boolean

Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured HlrAddress.

ChargingOptions

String[]

If this array contains the value IEC_MT_PS, charging is enabled for PS delivery

The second Profile Table is IPSMGWPSDeliveryConfigProfileTable. The following attributes are used:

Attributes Type Meaning
FallbackTimer

int

Time in milliseconds to wait for a response during PS Delivery before setting 'PSDeliveryStatus' to FAILED

RPErrorFallbackAvoidanceCodes

int[]

A list of error codes that if matched from the RP-ERROR will stop a CS fallback

The third Profile Table (IPSMGWPSDeliveryPerNodeURIConfigTable) holds node-specific feature configuration. The following attributes are used:

Attributes Type Meaning
NodeURI

String

The SIP Local URI for this node to use when sending the MESSAGE

MAP Application Contexts

The feature can be triggered by any of the following MAP Application Contexts: shortMsgMT_RelayContext_v3_ac shortMsgMT_RelayContext_v2_ac shortMsgMT_RelayContext_v1_ac

Behaviour

The feature is triggered upon receipt of a mt_ForwardSM in any of the above three MAP Application Contexts.

After validating configuration and session state inputs, it then takes the ForwardSM argument and creates an RpDATA that it can send in a SIP MESSAGE to the ICSCF

The SIP MESSAGE is created as follows:

3GPP TS 24.341 V12.6.0 (2014-12) section 5.3.3.4.2 Delivering a short message in a SIP MESSAGE request
If a short message is received from the SMS-GMSC, the IP-SM-GW shall extract the IMSI of the SM-over-IP receiver from the received message. Then the IP-SM-GW shall send a SIP MESSAGE request with the following information:
a)  the Request-URI, which shall contain a public user identity of the SM-over-IP receiver associated with the received IMSI;
b)  the Accept-Contact header, which shall contain a "+g.3gpp.smsip" parameter and the "explicit" and "require" tags according to RFC 3841 [17];
c)  the Request-Disposition header which shall contain the "no-fork" directive;
d)  the P-Asserted-Identity header which shall contain the SIP URI of the IP-SM-GW;
e)  the Content-Type header which shall contain "application/vnd.3gpp.sms"; and
f)  the body of the request which shall contain an RP-DATA message as defined in 3GPP TS 24.011 [8], including the SMS headers and the SMS user information encoded as specified in 3GPP TS 23.040 [3].

For example flows, see MT Delivery Flows

The IPSMGWPSDelivery feature arms a service timer (with the value of FallbackTimer attribute in the IPSMGWPSDeliveryConfigProfileTable) when it sends the SIP MESSAGE. If this timer expires, then PS Delivery has taken too long and the PSDeliveryStatus session state field is set to FAILED (default is NOT_ATTEMPTED.)

The following tables explains the behaviour during MT PS delivery.

PS_ONLY or CS_THEN_PS

This section describes the behaviour when the DeliveryOrder attribute in the Shared Configuration Profile is set to PS_ONLY or CS_THEN_PS.

For a PS delivery:

If Then

Charging is performed and returns a failure

Error returned to SMSC in MT-FSM response

Response received from UE is a 408 or 410, or no response received from UE before the FallBackTimer expires

Error returned to SMSC in MT-FSM response, IP-SM-GW subscribes to receive UEReachabilityForIP notifications using stored MSISDN, IP-SM-GW sends a MAP Report SM Delivery Status to the HLR

Response received from UE is other code that is not a 2xx (e.g. not 202 or 200)

Error returned to SMSC in MT-FSM response

Response received from UE is a 2xx

If Then

Delivery Report does not arrive before the FallBackTimer expires

Error returned to SMSC in MT-FSM response, IP-SM-GW subscribes to receive UEReachabilityForIP notifications using stored MSISDN, IP-SM-GW sends a MAP Report SM Delivery Status to the HLR

Delivery Report does not contain RP Data

Error returned to SMSC in MT-FSM response

Delivery report contains an RP ERROR with "memory out of capacity"

Error returned to SMSC in MT-FSM response, IP-SM-GW sends a MAP Report SM Delivery Status to the HLR

Delivery report contains an RP ERROR with other error

Error returned to SMSC in MT-FSM response

Delivery report contains an RP ACK

Success returned to SMSC in MT-FSM response, IP-SM-GW sends a MAP Report SM Delivery Status to the HLR

PS_THEN_CS

This section describes the behaviour when the DeliveryOrder attribute in the Shared Configuration Profile is set to PS_THEN_CS. In this mode, PS Delivery may not necessarily respond to the SMSC itself, instead falling back to CS Delivery.

For a PS delivery:

If Then

Charging is performed and returns a failure

Error returned to SMSC in MT-FSM response

No Response received from UE before the FallBackTimer expires

CS Fallback initiated, IP-SM-GW subscribes to receive a UEReachabilityForIP notification using the stored MSISDN

Response received from UE is not a 2xx (e.g. not 202 or 200)

CS Fallback initiated, IP-SM-GW may subscribe to receive a UEReachabilityForIP notification using the stored MSISDN

Response received from UE is a 2xx

If Then

Delivery Report does not arrive before the FallBackTimer expires

CS Fallback initiated, the feature may subscribe to receive UEReachabilityForIP notifications using stored MSISDN

Delivery Report does not contain RP Data

CS Fallback initiated

Delivery report contains an RP ERROR

If Then

No RPErrorFallbackAvoidanceCodes configured

CS Fallback initiated

RP-Error code does not match any entry in RPErrorFallbackAvoidanceCodes

CS Fallback initiated

RP-Error code matches an entry in RPErrorFallbackAvoidanceCodes

Error returned to SMSC in MT-FSM response

Delivery report contains an RP ACK

Success returned to SMSC in MT-FSM response, IP-SM-GW sends a MAP Report SM Delivery Status to the HLR

Requesting a UE Reachability for IP Notification

This feature may request a UE Reachability for IP Notification from the HSS, using Diameter Sh’s SubscribeNotificationRequest operation (through the Sh Cache Microservice). This operation is only sent to the HSS if the SubscribeToUEReachabilityForIP configuration flag is set to true and one of the following occurs:

  • the SIP Message Request sent towards the UE is responded to with a 408 (Request Timeout) or 410 (Gone) error response, or

  • an RP-ACK or RP-ERROR is not received from the UE within a guard time period

The guard time value is the FallBackTimer. The Sh SubscribeNotificationRequest operation is sent with the MSISDN as the access key, and the One Time Notification flag set.

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

MSISDN

String

The MSISDN to use in the subscription-notification and ReportSMDeliveryStatus operations, and to use for GT routing if configured

Unable to send subscription-notification and ReportSMDeliveryStatus messages, and to route on GT if configured

IsSMSOverIPRegistered

boolean

N/A

True if the user is logged in to the IMS - feature only runs if logged in

MTFSMDeliveryOrder

com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder

One of CS_ONLY, PS_ONLY, CS_THEN_PS, PS_THEN_CS

Current DeliveryOrder based on configuration and available routing info, correpsonding to current selection key plan Id.

Set PSDeliveryStatus to FAILED and report featureHasFinished

RegistrationRecords

List of com.opencloud.sentinel.state.RegistrationRecord

RegistrationRecords for the user - the default public ID is extracted from the first record and used as the RequestURI

Report featureCannotStart, featureHasFinished

SRI4SMArgV1, SRI4SMArgV2, SRI4SMArgV3

com.opencloud.slee.resources .cgin.map.MAPSendRoutingInfoForSMArg, com.opencloud.slee.resources .cgin.map.MAPRoutingInfoForSM_Arg

The SendRoutingInfoForSM Arg received from the SMSC, used to populate the service centre address in a Report SM Delivery Status

Use the IP-SM-GW address as the service centre address

Outputs

Name Type Description

PSDeliveryStatus

Enum

Values are NOT_ATTEMPTED, FAILED, SUCCEEDED. Indicates the state of PS Delivery

FallbackAllowed

boolean

True if the RP-Data Deliver MESSAGE received a SIP error response, or no RP-Ack MESSAGE was received, or if the delivery report didn’t contain RP Data, or if an RP-Error was received and its cause code was not a configured RPErrorFallbackAvoidanceCodes value.

RP Cause Mappings

Any values not in the table are still valid as RPErrorFallbackAvoidanceCodes but it is unlikely they will appear in the RP-ERROR.

Cause Value

UNASSIGNED_NUMBER

1

OPERATOR_DETERMINED_BARRING

8

CALL_BARRED

10

RESERVED

11

SHORT_MESSAGE_TRANSFER_REJECTED

21

MEMORY_CAPACITY_EXCEEDED

22

DESTINATION_OUT_OF_ORDER

27

UNIDENTIFIED_SUBSCRIBER

28

FACILITY_REJECTED

29

UNKNOWN_SUBSCRIBER

30

NETWORK_OUT_OF_ORDER

38

TEMPORARY_FAILURE

41

CONGESTION

42

RESOURCES_UNAVAILABLE

47

REQUESTED_FACILITY_NOT_SUBSCRIBED

50

REQUESTED_FACILITY_NOT_IMPLEMENTED

69

INVALID_SHORT_MESSAGE_REFERENCE_VALUE

81

INVALID_MESSAGE

95

INVALID_MANDATORY_INFORMATION

96

MESSAGE_TYPE_NONEXISTENT_OR_NOT_IMPLEMENTED

97

MESSAGE_NOT_COMPATIBLE_WITH_SHORT_MESSAGE_PROTOCOL_STATE

98

INFORMATION_ELEMENT_NONEXISTENT_OR_NOT_IMPLEMENTED

99

PROTOCOL_ERROR

111

INTERWORKING

127

Registration Lookup From Cassandra

This feature reads Third Party Registration information stored in the Cassandra Database, and writes it into session state. Information is read during MT ForwardSM processing. It reads the Third Party Registration information via the Cassandra CQL RA. For more information refer to Cassandra Storage.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWRegistrationLookupFromCassandra

No

MTFSM_PS,MTFSM_PS_CS,MTFSM_CS_PS

Stateless

POJO

Prerequisite features

These features must run after Fetch Routing Info Cassandra.

Session input and output variables

Session input variables

Session State variable name Variable type

MSISDN

String

SentinelDestinationDomain defined in Shared Configuration Profile

String

Session output variables

Session State variable name Variable type Comments

RegistrationRecords

List<RegistrationRecord>

The list of registration records for the subscriber

IsSMSOverIPRegistered

boolean

True, if the feature found a valid record in the database and if the Contacts header contains the indication g.3gpp.smsip

Statistics

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

Statistic Incremented when…​
NoSubscriberSpecified

the MSISDN is empty

RegistrationRetrieveSuccess

Registration found in the database

RegistrationRetrieveFail

an exception occurs in cassandra

CassandraQueried

the database is queried

SubscriberNotRegistered

could not find an active subscriber in the database

SupportSMSIP

found a valid record in the database and the Contacts header contains the indication g.3gpp.smsip

SubscriberNotActive

found a valid subscriber in the database but its status is not active.

Configuration

The feature has no configuration.

Behaviour

The feature queries the Cassandra Database using a Primary Key of the IMS Public Identity of the Served User constructed from the MSISDN provided by the SRI request. It creates a TEL URI using the MSISDN, and if can’t find the subscriber in the database it creates a SIP URI using the domain specified in SentinelDestinationDomain from Shared Configuration Profile and query the database again.

User logged in

The RegistrationRecords session state field is set to a List of RegistrationRecord if the indication g.3gpp.smsip is present in the Contacts header. Each element in the list indicates a device, with public and private IDs, that the subscriber is registered on. If the subscriber is registered on only one device, there is only one element in the list. If the subscriber is simultaneously registered on (say) four devices, there will be four elements in the list.

User not logged in

If the user is not logged in, the feature finishes execution without modifying any state.

Support for SMS over IP

If, during the registration process, the subscriber indicates if supports SMS over IP, then the feature sets the field IsSMSOverIPRegistered to true. The presence of the string g.3gpp.smsip in the Contacts header indicates that the subscriber supports SMS over IP. In this case the IPSMGW will try to forward the message to the PS network.

Store Routing Info Cassandra

This feature stores SMS Routing information retrieved from an HLR in Cassandra. The stored data includes additional correlation information.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWStoreRoutingInfoCassandra

Yes

SRI4SM,MTFSM_PS,MTFSM_CS,MTFSM_CS_PS,MTFSM_PS_CS

Stateless

POJO

Parameters

This feature can operate with two parameters - 'Store' or 'Refresh'. For details, please refer to Behaviour

Session output variables

The IPSMGWStoreRoutingInfoCassandra feature populates the following fields in Session State

Session State variable name Variable type Comments
MSISDN

String

Populated when processing a SRI4SM

The feature populates reads the following fields from Session State when refreshing data

Session State variable name Variable type Comments
IMSI

String

The MT Correlation ID/IMSI used as the key for the row

SRI4SMArgV1

MAPSendRoutingInfoForSMArg

The encoded java object representing v1 SRI4SM arg, if the application context was v1

SRI4SMArgV2

MAPSendRoutingInfoForSMArg

The encoded java object representing v2 SRI4SM arg, if the application context was v2

SRI4SMArgV3

MAPRoutingInfoForSM_Arg

The encoded java object representing v3 SRI4SM arg, if the application context was v3

SRI4SMResV1

MAPSendRoutingInfoForSMRes

The encoded java object representing v1 SRI4SM result, if the application context was v1

SRI4SMResV2

MAPSendRoutingInfoForSMRes

The encoded java object representing v2 SRI4SM result, if the application context was v2

SRI4SMResV3

MAPRoutingInfoForSM_Res

The encoded java object representing v3 SRI4SM result, if the application context was v3

SRI4SMResAppContext

String

A string of the application context name

Statistics

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

Name Description
StartedStore

Incremented when the feature is triggered with a mode of 'Store'

StartedRefresh

Incremented when the feature is triggered with a mode of 'Refresh'

TriggerOpenRequest

Incremented when the feature is triggered on a DialogOpenRequestTcapMessage

TriggerTCOperation

Incremented when the feature is triggered on a TCOperationTcapMessage

TriggerTCEnd

Incremented when the feature is triggered on a TCEnd message

TriggerSipResponse

Incremented when the feature is triggered on a SIP Response

ParsingSendRoutingInfoForSMArgV1

Incremented when the feature attempts to parse a MAP v1 MAPSendRoutingInfoForSMArg

ParsingSendRoutingInfoForSMArgV2

Incremented when the feature attempts to parse a MAP v2 MAPSendRoutingInfoForSMArg

ParsingSendRoutingInfoForSMArgV3

Incremented when the feature attempts to parse a MAP v3 MAPRoutingInfoForSM_Arg

ParsingSendRoutingInfoForSMResV1

Incremented when the feature attempts to parse a MAP v1 MAPSendRoutingInfoForSMRes

ParsingSendRoutingInfoForSMResV2

Incremented when the feature attempts to parse a MAP v2 MAPSendRoutingInfoForSMRes

ParsingSendRoutingInfoForSMResV3

Incremented when the feature attempts to parse a MAP v3 MAPRoutingInfoForSM_Res

RefreshingData

Incremented when the feature refreshes data

RefreshingRefreshingDataSkippedDueErrorMessage

Incremented when the feature skips refreshing the data due to receiving an error message

DataStoreError

Incremented when data is not successfully stored to Cassandra

DataStoreSuccess

Incremented when data is successfully stored in Cassandra

Configuration

The feature uses the IPSMGWRoutingInfoCassandraConfigProfileTable profile to configure the Cassandra attribute time-to-live (TTL), and whether tracing is enabled for Cassandra queries. The following attributes are used:

Attributes Type Meaning
CassandraTTL

int

Cassandra’s time to live timer in seconds

CassandraTracing

boolean

If true enables the cassandra tracing

Behaviour

The feature stores the CS Routing Information for SMS into the Cassandra Database using the schema detailed here. This includes the SRI for SM request and response content.

It can operate in two modes - 'Store' or 'Refresh':

  1. 'Store' mode is triggered on incoming SRI for SM Requests and responses. On a request it will extract the MSISDN from the request and store it in session state. On successful SRI response it encodes the SRI response and associated request, and writes them into the Cassandra DB using the IMSI read from session state, rather than from the message itself. It is important that the IMSI is read from session state, so that a MT Correlation ID can be used, rather than the true IMSI. The true IMSI is written as part of correlation data. When the feature is triggered by an SRI for SM error result, it will write an empty row to the Cassandra DB using just the MT Correlation IMSI as primary key and the MSISDN. If the write is successful, it will replace the proxied error with a success response including the correlation IMSI. When this empty row is read by FetchRoutingInfo during MT-FSM handling, it indicates that CS delivery is not possible, but PS delivery may be an option. The row is stored with a configurable TTL, so no manual cleanup process is required.

  2. 'Refresh' mode is triggered on indication of successful delivery of an SMS message (either via SIP encapsulated SMS over IP, or via a MAP MT Forward SM ACK). The successful delivery of an SMS indicates that the routing info remains valid and should not time out, so it is refreshed in Cassandra. This ensures that a batch of SMS for the same IMSI within the Time To Live period are correlated together. The feature uses the fields stored in session state by the IPSMGWFetchRoutingInfoCassandra feature and re-stores them in Cassandra.

When storing or refreshing data in Cassandra the primary key is formatted as an IMSI, and the value of the primary key is read from Session State. If suitable primary key information is not available (for example the Generate MT Correlation Id feature was unable to allocate a correlation IMSI), or there is a failure to write the routing information into Cassandra, an error response to the SRI-SM is sent.

A related feature is the Fetch Routing Info Cassandra.

Registrar Features

These features relate to Third Party Registration

Feature What it does

sets a session state field based on the presence of the “+g.3gpp.smsip” parameter in first party SIP Register request Contact headers and the subscriber MSISDN session state field.

sends a MAP AnyTimeModification request to HLR to set the IP-SM-GW address and set active flag to true when a user registers.

ATM Registration

This feature sends a MAP AnyTimeModification request to HLR to set the IP-SM-GW address and set active flag to true when a user registers.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWATMRegistration

No

register,de_register

Stateless

SBB

Statistics

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

Name Description
Started

Incremented each time the feature runs

Failed

Incremented when a fatal error occurs during feature execution

RequestSent

Incremented when ATM request is sent to HLR

RequestSuccessful

Incremented when a ATM non-error response is received from HLR

RequestFailed

Incremented when a ATM error response is received from HLR

Configuration

The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is Shared Configuration Profile. The following attributes are available

Attributes Type Meaning
HlrAddress

String

Address of the HLR to request the MSRN from, used when establishing the MAP dialog if UseMsisdnAsHlrAddress is not configured

UseMsisdnAsHlrAddress

boolean

Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured HlrAddress

SentinelOriginatingAddress

String

Address of Sentinel used when establishing the MAP dialog

SentinelIPSMGWAddress

String

The IP-SM-GW address that the feature will include it in MAP AnyTimeModification request to send to HLR

InvokeTimeout

int

The timeout in milliseconds for the response from HLR. Used in the TCAP layer for the invoke timeout. Default is 5000

Using MSISDN as HLR Address

The ATM Registration feature can optionally address the HLR leg using a GT address formed from the inbound subscriber MSISDN, as opposed to using the destination addresses configured in the IPSMGWMapProxyConfigProfileTable profile table described above.

This behaviour can be enabled or disabled by setting the UseMsisdnAsHlrAddress attribute in the Shared Configuration Profile.

Behaviour

The feature is triggered upon Initial Registration, and De-Registration. It is not triggered on registration refresh.

On initial registration, this feature sends a MAP AnyTimeModification request to the HLR to set IP-SM-GW address and the IP-SM-GW active flag. The IP-SM-GW address is configured in a configuration profile.

sms-registration

When a user de-registers, the feature sends a MAP AnyTimeModification request to the HLR to clear the IP-SM-GW Active flag. sms-deregistration

MAP Application Context

The feature uses MAP Application Context anyTimeInfoHandlingContext_v3_ac. This application context was added in GSM MAP Rel99.

Determine SMS Registration

This feature sets a session state field based on the presence of the “+g.3gpp.smsip” parameter in first party SIP Register request Contact headers and the subscriber MSISDN session state field.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWDetermineSMSRegistration

No

Any

Stateless

POJO

Session output variables

Session State variable name Variable type Comments
isSmsip

boolean

True if the feature finds the “+g.3gpp.smsip” parameter in the contact headers.

MSISDN

String

The MSISDN retrieved from the REGISTER message.

Statistics

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

Name Description
isSmsip

Incremented when the feature has set the isSmsip Session State field to true

incrementFailedToDetermineMSISDN

Incremented if an SMS over IP session and unable to determine the subscriber MSISDN.

Configuration

The feature has no configuration.

Behaviour

This feature checks incoming SMS Register messages for the presence of the +g.3gpp.smsip parameter in the contact headers of the message. If the parameter is present, the 'isSmsip' session state field is set to true. In all other cases the field defaults to false. If is an SMS over IP session, this feature also extracts a valid phone number from the IMPUs of the incoming REGISTER request and sets the MSISDN session state field.

Values examined

Value Name Source Notes

Contact Header “+g.3gpp.smsip” Parameter

Incoming SIP request

This is a parameter on the contact header, as per 3GPP TS 24.341 section 5.3.2.2

Shared Configuration Profile

The shared configuration profile is used to make the basic configuration of Sentinel IP-SM-GW. The profile table name is IPSMGWSharedConfigProfileTable.

Parameters

The profile table is scoped according to a Sentinel Selection Key. Typically there exists one profile for the platform.

Parameter Type Description Example

ChargingOptions

String[]

Determines which kinds of charging to apply to MT and MO deliveries

Zero or more of the following options can be enabled: IEC_MT_PS
IEC_MT_CS
IEC_MO_PS

DeliveryOrder

Enum

Sets the order in which to try MT delivery - whether PS first, CS first or only one or the other

The following options are available:
CS_THEN_PS
PS_THEN_CS
PS_ONLY
CS_ONLY

HlrAddress

String

Contains the HLR SCCP Address, used for routing if UseMsisdnAsHlrAddress is not configured and as a template address in which the digits are replaced by the subscriber MSISDN if UseMsisdnAsHlrAddress is configured.

'type=C7,ri=pcssn,pc=5,ssn=6'

UseMsisdnAsHlrAddress

Boolean

Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured HlrAddress.

false

TemplateSmscAddress

String

Contains a Template SMSC SCCP Address, where the digits are replaced by the received SMSC address

'type=C7,ri=gt,digits=0,ssn=6,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0'

SentinelOriginatingAddress

String

Defines the Sentinel IP-SM-GW SCCP Address

'type=C7,ri=pcssn,pc=5,ssn=147'

SentinelIPSMGWAddress

String

Defines the Sentinel IP-SM-GW international Address

'address=653333333, nature=INTERNATIONAL, numberingPlan=ISDN'

InvokeTimeout

Long

Timeout in ms when invoking MAP operations

5000

SentinelTerminatingDomain

String

Domain defined by the operator to compose SIP URIs from the MSISDN

domain.com

ICSCFURI

String

The I-CSCF SIP URI that will be used to route outbound SIP MESSAGE requests (see SIP Transports and Routing)

sip:127.0.0.1:5052;lr;transport=tcp
sip:icscf.home1.net

SipTransport

String

The SIP transport for the IPSMGW’s own SIP URI, used in the From and P-Asserted-Identity headers of outbound requests (see SIP Transports and Routing)

"udp" or "tcp"

SmsContentSizeThreshold

String

If the length of the message content falls within the configured maximum then send the ForwardSM as part of the TC-BEGIN. As a special case a configured max size of 0 disables this functionality regardless of the actual content length.

0

SriSmDeliveryNotIntended

Boolean

If true, specify the SmDeliveryNotIntended flag when performing an SRI for SM IMSI-only query (i.e. during SMMA callflows). The FetchIMSI feature will use a v2 MAP dialog if set to false, and a v3 MAP dialog when set to true. Please read the important note on the FetchIMSI feature page.

False

SubscribeToUEReachabilityForIP

Boolean

If true, request UEReachabilityForIP notifications from the HSS on certain PS Delivery failures.

True

UseGtAsCallingParty

Boolean

When accepting an OpenRequest, the SCCP responder address in the OpenAccept will, by default, be set to the value of the SCCP called party in the OpenRequest. If UseGtAsCallingParty is set to true, and if the received sccp-called-party contains a global title, the responder address will be modified in the following way:
The Translation Type is set to 0
The Routing Indicator will be set to gt
The Point Code will be unset
The National indicator will be set to false.

This is useful when the inbound sccp-called-party has been modified by a network element to use PCSSN routing, but GT routing is required for establishing the TCAP dialog.

False

Short Message Memory Available Features

These features relate to the Short Message Memory Available Submission path from the UE to the network. This occurs when the UE indicates that it has memory available to receive short messages, having previously indicated that it did not have available memory.

Feature What it does

extracts the MSISDN from a SMMA message, then sends an RP-ACK to the SMMA request

SMMA Response

This feature extracts the MSISDN from a SMMA message, then sends an RP-ACK to the SMMA request

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

IPSMGWSMMAResonse

No

SMMA

Stateless

POJO

Feature parameters

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

Name Allowed Values Description

mode

prepare and send

This is used to determine what action the feature should take when run.

Session Input variables

The feature reads the following fields in Session State

Session State variable name Variable type Comments
SRI4SMResult

enum

Indicates if the SendRoutingInfoForSM request has succeeded. Allowed values are NOT_ATTEMPTED, SUCCESS, and FAILED

SRI4SMError

TcapError

The TcapError received in response to the SendRoutingInfoForSMRequest

ReadyForSMResult

enum

Indicates if the ReadyForSM request has succeeded. Allowed values are NOT_ATTEMPTED, SUCCESS, and FAILED

ReadyForSMError

TcapError

The TcapError received in response to the ReadyForSM

Session Output variables

The feature sets the following fields in Session State

Session State variable name Variable type Comments
MSISDN

String

The MSISDN to be used by the Fetch IMSI feature

Statistics

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

Name Description
SavedMSISDN

Incremented when the MSISDN has been extracted from the incoming SIP MESSAGE

SentRPACK

Incremented when the RP-ACK message is successfully sent to the I-CSCF

FailedToSendRPACK

Incremented when the RP-ACK message fails to be sent to the I-CSCF

SentRPError

Incremented when the RP-ERROR message is successfully sent to the I-CSCF

FailedToSendRPError

Incremented when the RP-ERROR message fails to be sent to the I-CSCF

FailedToPrepareSIPMessage

Incremented when we unable to prepare a SIP MESSAGE for the RP-ACK or RP-ERROR to be sent in

NoPAIAvailable

Incremented when the P-Asserted-Identity does not give us an ID that can be used as the MSISDN

Configuration

The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is IPSMGWSharedConfigProfileTable.

The following attributes are available

Attributes Type Meaning
ICSCFURI

String

The I-CSCF SIP URI that will be used to route outbound SIP MESSAGE requests (see SIP Transports and Routing)

Behaviour

When run with mode prepare and the trigger is a SIP MESSAGE that contains a SMMA, the feature will send a 202 response, then attempt to derive an MSISDN from the 'P-Asserted-Identity' header. The feature will also use the incoming SIP MESSAGE to prepare the responding SIP MESSAGE request that will contain either the RP-ACK or RP-ERROR. This response is prepared but not sent.

When run with mode send and the trigger is a TCAP response the feature checks the SRI4SMResult, SRI4SMError, ReadyForSMResult, and ReadyForSMError session state fields and sends the RP response based on their values.

If both SRI4SMResult and ReadyForSMResult indicate success it will send an RP-ACK. If either one of them indicates failure it will map the TCAP error to an RP-ERROR cause based on the table below:

TCAP error RP-ERROR cause

unknownSubscriber

UNKNOWN_SUBSCRIBER

callBarred

CALL_BARRED

teleserviceNotProvisioned

REQUESTED_FACILITY_NOT_SUBSCRIBED

absentSubscriber

DESTINATION_OUT_OF_ORDER

facilityNotSupported

REQUESTED_FACILITY_NOT_IMPLEMENTED

Any other value

NETWORK_OUT_OF_ORDER

The prepared SIP Message request is then sent.

If the session state fields indicate that the SendRoutingInfoForSM and/or ReadyForSM operations have not been attempted then the feature will not do anything.

USSI Features

These features relate to processing USSI requests.

Feature What it does

analyses an incoming INVITE request to determine if it is a USSI request.

handles the SIP side of the USSI conversation.

converts USSD text to/from encoded forms

generates and sends a USSD request to an HLR, and handles the result

Convert USSI Text

This feature converts USSD text to/from encoded forms

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

ConvertUssiText

No

USSI

Stateless

POJO

Feature parameters

The Convert USSI Text feature supports the following parameters that may be passed in a feature execution script run statement:

Name Allowed Values Description

mode

xmlToEncoded and encodedToXml

This is used to determine what action the feature should take when run.

Session Input variables

The feature reads the following fields in Session State

Session State variable name Variable type Comments
UssdTextAsText

String

USSD text to be encoded into a byte array

UssdTextAsBytes

byte[]

Byte array to be decoded to USSD text

Session Output variables

The feature sets the following fields in Session State

Session State variable name Variable type Comments
UssdTextAsText

String

USSD text that has been decoded from a byte array

UssdTextAsBytes

byte[]

Byte array that has been encoded from USSD text

Statistics

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

Name Description
Started

Incremented when the feature is started.

FailedToStart

Incremented when Sentinel encounters an error while attempting to start the feature.

IssuedWarning

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

FailedDuringExecution

Incremented when a fatal problem is encountered and the feature cannot execute correctly.

TimedOut

Incremented when the feature takes too long to complete and Sentinel aborts execution.

StartedXmlToEncoded

Incremented when the feature is started in the XmlToEncoded mode

StartedEncodedToXml

Incremented when the feature is started in the EncodedToXml mode

RejectWithDefaultMessage

Incremented when the feature is started in the XmlToEncode mode and the configuration states that the feature should reject with a default message

Behaviour

This feature reads one of the two session state fields and encodes or decodes it into the other session state field. The encoding is done as GSM 7-bit.

The feature will encode or decode based on the feature parameter passed to it from the feature script.

  • When started with xmlToEncoded the feature reads from UssdTextAsText and encodes it into UssdTextAsBytes if RejectAllUssiWithDefaultErrorMessage is not set. In the event that RejectAllUssiWithDefaultErrorMessage is set the feature will instead stop Ussi conversation and a static message will be generated by another feature downstream. Also the features for ussi will not contact the HLR.

  • When started with encodedToXml the feature reads from UssdTextAsBytes and decodes it into UssdTextAsText.

Determine Ussi Mode

This feature analyses an incoming INVITE request to determine if it is a USSI request.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

DetermineUssiMode

No

All INVITE Sessions

Stateless

POJO

Session Input variables

None.

Session Output variables

None.

Statistics

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

Name Description
Started

Incremented when the feature is started.

FailedToStart

Incremented when Sentinel encounters an error while attempting to start the feature.

IssuedWarning

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

FailedDuringExecution

Incremented when a fatal problem is encountered and the feature cannot execute correctly.

TimedOut

Incremented when the feature takes too long to complete and Sentinel aborts execution.

MessageNotUssiRequest

Incremented when it is determined that the incoming request is not a USSI request.

MessageIsUssiRequest

Incremented when it is determined that the incoming request is a USSI request.

Behaviour

On receiving an incoming SIP request, this feature checks the request against the following conditions:

  • The request method is INVITE.

  • The Request-URI is a SIP URI (i.e. the URI starts with sip:).

  • The Request-URI has a user parameter with the value set to dialstring.

  • The user part of the Request-URI is a valid USSD dial string according to 3GPP TS 22.090.

If all of the conditions are met, the feature will increment the MessageIsUssiRequest statistic and finish execution, allowing message processing to proceed.

If any of the conditions are not met, the feature will increment the MessageNotUssiRequest statistic, and instruct the SIP session to proxy the request without recording Sentinel on the route. The feature will then finish execution.

Handle Mobile Initiated USSD

This feature generates and sends a USSD request to an HLR, and handles the result .

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

HandleMobileInitiatedUssd

No

USSI

Stateless

POJO

Session Input variables

The feature reads the following fields in Session State

Session State variable name Variable type Comments
MSISDN

String

The MSISDN to use in the MAPProcessUnstructuredSS_Request operation

UssdLanguageDcsMapping

UssdLanguageDcsMapping

The Data Coding Scheme to use in the MAPProcessUnstructuredSS_Request operation

UssdTextAsBytes

byte []

The text to use in the MAPProcessUnstructuredSS_Request operation, in an encoding matching the data coding scheme.

Session Output variables

The feature sets the following fields in Session State

Session State variable name Variable type Comments
UssdLanguageDcsMapping

UssdLanguageDcsMapping

The Data Coding Scheme retrieved from the MAPProcessUnstructuredSS_Request ack (if successful).

UssdTextAsBytes

byte []

The text retrieved from the MAPProcessUnstructuredSS_Request ack (if successful), in an encoding matching the data coding scheme.

UssiErrorCode

int

The Ussi Error codes as defined in TS 24390-c60 (if unsuccessful).

UssdConversationComplete

boolean

Whether the conversation is complete and a BYE should be sent to the initiating party.

Statistics

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

Name Description
SendProcessUnstructuredSSRequestSucceeded

Incremented when a MAPProcessUnstructuredSS_Request is sent to the HLR

SendProcessUnstructuredSSRequestFailed

Incremented when an attempt to send a MAPProcessUnstructuredSS_Request fails

ReceiveProcessUnstructuredSSRequestAck

Incremented when the feature receives a MAPProcessUnstructuredSS_Request ack

ReceiveProcessUnstructuredSSRequestError

Incremented when the feature receives a MAP error in response to the request

ReceiveUnexpectedError

Incremented when the feature receives an error that is not specifically mapped to an error code

ReceiveUnstructuredSSNotify

Incremented when the feature receives a MAPUnstructuredSSNotify_Request from the HLR

Configuration

The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is IPSMGWSharedConfigProfileTable.

The following attributes are available

Attributes Type Meaning
HlrAddress

String

Address of the HLR to request the IMSI from, used when establishing the MAP dialog if UseMsisdnAsHlrAddress is not configured

UseMsisdnAsHlrAddress

Boolean

Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured HlrAddress

SentinelOriginatingAddress

String

Address of Sentinel used when establishing the MAP dialog

Using MSISDN as HLR Address

The Fetch IMSI feature can optionally address the HLR leg using a GT address formed from the inbound subscriber MSISDN, as opposed to using the destination addresses configured in the IPSMGWMapProxyConfigProfileTable profile table described above.

This behaviour can be enabled or disabled by setting the UseMsisdnAsHlrAddress attribute in the Shared Configuration Profile.

MAP Application Context

The feature uses MAP Application Context networkUnstructuredSsContext. This application context was added in GSM MAP Phase 2.

Behaviour

When the feature is triggered on a SIP invite, the feature will construct a MAPProcessUnstructuredSS_Request message from values in session state. The Handle USSI Invite and Convert USSI Text features are responsible for correctly setting the session state fields.

When the HLR responds to the message, or the TCAP connection times out, the feature will indicate (through session state) that a response to the A-Party should be generated. If the HLR sent a success response, the feature will retrieve the USSD text and data coding scheme from the result, and store those values in session state. If the HLR sent an error response appropriate to the operation, the feature will store the corresponding value in session state (and leave the text and DCS fields blank). If an unrecognized error occurs - eg a TCAP timeout, an abort, or an unrecognized MAP error - the USSI Error Code session state field will be set to 1 (and the text and DCS fields will be left blank. If the HLR attempts to send a MAPUnstructuredSSNotify_Request, to begin a multipart USSD operation, the feature will respond with a TCAP User Abort, and set the Error Code session state to 1.

Handle USSI Invite

This feature handles the SIP side of the USSI conversation.

Feature cheat sheet

Feature Name Network Operator Data Used in PlanId(s) Stateful or Stateless POJO Feature or SBB Feature

HandleUssiInvite

No

USSI

Stateless with FSM encoded into session state

POJO

Session Input variables

The feature reads the following fields in Session State

Session State variable name Variable type Comments
UssdTextAsText

String

The data to put in the <ussd-string> element of the <ussd-data> xml in the message body

UssdLanguageDcsMapping

enum

An enum that indicates the supported language to put in the <language> element of the <ussd-data> xml

UssdConversationComplete

boolean

Set by the Handle Mobile Initiated Ussd feature to indicate the USSD conversation is finished.

UssiErrorCode

int

Set by the Handle Mobile Initiated Ussd if the response from the HLR is an error

Session Output variables

The feature sets the following fields in Session State

Session State variable name Variable type Comments
MSISDN

String

The MSISDN extracted from the 'P-Asserted-Identity' header.

UssdTextAsText

String

The <ussd-string> element of the <ussd-data> xml from the message body of the INVITE

UssdLanguageDcsMapping

enum

And enum that represents the <language> element of the <ussd-data> xml from the message body of the INVITE

Statistics

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

Name Description
Started

Incremented when the feature is started.

FailedToStart

Incremented when Sentinel encounters an error while attempting to start the feature.

IssuedWarning

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

FailedDuringExecution

Incremented when a fatal problem is encountered and the feature cannot execute correctly.

TimedOut

Incremented when the feature takes too long to complete and Sentinel aborts execution.

ReceivedUssiInvite

Incremented when the feature receives an INVITE that has a multipart/mixed message body with both USSD XML and SDP.

SavedUssiData

Incremented when the USSD XML data is successfully saved in session state.

SentInvite200Response

Incremented when the feature sends a 200 OK response to the INVITE.

ReceivedInviteAck

Incremented when the feature receives the ACK for the 200 OK.

SentByeWithSuccess

Incremented when the feature sends a BYE with successfully retrieved USSD data.

SentByeWithError

Incremented when the feature sends a BYE with a error in the USSD text.

ReceivedBye200Response

Incremented when the feature receives the 200 OK to the BYE.

EndSessionInError

Incremented when the feature ends the session due to an error.

Behaviour

This features handles all of the SIP messaging for a USSI conversation.

It starts by receiving the INVITE and checking it for an SDP body with media ports set to 0, as well as the presence of the ussd-data XML body. When this is confirmed it will save the 'ussd-string' and 'language' fields into session state as well as extracting the MSISDN from the 'P-Asserted-Identity' header.

It will then send a '200 OK' response with the following set:

  • Recv-Info header field containing the g.3gpp.ussd info-package name

  • The 'Accept' header field containing the 'application/vnd.3gpp.ussd+xml', 'application/sdp' and 'multipart/mixed' MIME types

  • SDP answer as described in subclause 4.5.2 of 3GPP TS 24.390

The feature then waits for the 'ACK' to the '200 OK', as well as for the MAP conversation to complete which is handled by the Handle Mobile Initiated Ussd feature. When both of these requirements are satisfied the feature will send a 'BYE' with a application/vnd.3gpp.ussd+xml MIME body, as described in subclause 5.1.3 of 3GPP TS 24.390 including a <ussd-string> element and a <language> element. Or a 'BYE' with a application/vnd.3gpp.ussd+xml MIME body, as described in subclause 5.1.3 of 3GPP TS 24.390 including a <error-code> element.

Mappers

Customising Mappers

Sentinel IPSMGW includes a module pack that can be used to extend all of these mappers:

ipsmgw-mappers

See Customising Mappers in the IPSMGW SDK guide for instructions.

IPSMGWChargingInstanceToCCR

Description

Generates an Ro Credit-Control-Request for online charging, using the ChargingInstance and information extracted from the MAP SendRoutingInfoForSM and MT_ForwardSM (for MT) or SIP Message (for MO) messages. The Diameter Ro version in use is v12.11.0.

From

com.opencloud.sentinel.charging.ChargingInstance

To

org.jainslee.resources.diameter.ro.types.vcb0.CreditControlRequest

See Charging Content AVPs for more information on which AVPs are included in Sentinel IPSMGW CCRs.

MTFSMToSessionCounterAddress

Description

Generates a SessionCounterAddress for MT charging.

From

com.opencloud.sentinel.ipsmgw.eventmanager.tcapmessage.DialogTcapMessage

To

com.opencloud.sentinel.charging.sessioncounters.SessionCounterAddress

Table 1. Key/Value pairs in generated SessionCounterAddress
Key Value or source

Subscriber-Id

Subscriber session state field

Service-Id

1

Cc-Unit-Type

Cc-Service-Specific-Units

TCAP Application Context Negotiation Flows

This page presents detailed information related to TCAP Application Context Negotiation for the Sentinel IP Short Message Gateway product.

SRI for SM receipt handling

The Routing Info for Short Message (SRI-SM) Application Context and request are proxied "as-is" between the received SRI-SM and that sent to the HLR. Therefore any errors from the HLR are proxied back towards the initiator.

For more information on the logic of the flow, please refer to Flows for SMS delivery

MT Forward Short Message negotiation

The IP-SM-GW may sit "in-between" any particular SMSC and the home network’s MSCs and SGSNs. As the IP-SM-GW forces MT Forward Short Message operations to route through it, it must implement TCAP Application Context Negotiation.

Each case is represented by a flow.

SMSC sends MAP Phase 1 Forward Short Message request

mt-fsm-phase1

SMSC sends MAP Phase 2+ empty Open Request where MSC does not support Phase 2+

mt-fsm-phase2-downgrade

SMSC sends MAP Phase 2+ non empty Open Request where MSC does not support Phase 2+

mt-fsm-phase2-downgrade-not-empty

SMSC sends MAP Phase 3 non empty Open Request where MSC supports Phase 2

mt-fsm-phase3-downgrade-not-empty

Both SMSC and MSC support MAP Phase 3 where a response is provided

mt-fsm-phase3-supported-not-empty

Mapping between versions for Forward Short Message Errors

MAP Phases 1 and 2 do not define a result type for the Forward Short Message operation. They do define errors. Therefore if a TC-END is received, where there are no errors, the operation is a success.

The different MAP Phases define similar yet different errors for the operations. When application contexts have been downgraded through negotiation, the errors need to be upgraded.

Phase 1 to Phase 2 Error Mapping

An error when using MAP Phase 1 towards the MSC/SGSN needs to be translated to the appropriate error when replying to Phase 2 towards the SMSC. An example is below.

mt-fsm-phase1-to-2-error

Phase 1 error response Mapped Phase 2 error response

absentSubscriber

absentSubscriber

facilityNotSupported

facilityNotSupported

illegalMS

illegalSubscriber

sm_DeliveryFailure

sm_DeliveryFailure

systemFailure

systemFailure

unexpectedDataValue

unexpectedDataValue

unidentifiedSubscriber

unidentifiedSubscriber

Phase 1 to Phase 3 Error Mapping

An error when using MAP Phase 1 towards the MSC/SGSN needs to be translated to the appropriate error when replying to Phase 3 towards the SMSC. An example is as follows:

mt-fsm-phase1-to-3-error

Phase 1 error response Mapped Phase 3 error response

absentSubscriber

absentSubscriberSM

facilityNotSupported

facilityNotSupported

illegalMS

illegalSubscriber

sm_DeliveryFailure

sm_DeliveryFailure

systemFailure

systemFailure

unexpectedDataValue

unexpectedDataValue

unidentifiedSubscriber

unidentifiedSubscriber

Phase 2 to Phase 3 Error Mapping

An error when using MAP Phase 2 towards the MSC/SGSN needs to be translated to the appropriate error when replying to Phase 3 towards the SMSC.

mt-fsm-phase2-to-3-error

Phase 2 error response Mapped Phase 3 error response

absentSubscriber

absentSubscriberSM

dataMissing

dataMissing

facilityNotSupported

facilityNotSupported

illegalEquipment

illegalEquipment

illegalSubscriber

illegalSubscriber

sm_DeliveryFailure

sm_DeliveryFailure

subscriberBusyForMT_SMS

subscriberBusyForMT_SMS

systemFailure

systemFailure

unexpectedDataValue

unexpectedDataValue

unidentifiedSubscriber

unidentifiedSubscriber

Charging Information

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

Topics

CDR Formats

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.

Topics

AVP CDR Format

AVP CDRs have logical content, and an on-disk format.

Logical content

Each CDR inside a CDR file has logical content. We use a BNF syntax to describe this logical content.

CDR ::=
        [ Subscription-Id ]
        [ IMS-Information ]
        [ User-Equipment-Info ]
       *[ Multiple-Services-Credit-Control ]
        [ OC-Call-Type ]
        [ OC-Service-Type ]
        [ OC-Charging-Result ]
       *[ OC-OCS-Session-Id ]
        [ OC-OCS-Session-Termination-Cause ]
        [ OC-Sentinel-Error ]
       *[ OC-Charging-Instance ]
        [ OC-Event-Id ]
        [ OC-Call-Id ]
        [ OC-End-Session-Cause ]
        [ OC-Session-Start-Time ]
        [ OC-Session-Established-Time ]
        [ OC-Session-End-Time ]
        [ OC-Selection-Key ]
        [ OC-Plan-Id ]
        [ OC-Submit-Report-Type ]
        [ OC-Correlated-Id ]
        [ OC-MT-PS-Delivery-Result ]
        [ OC-MT-CS-Delivery-Result ]
        [ OC-IMPU ]
        [ SMS-Information ]
       *[ 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-OCS-Session-Id AVPs, and so-on.

A CDR inside the CDR file is not an AVP. It is a protobuf record, and as such may contain additional "root" AVPs. So, for example an application may use the format, but add a LCS-Information AVP, or custom AVP.

You could consider each CDR to be roughly equivalent to the Service-Information AVP, yet more flexible/extensible regarding its content. This is because the Service-Information AVP is essentially closed for extension by non-3GPP groups.

To view the population of AVPs in use, refer to Charging Content AVPs

On disk format

AVP CDRs are written using Google protocol buffers (protobuf).

An AVP CDR file has a protobuf schema. This schema allows any AVP to be written to a CDR.

package com.opencloud.cdrformat;

// AVP based CDR

message AvpCdr {

    repeated AVP avps = 1;

    message AVP {
        required bytes avpData = 1; // The Diameter binary encoded AVP data
        required string interfaceName = 2; // The interface which the AVP is being written out as, e.g "Rf", "Ro"
        required string specRevision = 3; // E.g. "vcb0"
        optional string avpName = 4;
    }

}

Legacy CDR Format

The Legacy CDR format has an on-disk format defined using Google protocol buffers (aka protobuf).

There is a common "types definition" schema file that is used by multiple Sentinel Services for their CDRs. These types are called "base types". Each Sentinel Service then defines its own CDRs using these types and defining its own types.

Base types

The base types are used in CDRs for Sentinel SS7, Sentinel Diameter Mediation.

Unresolved directive in ipsmgw-administration-guide/charging-information/cdr-formats/legacy-cdr-format.adoc - include::/mnt/ephemeral0/workspace/product/sentinel/sentinel-ipsmgw/release-2.9.0/Auto/ipsmgw-docs/ipsmgw-docs/target/generated/ipsmgw-administration-guide/sentinel-cdr-common-base-cdr-types.proto[]

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

Unresolved directive in ipsmgw-administration-guide/charging-information/cdr-formats/legacy-cdr-format.adoc - include::/mnt/ephemeral0/workspace/product/sentinel/sentinel-ipsmgw/release-2.9.0/Auto/ipsmgw-docs/ipsmgw-docs/target/generated/ipsmgw-administration-guide/sentinel-ss7-cdr-format.proto[]

CAP3 SMS

CAP3 SMS support ses the following format for its CDR files (out of the box).

Unresolved directive in ipsmgw-administration-guide/charging-information/cdr-formats/legacy-cdr-format.adoc - include::/mnt/ephemeral0/workspace/product/sentinel/sentinel-ipsmgw/release-2.9.0/Auto/ipsmgw-docs/ipsmgw-docs/target/generated/ipsmgw-administration-guide/sentinel-ss7-cdr-format-sms.proto[]

Sentinel Diameter Mediation Service CDR format

The Sentinel Diameter Mediation service defines a CDR format.

Unresolved directive in ipsmgw-administration-guide/charging-information/cdr-formats/legacy-cdr-format.adoc - include::/mnt/ephemeral0/workspace/product/sentinel/sentinel-ipsmgw/release-2.9.0/Auto/ipsmgw-docs/ipsmgw-docs/target/generated/ipsmgw-administration-guide/sentinel-diameter-cdr-format.proto[]

Charging Content AVPs

The population of AVPs for Sentinel IPSMGW is described on this page. A definition of the AVPs used for the Sentinel IPSMGW product is provided on Sentinel IPSMGW AVP definitions.

Detecting Online Charging

The OC-Charging-Result AVP in a CDR or ACR indicates whether online (Diameter Ro) charging was used for a session. This may be used to determine if further action is needed when processing CDRs offline.

  • An OC-Charging-Result value of -1 means that online charging was not used for the session.

  • Otherwise the value is set to the Diameter Result-Code AVP value.

Populated AVPs in the Multiple-Services-Credit-Control AVP

The Multiple-Services-Credit-Control AVP is of type grouped, and is defined in RFC 4006. Section 7.1.4 of 3GPP TS 32.299 defines it with additional 3GPP specific parameters and states some IETF parameters are not used in the 3GPP.

AVP Name Specification reference Included in CDR Included in CCR Included in ACR Comments

Requested-Service-Unit

IETF RFC 4006

No

Yes

No

Used in the CCR. The CDR represents this information in the OC-Session-Counter AVP

Used-Service-Unit

IETF RFC 4006 and 3GPP TS 32.299

No

Yes

No

Used in the CCR according to Populated AVPs in the Used-Service-Unit AVP. The CDR represents this information in the OC-Session-Counter AVP

Service-Identifier

IETF RFC 4006

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 grammar for this AVP in 32.299 v12.11.0 is as follows:

<Multiple-Services-Credit-Control> ::=	   < AVP Header: 456 >

    [ Granted-Service-Unit ]   // not used in CCR
    [ Requested-Service-Unit ]
  * [ Used-Service-Unit ]
    [ Tariff-Change-Usage ]    // not used in 3GPP
  * [ Service-Identifier ]
    [ Rating-Group ]
  * [ G-S-U-Pool-Reference ]   // not used in CCR
    [ Validity-Time ]          // not used in CCR
    [ Result-Code ]            // not used in CCR
    [ Final-Unit-Indication ]  // not used in CCR
    [ Time-Quota-Threshold ]   // not used in CCR
    [ Volume-Quota-Threshold ] // not used in CCR
    [ Unit-Quota-Threshold ]   // not used in CCR
    [ Quota-Holding-Time ]     // not used in CCR
    [ Quota-Consumption-Time ] // not used in CCR
  * [ Reporting-Reason ]
    [ Trigger ]
    [ PS-Furnish-Charging-Information ]
    [ Refund-Information ]
  * [ AF-Correlation-Information]
  * [ Envelope ]
    [ Envelope-Reporting ]
    [ Time-Quota-Mechanism ]
  * [ Service-Specific-Info ]
    [ QoS-Information ]
  * [ AVP ]                    // not used in 3GPP

Populated AVPs in the Used-Service-Unit AVP

The Used-Service-Unit AVP is defined in IETF RFC 4006, and then its BNF is modified slightly in 3GPP TS 32.299 section 7.1.9.

AVP Name Specification reference Included in CDR Included in CCR Included in ACR Comments

Reporting-Reason

3GPP TS 32.299 v12.11.0 section 7.2.175

No

No

No

Tariff-Change-Usage

IETF RFC 4006

No

No

No

CC-Time

IETF RFC 4006

No

Yes

No

Used by default as the unit type for SIP Sessions

CC-Money

IETF RFC 4006

No

No typically

No

Not used out-of-the-box for Sentinel SIP

CC-Total-Octets

IETF RFC 4006

No

Not typically

No

Not used out-of-the-box for Sentinel SIP

CC-Input-Octets

IETF RFC 4006

No

Not typically

No

Not used out-of-the-box for Sentinel SIP

CC-Output-Octets

IETF RFC 4006

No

Not typically

No

Not used out-of-the-box for Sentinel SIP

The 3GPP definition (in v12.11.0) is

<Used-Service-Unit> ::=	   < AVP Header: 446 >
    [ Reporting-Reason ]
    [ Tariff-Change-Usage ]
    [ CC-Time ]
    [ CC-Money ]    // not used in 3GPP
    [ CC-Total-Octets ]
    [ CC-Input-Octets ]
    [ CC-Output-Octets ]
    [ CC-Service-Specific-Units ]
   *[ Event-Charging-TimeStamp ]
   *[ AVP ]        // not used in 3GPP

Populated AVPs in the Service-Information AVP

The Service-Information AVP is defined in 3GPP TS 32.299 v12.11.0. It is a grouped AVP. This table lists the AVPs grouped within Service-Information and how the product populates them.

AVP Name Specification reference Included in CDR Included in CCR Included in ACR Comments

SMS-Information

32.299 v12.11.0 section 7.2.211

Yes

Yes

Yes

Refer to Populated AVPs in the SMS-Information 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 SMS-Information AVP

The SMS-Information AVP is a grouped AVP. It is defined in 32.299 v12.11.0 section 7.2.211.

AVP Name Specification reference Included in CDR Included in CCR Comments

SMS-Node

32.299 v12.11.0 section 7.2.212

No

Yes

IP_SM_GW(1)

Client-Address

32.299 v12.11.0 section 7.2.41

No

Yes

Configured IPSMGW GT address

Data-Coding-Scheme

32.299 v12.11.0 section 7.2.49

No

Yes

The dataCodingSheme portion of the MT_ForwardSM’s SMS-DELIVER TPDU

SM-User-Data-Header

32.299 v12.11.0 section 7.2.210

No

Yes

The userDataHeader portion of the MT_ForwardSM’s SMS-DELIVER TPDU

SM-Status

32.299 v12.11.0 section 7.2.209

No

Yes

The single octet TP-Status field of the MT_ForwardSM’s SMS-STATUS-REPORT TPDU

SM-Discharge-Time

32.299 v12.11.0 section 7.2.206

No

Yes

The TP-Discharge-Time field of the MT_ForwardSM’s SMS-STATUS-REPORT TPDU

Originator-Interface

32.299 v12.11.0 section 7.2.126

No

Yes

Refer to Populated AVPs in the Originator-Interface AVP

Originator-Received-Address

32.299 v12.11.0 section 7.2.127

Yes

Yes

Refer to Populated AVPs in the Originator-Received-Address AVP

Recipient-Info

32.299 v12.11.0 section 7.2.168

Yes

Yes

Refer to Populated AVPs in the Recipient-Info AVP

It has the following ABNF grammar:

SMS-Information :: =   < AVP Header: 2000>
    [ SMS-Node ]
    [ Client-Address ]
    [ Originator-SCCP-Address ]
    [ SMSC-Address]
    [ Data-Coding-Scheme ]
    [ SM-Discharge-Time ]
    [ SM-Message-Type ]
    [ Originator-Interface ]
    [ SM-Protocol-ID ]
    [ Reply-Path-Requested ]
    [ SM-Status ]
    [ SM-User-Data-Header ]
    [ Number-Of-Messages-Sent ]
  * [ Recipient-Info ]
    [ Originator-Received-Address ]
    [ SM-Service-Type ]
Populated AVPs in the Originator-Interface AVP

The Originator-Interface AVP is a grouped AVP. It is defined in 3GPP TS 32.299 v12.11.0 section 7.2.126.

AVP Name Specification reference Included in CDR Included in CCR Comments

Interface-Id

32.299 v12.11.0 section 7.2.71

Yes

Yes

"SCCP Address=<SMSC SCCP Address>"

Interface-Port

32.299 v12.11.0 section 7.2.72

No

Yes

"SSN=<SMSC SCCP Address SSN>"

Interface-Text

32.299 v12.11.0 section 7.2.73

No

Yes

"IP-SM-GW/GSM MAP"

Interface-Type

32.299 v12.11.0 section 7.2.74

No

Yes

MOBILE_TERMINATING(2)

It has the following ABNF grammar:

Originator-Interface: =   < AVP Header: 2009>
    [ Interface-Id ]
    [ Interface-Text ]
    [ Interface-Port ]
    [ Interface-Type ]
Populated AVPs in the Originator-Received-Address AVP

The Originator-Received-Address AVP is a grouped AVP. It is defined in 3GPP TS 32.299 v12.11.0 section 7.2.127.

AVP Name Specification reference Included in CDR Included in CCR Comments

Address-Type

32.299 v12.11.0 section 7.2.9

Yes

Yes

MSISDN (1)

Address-Data

32.299 v12.11.0 section 7.2.7

Yes

Yes

For MT case: The OriginatingAddress portion of the MT_ForwardSM’s SMS-DELIVER TPDU, For MO case: The MSISDN of the served user

Address-Domain

32.299 v12.11.0 section 7.2.8

No

No

Not used

It has the following ABNF grammar:

Originator-Received-Address ::= < AVP Header: 2027>
    [ Address-Type ]
    [ Address-Data ]
    [ Address-Domain ]
Populated AVPs in the Recipient-Info AVP

The Recipient-Info AVP is a grouped AVP. It is defined in 3GPP TS 32.299 v12.11.0 section 7.2.168.

AVP Name Specification reference Included in CDR Included in CCR Comments

Recipient-Address

32.299 v12.11.0 section 7.2.167

Yes

Yes

Refer to Populated AVPs in the Recipient-Address AVP

It has the following ABNF grammar:

Recipient-Info :: = < AVP Header: 2026 >
    [ Destination-Interface ]
  * [ Recipient-Address ]
  * [ Recipient-Received-Address ]
    [ Recipient-SCCP-Address ]
    [ SM-Protocol-ID ]
Populated AVPs in the Recipient-Address AVP

The Recipient-Address AVP is a grouped AVP. It is defined in 3GPP TS 32.299 v12.11.0 section 7.2.167.

AVP Name Specification reference Included in CDR Included in CCR Comments

Address-Type

32.299 v12.11.0 section 7.2.9

Yes

Yes

In the MO Submission case this is always MSISDN

Address-Data

32.299 v12.11.0 section 7.2.7

Yes

Yes

In the MO Submission case this is taken from the Address part of the DestinationAddress portion of the MO_ForwardSM’s SMS-SUBMIT TPDU

It has the following ABNF grammar:

Recipient-Address :: = 	< AVP Header: 1201 >
    [ Address-Type ]
    [ Address-Data ]
    [ Address-Domain ]
    [ Addressee-Type ]

Populated AVPs in the IMS-Information AVP

The IMS-Information AVP is defined in 3GPP TS 32.299 v12.11.0. It is a grouped AVP. This table lists the AVPs grouped within IMS-Information and how the product populates them.

AVP Name Specification reference Included in CDR Included in CCR Included in ACR Comments

Event-Type

32.299 v12.11.0 section 7.2.65

Yes

Yes

Yes

Role-Of-Node

32.299 v12.11.0 section 7.2.177

Yes

Yes

Yes

Sessions with sescase of orig and orig_cdiv are in ORIGINATING_ROLE

Node-Functionality

32.299 v12.11.0 section 7.2.113

Yes

Yes

Yes

Set to value 6 as AS

User-Session-Id

32.299 v12.11.0 section 7.2.242

Yes

Yes

Yes

Set to the Call-Id for the initial request

Outgoing-Session-Id

32.299 v12.11.0 section 7.2.128A

No

No

No

Session-Priority

29.229

Yes

Yes

Yes

Set to value 2

Calling-Party-Address

32.299 v12.11.0 section 7.2.33

Yes

Yes

Yes

Called-Party-Address

32.299 v12.11.0 section 7.2.32

Yes

Yes

Yes

Called-Asserted-Identity

32.299 v12.11.0 section 7.2.31

Yes

Yes

Yes

Number-Portability-Routing-Information

32.299 v12.11.0 section 7.2.120

No

No

No

Carrier-Select-Routing-Information

32.299 v12.11.0 section 7.2.34

No

No

No

Alternate-Charged-Party-Address

32.299 v12.11.0 section 7.2.12

No

No

No

Requested-Party-Address

32.299 v12.11.0 section 7.2.176

Yes

Yes

Yes

This field is only included if different from the Called-Party-Address

Associated-URI

32.299 v12.11.0 section 7.2.26

No

No

No

Application-Server-Information

32.299 v12.11.0 section 7.2.24

No

No

No

Inter-Operator-Identifier

32.299 v12.11.0 section 7.2.80

Yes

Yes

Yes

Transit-IOI-List

32.299 v12.11.0 section 7.2.233B

No

No

No

IMS-Charging-Identifier

32.299 v12.11.0 section 7.2.75

Yes

Yes

Yes

SDP-Session-Description

32.299 v12.11.0 section 7.2.184

Yes

Yes

Yes

SDP-Media-Component

32.299 v12.11.0 section 7.2.180

Yes

Yes

Yes

Served-Party-IP-Address

32.299 v12.11.0 section 7.2.187

No

No

No

Server-Capabilities

29.229

No

No

No

Trunk-Group-ID

32.299 v12.11.0 section 7.2.237

No

No

No

Bearer-Service

32.299 v12.11.0 section 7.2.30

No

No

No

Service-Id

32.299 v12.11.0 section 7.2.190

No

No

No

Service-Specific-Info

32.299 v12.11.0 section 7.2.195

No

No

No

Message-Body

32.299 v12.11.0 section 7.2.103

No

No

No

Cause-Code

32.299 v12.11.0 section 7.2.35

Yes

Yes

Yes

Reason-Header

32.299 v12.11.0 section 7.2.164A

No

No

No

Access-Network-Information

32.299 v12.11.0 section 7.2.1

Yes

Yes

Yes

The first value in the SIP P-Access-Network-Info header is included as the value for this AVP

Early-Media-Description

32.299 v12.11.0 section 7.2.58

Yes

Yes

Yes

The most recent Early Media offer/answer is included

IMS-Communication-Service-Identifier

32.299 v12.11.0 section 7.2.76

Yes

Yes

Yes

IMS-Application-Reference-Identifier

32.299 v12.11.0 section 7.2.74A

No

No

No

Online-Charging-Flag

32.299 v12.11.0 section 7.2.122

No

No

No

Real-Time-Tariff-Information

32.299 v12.11.0 section 7.2.164

No

No

No

Account-Expiration

32.299 v12.11.0 section 7.2.2

No

No

No

Initial-IMS-Charging-Identifier

32.299 v12.11.0 section 7.2.79A

No

No

No

NNI-Information

32.299 v12.11.0 section 7.2.112A

No

No

No

From-Address

32.299 v12.11.0 section 7.2.67A

No

No

No

IMS-Emergency-Indicator

32.299 v12.11.0 section 7.2.76A

No

No

No

IMS-Visited-Network-Identifier

32.299 v12.11.0 section 7.2.77A

No

No

No

Access-Transfer-Information

32.299 v12.11.0 section 7.2.1A

No

No

No

Related-IMS-Charging-Identifier

32.299 v12.11.0 section 7.2.171B

No

No

No

Related-IMS-Charging-Identifier-Node

32.299 v12.11.0 section 7.2.171C

No

No

No

Route-Header-Received

32.299 v12.11.0 section 7.2.177A

No

No

No

Route-Header-Transmitted

32.299 v12.11.0 section 7.2.177B

No

No

No

Instance-Id

32.299 v12.11.0 section 7.2.70A

No

No

No

TAD-Identifier

32.299 v12.11.0 section 7.2.219A

No

No

No

The BNF syntax for the IMS-Information AVP according to 3GPP TS 32.299 v12.11.0 is as follows

    IMS-Information :: =        < AVP Header: 876>
    [ Event-Type ]
    [ Role-Of-Node ]
    { Node-Functionality }
    [ User-Session-Id ]
    [ Outgoing-Session-Id ]
    [ Session-Priority ]
 *  [ Calling-Party-Address ]
    [ Called-Party-Address ]
 *  [ Called-Asserted-Identity ]
    [ Number-Portability-Routing-Information ]
    [ Carrier-Select-Routing-Information ]
    [ Alternate-Charged-Party-Address ]
 *  [ Requested-Party-Address ]
 *  [ Associated-URI ]
    [ Time-Stamps ]
 *  [ Application-Server-Information ]
 *  [ Inter-Operator-Identifier ]
 *  [ Transit-IOI-List ]
    [ IMS-Charging-Identifier ]
 *  [ SDP-Session-Description ]
 *  [ SDP-Media-Component ]
    [ Served-Party-IP-Address ]
    [ Server-Capabilities ]
    [ Trunk-Group-ID ]
    [ Bearer-Service ]
    [ Service-Id ]
 *  [ Service-Specific-Info ]
 *  [ Message-Body ]
    [ Cause-Code ]
 *  [ Reason-Header ]
 *  [ Access-Network-Information ]
 *  [ Early-Media-Description ]
    [ IMS-Communication-Service-Identifier ]
    [ IMS-Application-Reference-Identifier ]
    [ Online-Charging-Flag ]
    [ Real-Time-Tariff-Information ]
    [ Account-Expiration ]
    [ Initial-IMS-Charging-Identifier ]
  * [ NNI-Information ]
    [ From-Address ]
    [ IMS-Emergency-Indicator ]
    [ IMS-Visited-Network-Identifier ]
 *  [ Access-Transfer-Information ]
    [ Related-IMS-Charging-Identifier ]
    [ Related-IMS-Charging-Identifier-Node ]
    [ Route-Header-Received ]
    [ Route-Header-Transmitted ]
    [ Instance-Id ]
    [TAD-Identifier]

Additional populated AVPs

This table lists additional standard AVPs that appear at the top level of a CDR or CCR instead of their standard place in a grouped AVP.

AVP Name Specification reference Included in CDR Included in CCR Comments

PDP-Address

32.299 v12.11.0 section 7.2.137

No

Yes

Destination IPCAN address of SIP message

Populated OpenCloud AVPs

The population of OpenCloud AVPs is described here. The definition of OpenCloud AVPs is provided in Sentinel AVP definitions. ACRs are not used by Sentinel IPSMGW.

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

OC-SM-Message-Type

OC-SM-Message-Type

Yes

Yes

n/a

n/a

OC-Plan-Id

OC-Plan-Id

Yes

No

n/a

n/a

OC-Submit-Report-Type

OC-Submit-Report-Type

Yes

No

n/a

n/a

OC-MT-Correlated-Id

OC-MT-Correlated-Id

Yes

No

n/a

n/a

OC-MT-PS-Delivery-Result

OC-MT-PS-Delivery-Result

Yes

No

n/a

n/a

OC-MT-CS-Delivery-Result

OC-MT-CS-Delivery-Result

Yes

No

n/a

n/a

OC-IMPU

OC-IMPU

Yes

No

n/a

n/a

Sentinel AVP definitions

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

AVPs defined in the Sentinel IPSMGW product

The Sentinel IPSMGW product extends Sentinel Express and adds the following AVP.

OC-SM-Message-Type

The OC-SM-Message-Type AVP (AVP code 2007) is of type Enumerated. It is set based on the MT ForwardSM TPDU Type. This is an OpenCloud defined AVP, as the standardized SM-Message-Type AVP in 3GPP TS 32.274 v8.2.0 does not allow MT values.

  • SUBMISSION = 0

  • DELIVERY_REPORT = 1

  • STATUS_REPORT = 100

  • DELIVER = 101

No Parent AVP.

OC-Plan-Id

The OC-Plan-Id AVP (AVP code 1030) is of type UTF8String. It contains the PlanId for the session. Refer to the DetermineSessionPlan feature for more information on how this is set.

OC-Submit-Report-Type

OC-Submit-Report-Type AVP (AVP code 1031) is of type Enumerated. It contains the submit report type for the MOFSM PlanId.

It can be one of the following:

  • NOT_APPLICABLE = 1

  • SUCCESS = 2

  • INVALID_SMS = 3

  • COMMUNICATION_ERROR = 4

  • U_ABORT = 5

  • P_ABORT = 6

  • INVOKE_TIMEOUT = 7

  • MO_FORWARD_SM_ERROR = 8

  • SS7_STACK_ERROR = 9

No Parent AVP.

OC-MT-Correlated-Id

The OC-MT-Correlated-Id AVP (AVP code 1032) is of type UTF8String. It contains the MT-Correlation-Id associated with the session IMSI.

OC-MT-PS-Delivery-Result

OC-MT-PS-Delivery-Result AVP (AVP code 1033) is of type Enumerated and specifies the PS-Delivery status.

It can be one of the following:

  • NOT_ATTEMPTED = 1

  • DELIVERY_SUCCEEDED = 2

  • DELIVERY_FAILED = 3

No Parent AVP.

OC-MT-CS-Delivery-Result

OC-MT-CS-Delivery-Result AVP (AVP code 1034) is of type Enumerated and specifies the CS-Delivery status.

It can be one of the following:

  • NOT_ATTEMPTED = 1

  • DELIVERY_SUCCEEDED = 2

  • DELIVERY_FAILED = 3

No Parent AVP.

OC-IMPU

OC-IMPU AVP (AVP code 1035) is of type UTF8String. Is set on success PS-Delivery and contains the default Public User Identity for the session.

No Parent AVP.

AVPs defined in Sentinel Express

The following AVPs are defined in the Sentinel Express product, and are used in the Sentinel IPSMGW product.

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.

OC-Session-Counter-Address-Value

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

OC-Cumulative-Committed-Used

The OC-Cumulative-Committed-Used AVP (AVP code 1017) is of type Integer64.

It contains the value of the cumulativeCommittedUsed unit counter documented in Session counter structure.

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.

OC-Interim-CDR-Leg

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

OC-Session-Start-Time

The OC-Session-Start-Time AVP (AVP code 1040) is of type Time.

It contains the time that the session’s Initial Request was processed.

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.

OC-Age-Of-Information

The OC-Age-Of-Information AVP (AVP code 1060) is of type Integer64. The time in milliseconds of the source information. The value depends on which of the grouped AVP’s contains the OC-Age-Of-Information.

OC-MCC-MNC

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

OC-Access-Network-MCC-MNC

The OC-Access-Network-MCC-MNC (AVP code 1062) indicates the home network MCC-MNC, in case the access network can be identified. The information is extracted from the P-Access-Network-Info header. 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.

Ro Interface AVPs

The AVPs used by Sentinel IPSMGW in the credit control request are described.

Sentinel IPSMGW Service population of Credit Control Request

The Credit Control Request message is defined according to IETF RFC 4006, and some AVPs are removed and not used according to 3GPP TS 32.299. Sentinel products use the definition in 3GPP TS 32.299 v12.11.0 for CCR.

This table indicates the top-level AVPs inside a CCR request and how the Sentinel SIP service populates them.

AVP Name Specification reference Included in CDR Included in CCR Comments

Service-Context-Id

IETF RFC 4006 and refined by 3GPP TS 32.299 v12.11.0 section 7.1.12

Yes

Yes

For IP-SM-GW the value is set to 12.32274@3gpp.org.

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 is

<CCR> ::= < Diameter Header: 272, REQ, PXY >

    < Session-Id >
    { Origin-Host }
    { Origin-Realm }
    { Destination-Realm }
    { Auth-Application-Id }
    { Service-Context-Id }
    { CC-Request-Type }
    { CC-Request-Number }
    [ Destination-Host ]
    [ User-Name ]
    [ CC-Sub-Session-Id ]      // not used in 3GPP
    [ Acct-Multi-Session-Id ]  // not used in 3GPP
    [ Origin-State-Id ]
    [ Event-Timestamp ]
   *[ Subscription-Id ]
    [ Service-Identifier ]     // not used in 3GPP
    [ Termination-Cause ]
    [ Requested-Service-Unit ] // not used in 3GPP
    [ Requested-Action ]
   *[ Used-Service-Unit ]      // not used in 3GPP
    [ AoC-Request-Type ]
    [ Multiple-Services-Indicator ]
   *[ Multiple-Services-Credit-Control ]
   *[ Service-Parameter-Info ] // not used in 3GPP
    [ CC-Correlation-Id ]
    [ User-Equipment-Info ]
   *[ Proxy-Info ]
   *[ Route-Record ]
    [ Service-Information ]
   *[ AVP ]

Sizing AVP CDRs

This section documents the storage requirements for AVP CDRs.

Binary CDR log structure

Each CDR log file can be broken down into the following parts:

  • Protobuf overhead - a small amount of type information about contained records.

  • A header section - a small amount of data written by the CDR RA including version, host, and timestamp information.

  • Zero or more AVP CDRs - these records will vary in individual size, and usually form the majority of a CDR log.

  • A footer - this is empty for Sentinel products.

Sizing analysis

The combined size of the header, footer, and protobuf overhead is normally trivial (<1KB) compared to the size of each finished CDR log file.

Individual CDR records will vary in size based on dynamic content such as hostnames, Sentinel selection key names, SDP content, and other similarly variable character data. As such, it is not possible to provide exact sizing for a given system without examining the CDR logs written while under a test load, but some approximations can be made.

A basic CDR record containing the information normally written by Sentinel will be on the order of 2000-3000 bytes. With this in mind, the following sections provide rough estimates regarding how much storage would be required for specific scenarios.

If Sentinel is configured to write Session CDRs (i.e. not writing Interim CDRs), then each session will write a single CDR on the order of 2000-3000 bytes.

Working with CDRs

Note Sentinel writes binary CDRs using the CDR RA. Refer to CDR Resource Adaptor section of this guide for more information about Sentinel and the CDR RA.

List CDRs

The Sentinel SDK contains a List CDRs tool, which can be used to print Sentinel’s binary CDRs files to a human readable format.

The CDR files contain binary encoded Diameter AVPs files in addition to a header and footer. The List CDRs tool decodes the binary CDR file and all the Diameter AVPs which is contains, printing them to the console.

It also supports printing the older 'legacy' CDR format which is not based on AVPs, as used by Sentinel version 2.4.x and earlier.

How to use it in a nutshell:

  • Install the SDK normally using the SDK installer script, which will automatically install list-cdrs at ipsmgw-sdk/tools/list-cdrs

  • Run ipsmgw-sdk/tools/list-cdrs/list-cdrs.sh CDRFILE1 [CDRFILE2]…​

This guide covers the installation options and customisation options available for List CDRs.

Protobuf

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

Topics

Installing List CDRs

Installing the List CDRs tools using the SDK installer

If you install the SDK using the ipsmgw-sdk/build/bin/installer script, then the installer will automatically install the list-cdrs tool at /home/testuser/ipsmgw-sdk/list-cdrs/.

$ ./build/bin/installer
[...]

Creating deployment module deploy-volte ... done.
[...]

Configuration changes written.
[...]

Installing List CDRs tool ... done.
[...]

Installing List CDRs from the SDK using Ant

To install the List CDRs tool using the Ant script instead, use the install-list-cdrs Ant build target under the ipsmgw-sdk/tools directory:

$ cd /home/testuser/ipsmgw-sdk/tools
$ ant install-list-cdrs
Buildfile: /home/testuser/ipsmgw-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/${sentinel.major.version}/sentinel-list-cdrs/${sentinel.major.version}.${sentinel.minor.version}/sentinel-list-cdrs-package-${sentinel.major.version}.${sentinel.minor.version}.zip ...
[ivy:resolve] ..... (8971kB)
[ivy:resolve] .. (0kB)
[ivy:resolve] 	[SUCCESSFUL ] opencloud#sentinel-list-cdrs#sentinel-core/${sentinel.major.version};${sentinel.major.version}.${sentinel.minor.version}!sentinel-list-cdrs-package.zip (1143ms)
     [echo]
     [echo] List CDRs retrieved.
     [echo]
     [echo] Installing List CDRs ...
     [echo]
    [unzip] Expanding: /home/testuser/ipsmgw-sdk/tools/target/sentinel-list-cdrs-package.zip into /home/testuser/ipsmgw-sdk/tools
     [echo]
     [echo]
     [echo] List CDRs installed.
     [echo] To print CDR files, use the script at list-cdrs/list-cdrs.sh
     [echo] Usage: list-cdrs CDRFILE [CDRFILE]...
     [echo]

BUILD SUCCESSFUL
Total time: 14 seconds

Installing List CDRs Standalone

The above two approaches are automated ways of installing the List CDRs package (sentinel-list-cdrs-package.zip) into a particular location: ipsmgw-sdk/tools/list-cdrs/.

Both the above methods place a List CDRs installer archive at ipsmgw-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/ipsmgw-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 ipsmgw-sdk/tools directory:

$ cd /home/testuser/ipsmgw-sdk/tools
$ ant uninstall-list-cdrs
Buildfile: /home/testuser/ipsmgw-sdk/tools/build.xml

uninstall-list-cdrs:
     [echo] Uninstalling (deleting) the list-cdrs install from: /home/testuser/ipsmgw-sdk/tools/list-cdrs/
   [delete] Deleting directory /home/testuser/ipsmgw-sdk/tools/list-cdrs

BUILD SUCCESSFUL
Total time: 0 seconds

Alternatively, just delete the list-cdrs directory:

$ rm -rf ipsmgw-sdk/tools/list-cdrs/

Obtaining CDRs

Obtaining CDR files

The List CDRs tool is designed to read completed binary CDR files generated by Sentinel.

Sentinel uses the CDR RA to write CDR files in a binary format. It typically writes these CDR files to the cdr directory inside the Rhino installation, and writes these binary CDR files using names such as cdr_101_1468259745367.log.

The List CDRs tool can read these completed binary CDR files either in their raw binary format (e.g. cdr_101_1468259745367.log), or in gzip compressed format (e.g. cdr_101_1468259745367.log.gz).

Note Before a CDR file is completed, Sentinel may write a partial CDR file to disk, e.g. cdr_101_cdr-stream_28929467492591509.tmp. When a partially written CDR is ready to be rolled over, the CDR RA converts it to a completed binary CDR file, e.g. cdr_101_1468259745367.log. The List CDRs tool cannot read partially written CDR files. It can only read complete CDR files.

Running List CDRs

To invoke the List CDRs tool, run the list-cdrs.sh script under the ipsmgw-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 ipsmgw-sdk/tools parent directory does not contain a list-cdrs directory, then the List CDRs tool needs to be installed. The Installing List CDRs page describes how to install the List CDRs tool.

Calling the script with no arguments shows the expected syntax:

$ ./tools/list-cdrs/list-cdrs.sh
Usage: list-cdrs.sh [--no-header] [--no-footer] [--no-protocol] [--ignore-error]
                    [--output-file OUTPUTFILE] [--size-limit BYTES]
                    [--cdr-filter FIELD=REGEX] CDRFILE [CDRFILE]...

    --no-header              - Disable printing of CDR headers.
    --no-footer              - Disable printing of CDR footers.
    --no-protocol            - Disable printing of protocol and spec revisions
                               in top level AVPs, e.g. "(Ro,vcb0)".
    --ignore-error           - Continue processing CDRs files when encountering
                               recoverable errors.
    --list-icids             - List all unique IMS Charging Identifiers in the given CDR file(s),
                               in order of first appearance.
    --filter-by-icid ICID    - Print CDR message body only when CDR contains the given IMS Charging Identifier.
                               ICID can be listed by "--list-icids" option.
    --output-file OUTPUTFILE - Append CDR output to OUTPUTFILE rather than to the console.
    --size-limit BYTES       - CDR record size limit. Minimum and default value is
                               67108864 (64MB). Increase if encountering
                               "Protocol message was too large" exception.
    --cdr-filter FIELD=REGEX - Print CDR message body only when the given FIELD
                               matches the given regular expression. FIELD can be
                               a field name, an AVP name, or an AVP path like
                               "/IMS-Information/User-Session-Id".
    CDRFILE                  - A completed binary CDR file as produced by Sentinel. Both the new
                               AVP based format (Sentinel 2.5 and later) and the older
                               format (Sentinel 2.4 and earlier) are supported. CDR files
                               can optionally be in gzip format, using a '.gz' suffix.
                               Partially written CDR files (ending in ".tmp") are not supported.

An example invocation, showing how to print a CDR file:

2016-08-03T20:45:47.569+1200 Header {
  ra_name=CDR Generation,
  ra_vendor=OpenCloud,
  ra_version=2.3,
  ra_release=2.3.0.0,
  ra_build=20160715041441,
  ra_revision=cdr-ra/2.3.0@a177ef4,
  description=CDR session,
  rhino_node=101,
  ra_entity=cdr,
  hostname=stroganoff.opencloud.co.nz
}
2016-08-03T20:45:47.575+1200 AvpCdr {
  avps=[
    IMS-Information(Ro,vcb0)[
      Node-Functionality[AS(6)],
      Session-Priority[PRIORITY_2(2)]
    ],
    Service-Context-Id(Ro,vcb0)[12.32274@3gpp.org],
    OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:map:SRI4SM:],
    OC-Service-Type(Ext,Ext)[Unknown(1)],
    OC-Charging-Result(Ext,Ext)[-1],
    OC-Sentinel-Error(Ext,Ext)[None(1)],
    OC-Plan-Id(Ext,Ext)[SRI4SM],
    OC-Submit-Report-Type(Ext,Ext)[NOT_APPLICABLE(1)],
    MSISDN(Ro,vcb0)[46 21 43 65 87],
    OC-MT-Correlated-Id(Ext,Ext)[001010000000000],
    OC-MT-PS-Delivery-Result(Ext,Ext)[NOT_ATTEMPTED(1)],
    OC-MT-CS-Delivery-Result(Ext,Ext)[NOT_ATTEMPTED(1)],
    SMS-Information(Ro,vcb0)[
      Originator-SCCP-Address[00 08 53 63 63 70 41 64 64 72 65 73 73 5b 74 79 70 65 3d 43 37 2c 72 6f 75 74 65 4f 6e 44 50 43 3f 3d 66 61 6c 73 65 2c 6e 61 74 69 6f 6e 61 6c 55 73 65 3f 3d 74 72 75 65 2c 67 74 20 69 6e 64 69 63 61 74 6f 72 3d 47 54 5f 30 30 30 31 2c 6e 61 74 75 72 65 3d 33 20 28 6e 61 74 69 6f 6e 61 6c 20 28 73 69 67 6e 69 66 69 63 61 6e 74 29 20 6e 75 6d 62 65 72 29 2c 61 64 64 72 65 73 73 3d 36 34 31 32 33 5d],
      Recipient-Info[
        Recipient-SCCP-Address[00 08 53 63 63 70 41 64 64 72 65 73 73 5b 74 79 70 65 3d 43 37 2c 72 6f 75 74 65 4f 6e 44 50 43 3f 3d 74 72 75 65 2c 6e 61 74 69 6f 6e 61 6c 55 73 65 3f 3d 74 72 75 65 2c 70 63 3d 36 20 28 30 2f 30 2f 36 29 2c 73 73 6e 3d 31 34 37 5d]
      ]
    ]
  ]
}
2016-08-03T20:45:48.685+1200 AvpCdr {
  avps=[
    IMS-Information(Ro,vcb0)[
      Role-Of-Node[ORIGINATING_ROLE(0)],
      Node-Functionality[AS(6)],
      Session-Priority[PRIORITY_2(2)],
      Called-Party-Address[sip:127.0.0.1:5060],
    ],
    Service-Context-Id(Ro,vcb0)[12.32260@3gpp.org],
    OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:sipcall:MTFSM_DR:],
    OC-Call-Type(Ext,Ext)[MOC(1)],
    OC-Service-Type(Ext,Ext)[Message(5)],
    OC-Charging-Result(Ext,Ext)[-1],
    OC-Sentinel-Error(Ext,Ext)[None(1)],
    OC-Call-Id(Ext,Ext)[e-gJhCPjtEDqoZWG8yBIng],
    OC-Plan-Id(Ext,Ext)[MTFSM_DR],
    OC-Submit-Report-Type(Ext,Ext)[NOT_APPLICABLE(1)],
    OC-MT-PS-Delivery-Result(Ext,Ext)[NOT_ATTEMPTED(1)],
    OC-MT-CS-Delivery-Result(Ext,Ext)[NOT_ATTEMPTED(1)],
    SMS-Information(Ro,vcb0)[    ]
  ]
}
2016-08-03T20:45:48.878+1200 AvpCdr {
  avps=[
    IMS-Information(Ro,vcb0)[
      Node-Functionality[AS(6)],
      Session-Priority[PRIORITY_2(2)]
    ],
    Service-Context-Id(Ro,vcb0)[12.32274@3gpp.org],
    OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:map:MTFSM_PS_CS:],
    OC-Service-Type(Ext,Ext)[Unknown(1)],
    OC-Charging-Result(Ext,Ext)[-1],
    OC-Sentinel-Error(Ext,Ext)[None(1)],
    OC-End-Session-Cause(Ext,Ext)[202],
    OC-Plan-Id(Ext,Ext)[MTFSM_PS_CS],
    OC-Submit-Report-Type(Ext,Ext)[NOT_APPLICABLE(1)],
    MSISDN(Ro,vcb0)[46 21 43 65 87],
    TGPP-IMSI(Ro,vcb0)[001010000001001],
    OC-MT-Correlated-Id(Ext,Ext)[001010000000000],
    OC-MT-PS-Delivery-Result(Ext,Ext)[DELIVERY_SUCCEEDED(2)],
    OC-MT-CS-Delivery-Result(Ext,Ext)[NOT_ATTEMPTED(1)],
    OC-IMPU(Ext,Ext)[tel:+6412345678],
    SMS-Information(Ro,vcb0)[
      Originator-SCCP-Address[00 08 53 63 63 70 41 64 64 72 65 73 73 5b 74 79 70 65 3d 43 37 2c 72 6f 75 74 65 4f 6e 44 50 43 3f 3d 66 61 6c 73 65 2c 6e 61 74 69 6f 6e 61 6c 55 73 65 3f 3d 74 72 75 65 2c 67 74 20 69 6e 64 69 63 61 74 6f 72 3d 47 54 5f 30 30 30 31 2c 6e 61 74 75 72 65 3d 33 20 28 6e 61 74 69 6f 6e 61 6c 20 28 73 69 67 6e 69 66 69 63 61 6e 74 29 20 6e 75 6d 62 65 72 29 2c 61 64 64 72 65 73 73 3d 36 34 31 32 33 5d],
      Recipient-Info[
        Recipient-SCCP-Address[00 08 53 63 63 70 41 64 64 72 65 73 73 5b 74 79 70 65 3d 43 37 2c 72 6f 75 74 65 4f 6e 44 50 43 3f 3d 74 72 75 65 2c 6e 61 74 69 6f 6e 61 6c 55 73 65 3f 3d 74 72 75 65 2c 70 63 3d 36 20 28 30 2f 30 2f 36 29 2c 73 73 6e 3d 31 34 37 5d]
      ]
    ]
  ]
}
2016-08-03T20:45:50.554+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 ipsmgw-sdk/list-cdrs/log4j.properties.

By default, it will log to ipsmgw-sdk/tools/list-cdrs/logs/list-cdrs.log. It logs very little when using the default configuration — the log file will typically be empty unless configured for debug logging.

To enable debug logging, change the log level on the last line of the log4j.properties file to DEBUG:

log4j.logger.sentinel.cdr=DEBUG

Extension AVPs

Built-in AVPs and extension AVPs

The binary CDR format contains Diameter AVPs encoded in binary form, and the List CDRs tool decodes these binary AVPs before printing them in a human readable format.

The tool has built-in knowledge of AVPs which are defined in Diameter protocols such as Rf and Ro.

It can also be customized with knowledge of user defined extension AVPs, by providing definitions of those AVPs in YAML files.

The List CDRs tool looks in the list-cdrs/extension-avps directory for YAML based files which define these extension AVPs.

A default installation of the List CDRs tool contains a DiameterExtension-AVP.yaml file inside this directory, which defines OpenCloud’s extension AVPs. This means that by default, the List CDRs tool recognizes all the AVPs in the CDR files produced by Sentinel.

Known AVPs vs Undefined AVPs

When encountering an AVP which it does not recognize, the List CDRs tool treats it as an Undefined AVP. Because the tool can’t see which type of AVP it is (e.g. UTF8String or Integer32), it prints the raw binary content of the AVP in hexadecimal format.

This is how the List CDRs tool will print an extension AVP that it doesn’t recognize:

    Undefined-AVP[code=1029,vendor=19808,hex=64 61 4a 76 69 5f 64 4e 69 65 5f 57 5f 76 2d 66 7a 44 4f 66 6c 67,ascii=daJvi_dNie_W_v-fzDOflg],

This is how the List CDRs tool prints that same extension AVP, when that AVP is configured as an extension AVP (see below):

    OC-Call-Id[daJvi_dNie_W_v-fzDOflg],

Built-in extension AVPs

This is an excerpt from the default extension AVP configuration file at
list-cdrs/extension-avps/DiameterExtension-AVP.yaml, showing the first two extension AVPs:

$ cat extension-avps/DiameterExtension-AVP.yaml
!profiles
DiameterExtension-AVP:
    id:
        name: 'Diameter Extension AVP'
        vendor: 'OpenCloud'
        version: '2.7'
    imports: null
    profiles:
        ? ''
        :   AvpCode: 0
            AvpName: null
            AvpType: null
            MandatoryRule: 1
            ProtectedRule: 1
            VendorId: 0
        OC-Sentinel-Selection-Key:
            AvpCode: 1001
            AvpName: OC-Sentinel-Selection-Key
            AvpType: UTF8String
            MandatoryRule: 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:

$ 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

Installing Protobuf

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

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

Installing Protobuf from the SDK using Ant

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

$ cd /home/testuser/ipsmgw-sdk/tools
$ ant install-protobuf

init-build-extensions:

[...]

init-tools-common:

install-protobuf:
     [echo]
     [echo] Retrieving Protobuf...
    [mkdir] Created dir: /home/testuser/ipsmgw-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/ipsmgw-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/ipsmgw-sdk/tools/target/protobuf-2.3.0.tar.gz to /home/testuser/ipsmgw-sdk/tools/target/protobuf-2.3.0.tar
    [untar] Expanding: /home/testuser/ipsmgw-sdk/tools/target/protobuf-2.3.0.tar into /home/testuser/ipsmgw-sdk/tools
     [echo]
     [echo]
     [echo] Protobuf unpacked.
     [echo] Requires further install steps, please read protobuf-2.3.0/README.txt for further details.
     [echo]

BUILD SUCCESSFUL
Total time: 6 seconds

To complete installation, follow the instructions in ipsmgw-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 ipsmgw-sdk/tools/ directory:

$ cd /home/testuser/ipsmgw-sdk/tools
$ ant install-protobuf

init-build-extensions:

[...]

init-tools-common:

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

BUILD SUCCESSFUL
Total time: 2 seconds

Alternatively, just delete the protobuf-2.3.0 directory:

$ rm -rf ipsmgw-sdk/tools/protobuf-2.3.0/

SIP Transports and Routing

This page describes how SIP requests are routed to and from the IPSMGW .

The ICSCFURI and SipTransport parameters in the Shared Configuration Profile determine how SIP requests are routed to and from the IPSMGW.

Outbound SIP requests

The ICSCFURI parameter specifies the URI of the I-CSCF in the operator’s network. The IPSMGW inserts this URI in the Route header of outbound requests. This determines the address, port and transport protocol that will be used when sending the request.

ICSCFURI is parsed as a SIP URI as per section 19.1 of RFC 3621. It may use hostnames or IP addresses, and also the port and transport may be specified. Some valid examples are shown below:

  • sip:icscf.home1.net

  • sip:10.45.200.1:5062;lr;transport=tcp

  • sip:server5.ims.example.com:5060

Note The "lr" parameter is automatically added to the I-CSCF’s URI when it is used in an outgoing request’s Route header. It does not need to be specified in ICSCFURI.

In an operator network it will usually be preferable to use a FQDN without port or transport parameters, such as sip:icscf.home1.net. The IPSMGW will then use RFC 3263 DNS procedures to dynamically resolve the address, port and transport of the I-CSCF. This means the operator can easily change the I-CSCF location in the DNS, without needing to update clients. For testing purposes it may sometimes be useful to use explicit IP addresses, ports or transports.

Inbound SIP requests

The SipTransport parameter is used when IPSMGW needs to construct its P-Asserted-Identity address. The routing of inbound requests, such as delivery reports, is determined by this address.

The P-Asserted-Identity address is constructed using the local IP address and port configured in the SIP-SIS resource adaptor, and the transport specified by SipTransport. This may be "tcp" or "udp".

An SM-over-IP receiver that sends a delivery report to the IPSMGW obtains the address from the P-Asserted-Identity header in the MESSAGE it received from the IPSMGW (3GPP TS 24.341 §5.3.2.4).

For example, when IPSMGW delivers a short message, it puts its own address in the P-Asserted-Identity header.

MESSAGE tel:+4475500002222 SIP/2.0
From: <sip:ipsmgw-address:5060;transport=udp>;tag=096724a
To: <tel:+4475500002222>
P-Asserted-Identity: <sip:ipsmgw-address:5060;transport=udp>
Content-Type: application/vnd.3gpp.sms
...

When the SM-over-IP receiver sends its delivery report request, it uses this address in the Request-URI:

MESSAGE sip:ipsmgw-address:5060;transport=udp SIP/2.0
From: <tel:+4475500002222>;tag=5623989
To: <sip:ipsmgw-address:5060;transport=udp>
P-Asserted-Identity: <tel:+4475500002222>
Content-Type: application/vnd.3gpp.sms
...

In this way, delivery reports are routed to the IPSMGW using the configured SipTransport.

Resource Adaptors

In Rhino, a Resource Adaptor (RA) provides the interface between the application (Sentinel IP-SM-GW) and the network. Sentinel IP-SM-GW makes use of a number of Resource Adaptors, for purposes ranging from database connections to network integration.

OpenCloud Resource Adaptors used by Sentinel IP-SM-GW

Sentinel IP-SM-GW uses the following Resource Adaptor Entities out of the box.

Resource Adaptor Entity Purpose

cassandra-ipsmgw

communication with the Cassandra Database for IPSMGW specific tables

cassandra-third-party-reg

communication with the Cassandra Database for Registrar specific tables

cdr

writing of call detail records (or 3GPP Charging Data Records)

cginmapra

sending/receiving MAP messages to/from any network element

diameter-sentinel-internal

internal Ro communication between protocol handling front-ends and the internal mediation subsystem

diameterro-0

communication with Online Charging Systems

ipsmgw-correlation-ra

enabling the correlation of IPSMGW session data with subscriber data retrieved from the HLR

sentinel-management

management of Sentinel subsystems

sh-cache-microservice-ra

communication with the HSS

sip-sis-ra

SIP interface for the IP-SM-GW

sipra

utility mechanisms for the SIP protocol

uid

allocation of globally unique IDs

Further information on specific Resource Adaptors

Below are overviews of:

Within Sentinel IP-SM-GW, the main users of the Sh Cache Microservice RA are:

  • PS Delivery feature --- uses the sh-cache-microservice-ra to subscribe to UE Reachability for IP Sh-Notifications

Note For more information on UE Reachability see UE Reachability for IP Notification Flows

CDR Resource Adaptor

CDR resource adaptor entities

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

CDR resource adaptor configuration

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

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

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

Sentinel configuration requirements

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

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

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

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

Correlation Resource Adaptor

Correlation RA Overview

What is the Correlation RA?

The Correlation RA provides a mechanism to allocate a routing number with correlation data. The routing number and associated correlation data is replicated across the Rhino cluster. All nodes in the cluster have access to read/write correlation data.

This is used in the IP-SM-GW in order to allocate a correlation IMSI as part of the MT Delivery flows. The feature that performs this function is the Generate MT Correlation Id feature.

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

Configuring a Correlation RA entity

A Correlation RA entity configuration consists of:

Note The Correlation Ra Configurer in the installer configures the GenerateMTCorrelationIdFeature which makes use of the CorrelationProvider. The generate mt correlation id feature in IPSMGW Configuration
Tip The Correlation resource adaptor supports live re-configuration, so the administrator may update the configuration properties of a Correlation resource adaptor entity that has already been created.

Correlation RA configuration properties

The Correlation RA configuration properties are:

Name

Type

Description

ConfigProfileTable

String

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

ConfigProfile

String

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

CorrelationIdPoolProfileTable

String

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

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

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

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 IP-SM-GW Correlation RA entity has the following configuration:

[Rhino@localhost (#8)] listprofileattributes CorrelationConfigTable IPSMGWCorrelationConfigProfile
CorrelationIDExpiryTimerPeriod=55000
NumberOfThreadPool=5
RequestTimeout=5000
Note If a change is made to the profile, the following command to activate the changes:
rhino-console updateraentityconfigproperties ipsmgw-correlation-ra

Once a Correlation ID has been allocated it is returned to the pool either when the application returns it, or after CorrelationIDExpiryTimerPeriod milliseconds. Once returned to the pool a Correlation ID is available for subsequent allocation.

Correlation RA entity ID pools configuration

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

  • a default ID pool (optional)

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

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

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

AddressPrefixes

The MCC and MNC. If deploying rhino as a cluster this should be one entry for each cluster.

NodeIds

The rhino cluster ids

IsPreconfiguredCorrelationIdSetUsed

false

PreconfiguredCorrelationIdSet

null

MinCorrelationIDInCluster

The first possible fake IMSI. The MCC and MNC (the first 5 or 6 digits) must be the same as defined in AddressPrefixes

MaxCorrelationIDInCluster

The last possible fake IMSI. The MCC and MNC (the first 5 or 6 digits) must be the same as defined in AddressPrefixes

CorrelationIDNumberOfDigits

The number of IMSI digits depending on the network. Maximum number is 15

CorrelationIDRangePerNode

Number of the fake IMSIs per cluster node

Note If a change is made to the profile, the following command to activate the changes:
rhino-console updateraentityconfigproperties ipsmgw-correlation-ra

Ensuring that Correlation IDs have the appropriate number of digits

The correlation RA will always return a value with the size specified in CorrelationIDNumberOfDigits by padding zeros. The proper configuration is to have the number of digits in MinCorrelationIDInCluster and MaxCorrelationIDInCluster to be equal to CorrelationIDNumberOfDigits. In the following example, the number of digits is 10, and both the min and max values have 10 digits.

  • AddressPrefixes = 64452

  • CorrelationIDNumberOfDigits = 10

  • MinCorrelationIDInCluster = 6445200000

  • MaxCorrelationIDInCluster = 6445299999

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.

In addition to the above statistics there are additional statistics use by Generate MT Correlation Id as the Generate MT Correlation Id feature uses the Correlation RA.

Caution The count correlationGets should equal the sum of localGets + remoteGets. These statistics can use used to create threshold-based alarms.

Diameter Resource Adaptor

Diameter RA documentation

Diameter resource adaptors

There are currently 2 Diameter Ro Resource Adaptor Entities in Sentinel IP-SM-GW:

  • diameterro-0 — for OCS connections

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

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)

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

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

Link name Default Bound RA entity

sentinel-sip

sip-sis-ra

Sentinel and SIS

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

Configuring SIS

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

Configuring the network interface

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

Cassandra Storage

This page describes how Sentinel IP-SM-GW uses the Cassandra database.

Overview

The IPSMGW uses a Cassandra database for storing Third Party Registration data, Routing Information, and for generating Message References. During Installation the user is asked to enter connection details for the Cassandra Database.

How it works

The Cassandra Storage system uses the Cassandra CQL RA to create, update and remove entries from a Cassandra Database cluster.

Note For information about the Cassandra CQL RA’s architecture and configuration, see the Cassandra CQL Resource Adaptor Guide.

Cassandra Database Configuration

The administrator is required to download and set up a Cassandra Database. The Sentinel IP-SM-GW installer does not perform this function on the behalf of the user. It is required that the installed version of Cassandra be 2.0.17+ or 2.1.17+.

OpenCloud recommends reading Cassandra’s Getting Started page.

For a test system, a single Cassandra Database instance may be sufficient if redundancy is not a requirement.

Minimal production recommendations

For a minimal production system, in order to tolerate a single failure in the Cassandra Database there should be at least three nodes configured per site. The Cassandra replication factor should be three.

Higher replication factors can be used on larger clusters. The recommended consistency level for this storage system is the LOCAL_QUORUM consistency level. All read and write queries are programmed to use LOCAL_QUORUM as the consistency level.

It is assumed that in a multi-site deployment, an appropriate Snitch and Topology Strategy are used. As a basis, we suggest use of the NetworkTopologyStrategy and GossipingPropertyFileSnitch, then reading the relevant links below to review this selection.

There are several recommended links to review when planning a deployment.

Configuration aspect Cassandra documentation link

Planning a Cassandra deployment

Recommended settings for Cassandra

Some anti-patterns, or things to not do with Cassandra

Cassandra Consistency levels and replication factors - in particlar read the LOCAL_QUORUM section

Cassandra Snitches - read this when configuring a single site or multi-site deployment

Cassandra Topology Strategies - read this when configuring a single site or multi-site deployment

Performance recommendations

OpenCloud recommend that Cassandra’s Data directory and Commit log directories are on different physical devices (e.g. different disks). If this is not possible, then different partitions on the same device is acceptable. OpenCloud performance testing shows that there are benefits using different partitions on the same device when there are 1000 or more Cassandra DB transactions per second.

Sentinel IP-SM-GW Configuration for Cassandra

Each insert and update in the database uses Cassandra’s 'time to live' feature, automatically removing stale data from the database. The TTL is set in seconds. It is always calculated to be greater than the largest expiry for a First Party Registration.

3rd-Party Registration TTL

The TTL is defined as the largest expiry from First Party Registration plus a configured time. The configured time value is defined in the Profile Table CassandraSubscriberDataStoreConfig. It is scoped by a Sentinel Selection Key. The value is stored in the attribute named CassandraTTL. The default value is 1800 seconds (30 minutes).

Routing Info TTL

For Routing Info the TTL is configured in IPSMGWRoutingInfoCassandraConfigProfileTable. The value is stored in the attribute named CassandraTTL. The default value is 120 seconds.

Sentinel IP-SM-GW Data Schema

Cassandra’s tables exist in a 'keyspace', which, for illustrative purposes, can be thought of as a 'database' in SQL implementations. Creating a keyspace is simple, but some considerations are present.

Third Party Registration

  • The keyspace must be named opencloud_thirdparty_reg

  • For a production environment, the keyspace can be created such that it is replicated. A sample CQL command for creating such a keyspace is:

CREATE KEYSPACE opencloud_thirdparty_reg WITH REPLICATION={'class' : 'NetworkTopologyStrategy' ,'replication_factor' : 3 };
  • For testing purposes, replication may not be necessary. A sample CQL command for creating such a keyspace is:

CREATE KEYSPACE opencloud_thirdparty_reg WITH REPLICATION={'class' : 'SimpleStrategy' ,'replication_factor' : 1 };

Once a keyspace is created, the required tables can be created. The following CQL statements provide both the structure and insight into the tables that are required.

USE opencloud_thirdparty_reg;

CREATE TABLE REGISTRATIONDATA(
    callid text,                    //The callid used for registration
    defaultpublicid text,           //The default IMS Public ID
    privateid text,                 //The IMS Private ID
    associateduris list<text>,      //The Associated URIs
    contacts set<text>,             //Registered Contacts
    visitednetworkid text,          //P-Visited-Network-ID header from registration
    creationtime timestamp,         //The registration creation datetime
    expires int,                    //The time this registration expires in seconds
    expirytime timestamp,           //The registration expiration datetime
    tempgruu text,                  //Temporary GRUU defined in the Contacts
    gruu text,                      //The GRUU in the Contacts
    cmsisdn text,                   //The Correlation MSISDN
    stnsr text,                     //The Session Transfer Number for Single Radio
    isuesrvcccapable boolean,       //Whether the ue has capability UE-SRVCC-CAPABILITY-SUPPORTED
    paccessnetworkinfo list<text>,  //P-Access-Network-Info header from registration
    currentatusti text,             //Current ATU-STI, from initial registration
    atcfmgmturi text,               //ATCF Management URI, from initial registration
    atcfpathuri text,               //ATCF path URI, from initial registration
    primary key(callid)
);

CREATE TABLE ASSOCURIS(
    impu text,                      //A referenced IMS Public ID
    callid text,                    //The callid used for registration
    isdefault boolean,              //Flag indicating if this IMPU is the default public ID
    defaultpublicid text,           //The default IMS Public ID
    privateid text,                 //The IMS Private ID
    regstate text,                  //Registration state: active, terminated or unknown
    creationtime timestamp,         //The registration creation datetime
    expires int,                    //The time this registration expires in seconds
    expirytime timestamp,           //The registration expiration datetime
    cmsisdn text,                   //The Correlation MSISDN
    associateduris list<text>,      //The Associated URIs
    contacts set<text>,             //Registered Contacts
    isuesrvcccapable boolean,       //Whether the ue has capability UE-SRVCC-CAPABILITY-SUPPORTED
    visitednetworkid text,          //P-Visited-Network-ID header from registration
    paccessnetworkinfo list<text>,  //P-Access-Network-Info headers from registration
    currentatusti text,             //Current ATU-STI, from initial registration
    atcfmgmturi text,               //ATCF Management URI, from initial registration
    atcfpathuri text,               //ATCF path URI, from initial registration
    primary key(impu,callid)
);

IP-SM-GW Routing Information

  • The keyspace must be named opencloud_ipsmgw_routing_info

  • For a production environment, the keyspace can be created such that it is replicated. A sample CQL command for creating such a keyspace is:

CREATE KEYSPACE opencloud_ipsmgw_routing_info WITH REPLICATION={'class' : 'NetworkTopologyStrategy' ,'replication_factor' : 3 };
  • For testing purposes, replication may not be necessary. A sample CQL command for creating such a keyspace is:

CREATE KEYSPACE opencloud_ipsmgw_routing_info WITH REPLICATION={'class' : 'SimpleStrategy' ,'replication_factor' : 1 };

Once a keyspace is created, the required tables can be created. The following CQL statements provide both the structure and insight into the tables that are required.

USE opencloud_ipsmgw_routing_info;

CREATE TABLE IPSMGWROUTINGINFO(
    mtcorrelationid text,           //The mtcorrelationid used as the address of the SRI SM response
    appcontext text,                //The application context of the stored SRI SM response
    srismarg blob,                  //The SRI SM request that is stored as a byte array
    srismres blob,                  //The SRI SM response that is stored as a byte array
    msisdn text,                    //The MSISDN retrieved from the SRI SM request
    imsi text,                      //The IMSI retrieved from the SRI SM response
    uuid uuid,                      //The UUID generated for SAS correlation
    primary key(mtcorrelationid)
);

CREATE TABLE IPSMGWGenerateMessageReference(
    imsi text,                      //MSISDN from the MT FSM (previously used IMSI as key, but not always available)
    messagereference bigint,        //The message reference counter to use when forwarding an RpData - it will be modulo 256 so we actually loop through 0 - 255
    primary key(imsi)
);

The schemas are used by three features:

Initial Filter Criteria

Initial Filter Criteria (iFC) is the mechanism used by the IMS to invoke Application Servers. It applies to SIP initial requests.

Requirements for Sentinel IP-SM-GW

The Sentinel IP-SM-GW receives Third Party Registration and SIP MESSAGE requests. In particular the SIP MESSAGE requests contain SMS RP-DATA level information encapsulated in the body of the SIP MESSAGE request.

The IP-SM-GW receives SIP MESSAGE requests where the addressing requirements for those SIP MESSAGE requests are standardised in 3GPP TS 24.341. The addressing for these messages provides the requirements for the iFC configuration.

These are:

  1. Submitting a short message - the Request-URI uses the Public Service Identity of the Service Centre of the SM-over-IP sender.

  2. Sending a notification about SM-over-IP receiver having memory available - the Request URI which shall contain the IP-SM-GW address, if available, and shall contain PSI of the SC otherwise.

  3. Sending a delivery report - the Request-URI is set to the received P-Asserted-Identity in the received SIP MESSAGE request including the delivered short message.

This means that there is:

  1. One PSI for each Service Centre - that can include an AS name that resolves (via DNS) to any IP-SM-GW cluster node that represents the Service Centre.

  2. One PSI for each cluster node - such that delivery reports can route directly to the appropriate node.

Flows for submitting a short message are shown in MO Submission Flows. The delivery report is part of the MT Delivery Flows and is mentioned as the SIP MESSAGE request containing an RP-ACK.

Registration

The IP-SM-GW requires Third Party Registration details for various functions, so registrations need to be routed to the IP-SM-GW. First-Party register and response should be included in the Register messages. Depending on your HSS, the configuration for including first-party request and response messages could be on the iFC or the associated AS. The ServerName name in the iFC should resolve to multiple AS nodes through DNS.

<?xml version="1.0"?>
<!-- Example IFC for sending registration messages to the IPSMGW -->
<InitialFilterCriteria>
    <Priority>1</Priority>
    <TriggerPoint>
        <!-- ConditionTypeCNF 1 means logical OR of SPT elements in the same group then AND the SPT elements in different groups -->
        <ConditionTypeCNF>1</ConditionTypeCNF>

        <!-- logically, this TriggerPoint matches if the request is an Initial Registration or a Re-Registration or a De-registration -->
        <SPT>
            <Group>0</Group>
            <Method>REGISTER</Method>
            <Extension>
                <RegistrationType>0</RegistrationType> <!-- INITIAL_REGISTRATION -->
            </Extension>
        </SPT>
        <SPT>
            <Group>0</Group>
            <Method>REGISTER</Method>
            <Extension>
                <RegistrationType>1</RegistrationType> <!-- RE_REGISTRATION -->
            </Extension>
        </SPT>
        <SPT>
            <Group>0</Group>
            <Method>REGISTER</Method>
            <Extension>
                <RegistrationType>2</RegistrationType> <!-- DE_REGISTRATION -->
            </Extension>
        </SPT>
    </TriggerPoint>
    <ApplicationServer>
        <!-- The DNS name should resolve to a number of IP-SM-GW cluster nodes -->
        <ServerName>sip:ipsmgw-cluster.example.com;transport=tcp</ServerName>
        <DefaultHandling>0</DefaultHandling>
        <Extension>
            <IncludeRegisterRequest/>
            <IncludeRegisterResponse/>
        </Extension>
    </ApplicationServer>
</InitialFilterCriteria>

Messages

Message Request containing Service Centre PSI

SIP MESSAGE requests that contain the Service Centre PSI should be routed to the IP-SM-GW if the Content-Type Header is equal to application/vnd.3gpp.sms. This caters for SMS submission and notification about the SM-over-IP receiver having memory available (if it used the PSI of the SC).

<?xml version="1.0"?>
<!-- example IFC showing MESSAGE requests to the Service Centre PSI -->
<InitialFilterCriteria>
    <Priority>2</Priority>
    <TriggerPoint>
        <!-- logically, this TriggerPoint matches if the request is a SIP MESSAGE AND the Content-Type is 'application/vnd.3gpp.sms' AND the host part of the Request-URI matches -->
        <ConditionTypeCNF>1</ConditionTypeCNF>
        <SPT>
            <Group>0</Group>
            <Method>MESSAGE</Method>
        </SPT>
        <SPT>
            <Group>1</Group>
            <SIPHeader>
                <Header>Content-Type</Header>
                <Content>application/vnd.3gpp.sms</Content>
            </SIPHeader>
        </SPT>
        <SPT>
            <Group>2</Group>
            <RequestURI>service-centre.example.com</RequestURI>
        </SPT>
    </TriggerPoint>
    <ApplicationServer>
        <!-- The DNS name should resolve to a number of IP-SM-GW cluster nodes -->
        <ServerName>sip:ipsmgw-cluster.example.com;transport=tcp</ServerName>
        <DefaultHandling>0</DefaultHandling>
    </ApplicationServer>
</InitialFilterCriteria>
Note The default SIP transport mechanism for AS communication is UDP. TCP can be specified by appending ;transport=tcp to the IP-SM-GW AS URI configured in the <ServerName> attribute.
Note The ServerName name used is intended to be resolved to a number of IP-SM-GW node addresses through DNS.
Message Request containing a per-node PSI

SIP MESSAGE requests that contain a per-node PSI should be routed to the specific IP-SM-GW node that is holding an Open TCAP Transaction from the SMS-C. These messages have the Content-Type header equal to application/vnd.3gpp.sms. This caters for the sending of a delivery report or a memory available notification (if it used the IP-SM-GW address).

There should be one iFC for each IP-SM-GW cluster node, containing its AS name. This name should resolve to only one AS node.

In 24.341 the specification text does not describe the SIP Message carrying a delivery report or a memory available report as being originating, therefore it is treated as terminating.

This iFC indicates that SIP MESSAGE Requests for the per-node PSI shall only be triggered to the IP-SM-GW in a terminating request. As the SIP MESSAGE request carrying a delivery report has an In-Reply-To header containing a SIP Call-ID related to an earlier SIP MESSAGE transaction, the MESSAGE request containing the delivery report should not traverse other SIP-AS B2BUA’s (as B2BUA’s typically change the Call-ID as a message traverses the IMS).

<?xml version="1.0"?>
<!-- example IFC showing MESSAGE requests to a per node PSI -->
<InitialFilterCriteria>
    <Priority>2</Priority>
    <TriggerPoint>
        <!-- logically, this TriggerPoint matches if the request is a SIP MESSAGE AND the Content-Type is 'application/vnd.3gpp.sms' AND the host part of the Request-URI matches AND (TERMINATING_REGISTERED OR TERMINATING_UNREGISTERED) -->
        <ConditionTypeCNF>1</ConditionTypeCNF>
        <SPT>
            <Group>0</Group>
            <Method>MESSAGE</Method>
        </SPT>
        <SPT>
            <Group>1</Group>
            <SIPHeader>
                <Header>Content-Type</Header>
                <Content>application/vnd.3gpp.sms</Content>
            </SIPHeader>
        </SPT>
        <SPT>
            <Group>2</Group>
            <RequestURI>ipsmgw-node1.example.com</RequestURI>
        </SPT>
        <SPT> <!-- GROUP 3 elements are OR'd together -->
            <Group>3</Group>
            <SessionCase>TERMINATING_REGISTERED</SessionCase>
        </SPT>
        <SPT>
            <Group>3</Group>
            <SessionCase>TERMINATING_UNREGISTERED</SessionCase>
        </SPT>
    </TriggerPoint>
    <ApplicationServer>
        <!-- The DNS name should resolve to a single IP-SM-GW node -->
        <ServerName>sip:ipsmgw-node1.example.com:5060;transport=tcp</ServerName>
        <DefaultHandling>0</DefaultHandling>
    </ApplicationServer>
</InitialFilterCriteria>

INVITE Request containing USSD content

The IP-SM-GW product implements support for USSD over IMS (USSI) interworking with MAP based USSD. This requires INVITE requests containing USSD messages to be routed to the IP-SM-GW.

For originating USSI INVITEs an originating iFC needs to match the USSI INVITE. The following example matches all INVITEs with a Recv-Info header equal to g.3gpp.ussd.

<?xml version="1.0"?>
<!-- example IFC showing USSI INVITEs routing to the IP-SM-GW -->
<InitialFilterCriteria>
    <Priority>2</Priority>
    <TriggerPoint>
        <!-- logically, this TriggerPoint matches if the request is a SIP INVITE AND the Recv-Info header matches the value g.3gpp.ussd -->
        <ConditionTypeCNF>1</ConditionTypeCNF>
        <SPT>
                <ConditionNegated>0</ConditionNegated>
                <Group>0</Group>
                <Method>INVITE</Method>
                <Extension/>
        </SPT>
        <SPT>
                <ConditionNegated>0</ConditionNegated>
                <Group>1</Group>
                <SIPHeader>
                        <Header>Recv-Info</Header>
                        <Content>g.3gpp.ussd</Content>
                </SIPHeader>
                <Extension/>
        </SPT>
    </TriggerPoint>
    <ApplicationServer>
        <!-- The DNS name should resolve to a number of IP-SM-GW cluster nodes -->
        <ServerName>sip:ipsmgw-cluster.example.com;transport=tcp</ServerName>
        <DefaultHandling>0</DefaultHandling>
    </ApplicationServer>
</InitialFilterCriteria>

An alternative to the approach used here is to define a wildcard Public Service Identity for USSD over IMS.

Note The Sentinel VoLTE product typically receives INVITE requests. The iFC used to trigger Sentinel VoLTE should exclude INVITEs matching USSD over IMS requests.

License Requirements

This page gives information about license requirements for running Sentinel IP-SM-GW.

Required License Functions

All services and resource adaptors require the following license function:

License Function Optional Required For

Rhino

No

Capacity

This following sections list the additional license functions required by certain components of Sentinel IP-SM-GW. Some of the components listed below modify the Rhino license function to be only necessary for Activation instead of Capacity.

Note Not all of the components listed below will be present in all Sentinel IP-SM-GW deployments.

Services

Sentinel IP-SM-GW Service

Component Name: sentinel.ipsmgw

License Function Optional Required For

Rhino

No

Activation

Sentinel

No

Activation

Sentinel-IPSMGW

No

Activation

Sentinel-USSI

Yes

Activation

Sentinel Registrar Service

Component Name: sentinel.registrar

License Function Optional Required For

Rhino

No

Activation

Resource Adaptors

SIS-SIP/EasySIP RA

Component Name: SIS-SIP/EasySIP RA

License Function Optional Required For

Rhino-SIS

No

Capacity

Rhino-SIS-SIP

No

Capacity

Rhino-SIS-SIP-External-Service

Yes

Capacity

Rhino-SIS-SIP-Local-Service

Yes

Capacity

CGIN Unified RA

Component Name: CGIN Unified RA

License Function Optional Required For

Rhino-CGIN

No

Activation

Rhino-CGIN-Base

No

Activation

HTTP RA

Component Name: HTTP

License Function Optional Required For

Rhino-HTTP

No

Activation


1. Where <DeliveryOrder> is determined by looking up the Shared Configuration Profile DeliveryOrder attribute and is one of: PS, CS, PS_CS or CS_PS