This document provides a high-level overview of Sentinel.

Topics

Audience and scope

Intended audience

This document is aimed at network operators, systems integrators, and software developers.

Scope

This document provides an overview of the OpenCloud Sentinel product.

Introducing Sentinel

What is Sentinel?

Sentinel is a services platform and a powerful services framework.

Sentinel is a services platform …​

Sentinel is a services platform for real-time session control of TDM, IMS, and Diameter sessions.

sentinel context

Features:

  • is very extensible, flexible, and configurable

  • supports session control for SS7, SIP, and Diameter sessions with a rich set of built-in features

  • provides USSD features such as USSD callback and USSD balance enquiry

  • supports multi-tenancy to support MVNO configurations

  • integrates to one or more Online Charging Systems (OCS)

  • integrates to any CDF that supports the Rf Diameter Protocol via Rf Control RA.

  • supports promotions, which provide a very flexible and configurable interface to Online Charging Systems, supporting OCS offload, special offers, fair-use policy, and OCS failure policy

  • includes an element manager with a web-based user interface for operations and management staff, a RESTful HTTP interface for machine-to-machine management, and an XCAP server framework

  • includes the Sentinel database for subscriber and promotions-related data.

Contact OpenCloud for more information about the databases that can be used by Sentinel.

Note See Sentinel Services and Sentinel Charge for an architectural overview of the Sentinel platform from a Rhino TAS/JAIN SLEE perspective.

Sentinel is a powerful services framework …​

You can also view Sentinel as an open, flexible and powerful services framework. The Sentinel Software Development Kit (SDK) lets you use Sentinel as a framework rather than a fixed feature set product.

sentinel sdk action
Note

For more information see Sentinel SDK

Sentinel Services

Sentinel is a collection of JAIN SLEE services

Sentinel is a services platform for real-time session control of TDM, IMS, and Diameter sessions. It’s built on the Rhino TAS platform.

Sentinel consists of:

  • a set of JAIN SLEE services and Service Building Blocks (SBBs)

  • JAIN SLEE profiles

  • Standard OpenCloud resource adaptors for SS7, SIP, Diameter, HTTP, and CDRs

  • Sentinel-specific resource adaptors for generating unique IDs and correlation IDs.

The following sections present a SLEE-centric architectural overview of Sentinel, and introduce each of the SLEE services that are part of the Sentinel package (for SS7, SIP, and Diameter).

Architecture of a Sentinel service

Each Sentinel service has the same SLEE-based architecture (see the diagram below).

sentinel service arch
SBBs

A Sentinel service consists of:

  • A front-end SBB, which:

    • receives events from the front-end network element (For example, the SS7 front-end service receives SS7 events from an MSC.)

    • controls the session with the front-end network element (For example, the SS7 front-end may arm events in the switch or release the call.)

    • applies an appropriate session plan (For example, the SS7 supports three session plans: one for voice triggers, one for SMS triggers, one for third-party voice triggers.)

    • hosts POJO features and mappers, and has SLEE child relations to SBB features

    • hosts the Sentinel mediation layer, which:

      • presents a Diameter Ro interface to the front-end

      • provides charging methods such as SCUR and IEC

      • provides promotions

    • runs features execution scripts, features and mappers.

  • One or more OCS Driver SBBs, which:

    • integrate Sentinel core (the front-end) with a particular type of OCS

    • have a Diameter Ro interface to the mediation layer, and map Diameter Ro to and from the charging protocol used by the OCS

    • are shared by all services.

Resource adaptors

Each service has resource adaptor bindings for:

  • a resource adaptor for the front-end protocol (For example the SS7 service uses the CGIN resource adaptor to connect to an MSC, and the HTTP resource adaptor for accepting third-party call setup requests.)

  • any protocol used by features (For example, the subscriber data feature uses the OpenCloud DB-Query RA to talk to a relational database. The USSDNotification feature uses the CGIN resource adaptor to send USSD notifications with GSM MAP.)

Profiles

A Sentinel service accesses configuration data stored in these SLEE profiles:

  • platform configuration — configuration data of a Sentinel production install

  • feature configuration — configuration data for each feature

  • feature execution scripts — lookup tables for selecting features execution scripts

  • mapper configuration — lookup tables for selecting mappers

  • promotions scripts — lookup table of scriptable promotions.

Note The profiles are managed using the Sentinel element manager and the Sentinel machine API.

Sentinel Services

Sentinel for SS7

What does it provide?

Sentinel as an SCP

Front-end interfaces

SS7, HTTP

Session plans

Features

Logical Service ID

Sentinel allows Features and Mappers to be dynamically "added to", "removed from" and "replaced" inside Rhino.

This capability is supported by the use of Rhino 2.4.x bindings capability, and the tools that are part of the Sentinel SDK.

The user experience of this capability is improved through the introduction of the Logical Service ID. In essence, the logical service ID creates a "constant" Service ID that is able to be used regardless of changes to features and mappers in the running system.

Motivation for a Logical Service ID

The process of binding new or different version features into Rhino may require new Service Copy components to be created. This is because a running service must not change its components. Rhino supports two approaches to achieve the goal of modifying the code used at runtime.

  1. deactivate the service, then its bindings can be updated in order to make use of new features or mappers or different versions thereof, and re-activating once the bindings changes are complete

  2. creation of a new copy (from the existing active copy). The new copy is now inactive, then its bindings are updated in order to make use of new features or mappers or different versions thereof

The net result is that it is possible for the Service ID that is active to change.

As an example the following timeline can occur

  1. initial installation, the Service ID has name="Sentinel Service", vendor="OpenCloud", version="2.7.0.0"

  2. first bind operation occurs, creating a Service ID with name="Sentinel Service", vendor="OpenCloud", version="2.7.0.0-copy#1". This copy is activated.

  3. some time passes, and new features are introduced. This may create a new Service ID with name="Sentinel Service", vendor="OpenCloud", version="2.7.0.0-copy#2". The earlier copy (-copy#1) is deactivated and the new copy is activated.

Collection of statistics from Rhino is one case that illustrates the requirement for a logical service ID. Collection of statistics from a Service inside Rhino requires a Service ID to be passed in. For arguments sake, let’s assume that statistics collection is running, collecting statistics from the current active version ("2.7.0.0-copy#1). Yet during the timeline above, at some point, the active Service ID is now "2.7.0.0-copy#2".

Therefore unless the collection of statistics is changed to use the new service ID, the statistics being collected will now refer to an inactive copy.

The user experience is improved by making use of Rhino 2.4.x Linked Components capabilities.

In essence a Linked Component is a Rhino SLEE component, that is set up to "point to" another component. Rhino "follows" the links, to resolve them to a non-linked Component. It is inspired by Unix symlinks.

The Sentinel tooling creates two links for each Sentinel Service upon deployment of the service into Rhino. When the binder creates a new copy, the links are updated automatically.

The process is best understood by comparing it with the timeline above

  1. initial installation, the Service ID name="Sentinel Service", vendor="OpenCloud", version="2.7.0.0" is installed, two link components are created

    1. Link Component name="Sentinel Service", vendor="OpenCloud", version="current" points to Service ID name="Sentinel Service", vendor="OpenCloud", version="2.7.0.0"

    2. Link Component name="Sentinel Service", vendor="OpenCloud", version="2.7.0" points to Service ID name="Sentinel Service", vendor="OpenCloud", version="2.7.0.0"

  2. first bind operation occurs, creating a Service ID with name="Sentinel Service", vendor="OpenCloud", version="2.7.0.0-copy#1". This copy is activated.

    1. both link components are updated such that they point to Service ID with name="Sentinel Service", vendor="OpenCloud", version="2.7.0.0-copy#1"

  3. some time passes, and new features are introduced. This may create a new Service ID with name="Sentinel Service", vendor="OpenCloud", version="2.7.0.0-copy#2". The earlier copy (-copy#1) is deactivated and the new copy is activated.

    1. both link components are again updated such that they point to the newly activated copy

Now, when collecting statistics from name="Sentinel Service", vendor="OpenCloud", version="2.7.0" .. the gathered data is always from most recent active version. Therefore collection does not need to be changed as new copies are created and activated.

This approach has similar user experience benefits that are wider than statistics collection, including but not limited to:

  1. SIS compositions - a composition can use a constant Service ID (link) in the composition

  2. SLEE service event firing - directed event firing - an SBB can fire an event to a service link, and Rhino will deliver the event following links

Link components can be changed to point to another place on the fly.

Sentinel for SIP

What does it provide?

Sentinel as a SIP AS

Front-end interfaces

SIP, HTTP

Session plans

Features
Note
Support for re-INVITE

  • Sentinel emits re-INVITEs as a means to check activity liveness and accepts/proxies re-INVITEs mid-session.

  • Sentinel does not (yet) implement the rules outlined in RFC3261 and RFC6141 to update the SDP or participate in SDP negotiation.

Sentinel for Diameter to Diameter

What does it provide?

Diameter to Diameter mediation scenarios

Front-end interfaces

Diameter Ro, HTTP

Session plans

Features

Sentinel Charge

SLEE service that uses Sentinel Charge

The following sections present a SLEE-centric architectural overview of a SLEE service that uses Sentinel Charge. Sentinel Charge provides the Sentinel mediation layer for use by SLEE services (see the diagram below).

sentinel charge arch

SBBs

The service consists of:

  • Custom front-end SBB, which:

    • receives events from the front-end network element

    • controls the session with the front-end network element.

  • Sentinel Charge SBB, which:

    • receives charging requests from the custom front-end SBB

    • hosts POJO features and mappers and has SLEE child relations to SBB features

    • encapsulates the Sentinel mediation layer, which:

      • provides charging methods such as SCUR and IEC

      • provides promotions.

    • runs feature execution scripts, features and mappers

  • One or more OCS Driver SBBs, which:

    • integrate Sentinel core (the front end) with a particular type of OCS

    • have a Diameter Ro interface to the mediation layer, and map Diameter Ro to and from the charging protocol used by the OCS

    • are shared by all services.

Important The resource adaptors and profiles used in Sentinel charge are the same as Sentinel services.

Sentinel Charge

What does it provide?

Sentinel Charge provides the Sentinel mediation layer for use of SLEE services

Front-end interfaces

As required by the custom front end

Features

Inside Sentinel

This page describes the architecture of Sentinel and its relation with the network.

The Architecture

Below is a high-level diagram of Sentinel and its relation with the network.

sentinel high level

The Sentinel platform connects to network elements (Switches, HLRs, GGSNs, and so on) and to one or more online charging system. The sentinel platform consists of:

  • the Sentinel application server (based on the OpenCloud Rhino platform)

  • the Sentinel subscriber database

  • the Sentinel promotions database

  • the Sentinel Element Manager, which provides a web-based interface, a machine-to-machine interface, and an XCAP server framework.

The Sentinel Platform

Below is a high-level diagram of the architecture of the Sentinel platform.

sentinel internal

There are three layers:

  1. Session control — There is a SLEE service per triggering protocol (such as SS7 or Diameter).

  2. Mediation — The mediation layer provides a charging interface to session control and connects to one or more online charging systems. The mediation layer uses Diameter Ro as its internal charging protocol and provides different methods of charging control (such as SCUR or IEC).

  3. OCS — The OCS layer includes a set of OCS drivers that connect Sentinel to different types of OCS; for example, an OCS that exposes a standard Diameter Ro interface, or an OCS that exposes a proprietary charging interface.

The Sentinel application server also includes configuration data related to:

Session Plans

What is a session plan?

A session plan is the set of possible steps that Sentinel may go through when it processes a session. There is a session plan for each type of session that Sentinel supports. Sessions are processed in three phases (see the diagram below). Each phase contains one or more steps.

phases of processing a session
The three phases of processing a session

The term we use for a “step” is a point in session. Sentinel looks up and runs a feature execution script at each point in session. The feature execution script tells Sentinel how to run one or more features. We also, therefore, refer to points in session as features execution points.

Session plans in Sentinel

See the following topics for specific session plans:

Session Plans for the SS7 Service

Sentinel provides three types of session plan for SS7:

SS7 SMS Sessions Initiated via SS7

Purpose

This session plan is triggered on receipt of a CAMEL InitialDP

Feature Endpoint API

sentinel-ss7-spi

The following diagram is a visual representation of the session plan. It shows:

  • the points-in-session where Sentinel will search for a feature execution script to run (the green boxes)

  • the most important points where Sentinel will make a decision about how the session should be processed further (the grey diamonds)

  • the points where Sentinel will delegate to the mediation layer to interact with an OCS (the blue mediation boxes): see Session plans for the Mediation Layer for more details.

The points-in-session for this session plan are described in detail below the diagram.

ss7 sms sp ss7 sms

Feature script execution points

Below are details of these points-in-session:
Note For feature script execution points available in the mediation layer (the dark blue box): see Session Plans for the Mediation Layer for more details.

On initial trigger …​

The three major tasks Sentinel does on the first message of a new session (the initial trigger) are:

  • decide if the new session should be accepted for processing

  • if the new session is accepted, analyse the initial trigger and classify the session

  • do an initial credit check by querying the OCS for this session.

Should the session be accepted?
Point in session Execution point name Feature endpoint Trigger object Trigger activity

Session Accept

DirectAccess_SessionAccept

SentinelSs7StartSessionFeatureEndpoint

DialogOpen (Event)

CCDialog

Session Start

DirectAccess_SessionStart

SentinelSs7StartSessionFeatureEndpoint

DialogOpen (Event)

CCDialog

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse properties of the DialogOpen and determine if the dialog should be accepted, rejected or relayed. Properties of the DialogOpen can also be used to determine the network operator and the session type.

Note Sentinel executes scripts at both execution points and analyses the combined result before deciding if the session must be relayed or refused.
…​ analyse the initial trigger …​
Point in session Execution point name Feature endpoint Trigger object Trigger activity

Network Pre Initial Credit Check

DirectAccess_NetworkPreCreditCheck

SentinelSs7InitialTriggerFeatureEndpoint

CAP3InitialDPSMSArg (CGIN arg pojo)

CCDialog

Session Pre Initial Credit Check

DirectAccess_SessionPreCreditCheck

SentinelSs7InitialTriggerFeatureEndpoint

CAP3InitialDPSMSArg (CGIN arg pojo)

CCDialog

Subscriber Pre Initial Credit Check

DirectAccess_SubscriberPreCreditCheck

SentinelSs7InitialTriggerFeatureEndpoint

CAP3InitialDPSMSArg (CGIN arg pojo)

CCDialog

Suggested role/purpose of features that run at this feature script execution point

Features that run at these execution points should analyse the InitialDP and classify this session. The three execution points allow you to select feature execution scripts in phases, as you further classify details of the session. For example: the first execution point can select a feature execution script that is particular to the network operator; the next execution point can select a feature execution script that is particular to the session type; and the last execution point can select a feature execution script that is particular to the plan and subscription ids.

Note Sentinel executes scripts at all three execution points and analyses the combined result before deciding if the session should end.
…​ take actions based on the outcome of the initial credit check …​
Point in session Execution point name Feature endpoint Trigger Object Trigger Activity

Initial Credit Allocated

DirectAccess_CreditAllocatedPostCC

SentinelSs7InitialTriggerFeatureEndpoint

CAP3InitialDPSMSArg (CGIN arg pojo)

CCDialog

Initial Credit Limit Reached

DirectAccess_CreditLimitReachedPostCC

SentinelSs7InitialTriggerFeatureEndpoint

CAP3InitialDPSMSArg (CGIN arg pojo)

CCDialog

Initial Control Not Required

DirectAccess_ControlNotRequiredPostCC

SentinelSs7InitialTriggerFeatureEndpoint

CAP3InitialDPSMSArg (CGIN arg pojo)

CCDialog

Initial Credit Failure

DirectAccess_OCSFailurePostCC

SentinelSs7InitialTriggerFeatureEndpoint

CAP3InitialDPSMSArg (CGIN arg pojo)

CCDialog

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session based on the outcome of the initial credit check.

Monitoring the session …​

Sentinel will confirm the credit used, or make a refund, as required. There are no mid session feature script execution points for this session plan.

Ending the session …​

A session may end for many reasons (a subscriber hangs up a call, there is no credit and so on).

…​ on session end
Point in session Execution point name Feature endpoint Trigger object Trigger activity

End Session

EndSession

SentinelSs7EndSessionFeatureEndpoint

CAP3InitialDPSMSArg (CGIN arg pojo)

CCDialog

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour, such as sending notifications, when a session ends.

SS7 Sessions Initiated via SS7

Purpose

This session plan is triggered on receipt of a CAMEL InitialDP

Feature Endpoint API

sentinel-ss7-spi

The following diagram is a visual representation of the session plan. It shows:

  • the points-in-session where Sentinel will search for a feature execution script to run (the green boxes)

  • the most important points where Sentinel will make a decision about how the session should be processed further (the grey diamonds)

  • the points where Sentinel will delegate to the mediation layer to interact with an OCS (the blue mediation boxes) — see Session plans for the Mediation Layer for more details.

The points-in-session for this session plan are described in detail below the diagram.

ss7 sp ss7

Feature script execution points

Below are details of these points-in-session:
Note For feature script execution points available in the mediation layer (the dark blue box) see: Sentinel Mediation Layer.

On initial trigger …​

The three major tasks Sentinel does on the first message of a new session (the initial trigger) are:

  • decide if the new session should be accepted for processing

  • if the new session is accepted, analyse the initial trigger and classify the session

  • do an initial credit check by querying the OCS for this session.

Should the session be accepted?
Point in session Execution point name Feature endpoint Trigger object Trigger activity

Session Accept

DirectAccess_SessionAccept

SentinelSs7StartSessionFeatureEndpoint

DialogOpen (Event)

CCDialog

Session Start

DirectAccess_SessionStart

SentinelSs7StartSessionFeatureEndpoint

DialogOpen (Event)

CCDialog

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse properties of the DialogOpen and determine if the dialog should be accepted, rejected or relayed. Properties of the DialogOpen can also be used to determine the network operator and the session type.

…​ analyse the initial trigger …​
Point in Session Execution Point Name Feature Endpoint Trigger Object Trigger Activity

Network Pre Initial Credit Check

DirectAccess_NetworkPreCreditCheck

SentinelSs7InitialTriggerFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Session Pre Initial Credit Check

DirectAccess_SessionPreCreditCheck

SentinelSs7InitialTriggerFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Subscriber Pre Initial Credit Check

DirectAccess_SubscriberPreCreditCheck

SentinelSs7InitialTriggerFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse the InitialDP and classify this session. The three execution points allow you to select feature execution scripts in phases, as you further classify details of the session. For example: the first execution point can select a feature execution script that is particular to the network operator; the next execution point can select a feature execution script that is particular to the session type; and the last execution point can select a feature execution script that is particular to the plan and subscription ids.

…​ take actions based on the outcome of the initial credit check …​
Point in Session Execution Point Name Feature Endpoint Trigger Object Trigger Activity

Initial Credit Allocated

DirectAccess_CreditAllocatedPostCC

SentinelSs7InitialTriggerFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Initial Credit Limit Reached

DirectAccess_CreditLimitReachedPostCC

SentinelSs7InitialTriggerFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Initial Control Not Required

DirectAccess_ControlNotRequiredPostCC

SentinelSs7InitialTriggerFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Initial Credit Failure

DirectAccess_OCSFailurePostCC

SentinelSs7InitialTriggerFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session based on the outcome of the initial credit check.

…​ take actions based on the outcome of the B-party response …​
Point in session Execution point name Feature endpoint Trigger Object Trigger Activity

B Party Not Established

DirectAccess_BPartyNotEstablished

SentinelSs7InitialTriggerFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

B Party Not Established Post Credit Check

DirectAccess_BPartyNotEstablished_PostCC

SentinelSs7InitialTriggerFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Suggested Role/Purpose of features that run at this feature script execution point

Features that run in the B Party Not Established execution point can instruct the service to attempt a follow on call via the followOnCall() method of the SentinelSs7InitialTriggerFeatureEndpoint.

Monitoring the session …​

Sentinel monitors the session by exchanging messages with the switch and updating the credit allocated for this session with the OCS.

…​ before each credit update …​
Point in Session Execution Point Name Feature Endpoint Trigger Object Trigger Activity

Mid Session Pre Credit Check

MidSession

SentinelSs7MidSessionFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour (related to SS7) before Sentinel defers to the mediation layer for a subsequent credit update.

Ending the session …​

A session may end for many reasons (a subscriber hangs up a call, there is no credit and so on).

…​ on session end
Point in Session Execution Point Name Feature Endpoint Trigger Object Trigger Activity

End Session

EndSession

SentinelSs7EndSessionFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour, such as sending notifications, when a session ends.

SS7 Sessions Initiated Via Third Party

Purpose

This session plan is triggered for a Voice session initiated via 3rd party call setup. Sentinel provides an HTTP interface for 3rd party call setup, so this session plan is triggered on receipt of an HTTP GET or HTTP POST request.

Feature Endpoint API

sentinel-ss7-spi

The following diagram is a visual representation of the session plan. It shows:

  • the points-in-session where Sentinel will search for a feature execution script to run (the green boxes)

  • the most important points where Sentinel will make a decision about how the session should be processed further (the grey diamonds)

  • the points where Sentinel will delegate to the mediation layer to interact with an OCS (the blue mediation boxes): see Session Plans for the Mediation Layer for more details.

The points-in-session for this session plan are described in detail below the diagram.

ss7 sp http

Feature script execution points

Below are details of these points-in-session:
Tip For feature script execution points available in the mediation layer (the dark blue box): see Session Plans for the Mediation Layer.

On initial trigger …​

The three major tasks Sentinel does on the first message of a new session (the initial trigger) are:

  • decide if the new session should be accepted for processing

  • if the new session is accepted, analyse the initial trigger and classify the session

  • do an initial credit check by querying the OCS for this session.

Should the session be accepted?
Point in Session Execution Point Name Feature Endpoint Trigger Object Trigger Activity

Session Accept

ThirdPartyAccess_SessionAccept

SentinelSs7StartSessionFeatureEndpoint

HttpRequest (Event)

IncomingHttpRequestActivity

Session Start

ThirdPartyAccess_SessionStart

SentinelSs7StartSessionFeatureEndpoint

HttpRequest (Event)

IncomingHttpRequestActivity

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse properties of the incoming HTTP request and determine if the request for a third part call setup should be accepted, or rejected. Properties of the HTTP request can also be used to determine the network operator. If the session is accepted, then Sentinel generates a CAP2InitialDPArg that corresponds to HTTP request. Subsequent features run within the context of the CAP2InitialDPArg.

…​ analyse the initial trigger …​
Point in Session Execution Point Name Feature Endpoint Trigger Object Trigger Activity

Network Pre Initial Credit Check

ThirdPartyAccess_NetworkPreCreditCheck

SentinelSs7InitialTriggerFeatureEndpoint

CAP2InitialDPArg (CGIN arg pojo)

IncomingHttpRequestActivity

Session Pre Initial Credit Check

ThirdPartyAccess_SessionPreCreditCheck

SentinelSs7InitialTriggerFeatureEndpoint

CAP2InitialDPArg (CGIN arg pojo)

IncomingHttpRequestActivity

Subscriber Pre Initial Credit Check

ThirdPartyAccess_SubscriberPreCreditCheck

SentinelSs7InitialTriggerFeatureEndpoint

CAP2InitialDPArg (CGIN arg pojo)

IncomingHttpRequestActivity

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse the CAP2InitialDPArg and classify this session. The three execution points allow you to select feature execution scripts in phases, as you further classify details of the session. For example: the first execution point can select a feature execution script that is particular to the network operator; the next execution point can select a feature execution script that is particular to the session type; and the last execution point can select a feature execution script that is particular to the plan and subscription ids.

…​ take actions based on the outcome of the initial credit check …​
Point in Session Execution Point Name Feature Endpoint Trigger Object Trigger Activity

Initial Credit Allocated

ThirdPartyAccess_CreditAllocatedPostCC

SentinelSs7InitialTriggerFeatureEndpoint

CAP2InitialDPArg (CGIN arg pojo)

IncomingHttpRequestActivity

Initial Credit Limit Reached

ThirdPartyAccess_CreditLimitReachedPostCC

SentinelSs7InitialTriggerFeatureEndpoint

CAP2InitialDPArg (CGIN arg pojo)

IncomingHttpRequestActivity

Initial Control Not Required

ThirdPartyAccess_ControlNotRequiredPostCC

SentinelSs7InitialTriggerFeatureEndpoint

CAP2InitialDPArg (CGIN arg pojo)

IncomingHttpRequestActivity

Initial Credit Failure

ThirdPartyAccess_OCSFailurePostCC

SentinelSs7InitialTriggerFeatureEndpoint

CAP2InitialDPArg (CGIN arg pojo)

IncomingHttpRequestActivity

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session based on the outcome of the initial credit check.

Monitoring the session …​

Sentinel monitors the session by exchanging messages with the switch and updating the credit allocated for this session with the OCS.

…​before each credit update…​
Point in Session Execution Point Name Feature Endpoint Trigger Object Trigger Activity

Mid Session Pre Credit Check

MidSession

SentinelSs7MidSessionFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour(related to SS7) before Sentinel defers to the mediation layer for a subsequent credit update.

Ending the session …​

A session may end for many reasons (a subscriber hangs up a call, there is no credit and so on).

…​ on session end
Point in Session Execution Point Name Feature Endpoint Trigger Object Trigger Activity

End Session

EndSession

SentinelSs7EndSessionFeatureEndpoint

CCInitialDPArg (CGIN arg pojo)

CCDialog

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour, such as sending notifications, when a session ends.

Session Plans for the SIP Service

Sentinel provides a number of types of session plan for SIP:

SIP Sessions Initiated via SIP INVITE

Purpose

This session plan is triggered on receipt of a new SIP INVITE.

Feature Endpoint API

sentinel-sip-spi (SentinelSipMultiLegFeatureEndpoint)

The following diagram is a visual representation of the session plan. It shows:

  • the points-in-session where Sentinel will search for a feature execution script to run (the green boxes)

  • the most important points where Sentinel will make a decision about how the session should be processed further (the grey diamonds)

  • the points where Sentinel will delegate to the mediation layer to interact with an OCS (the blue mediation boxes) — see: Session plans for the Mediation Layer for more details.

The session plan is multi-leg aware; for example, within a multi-leg communication session, some of the feature script execution points may be run within the context of a particular ‘leg’. The points-in-session for this session plan are described in detail below the diagram.

sip invite session plan
Figure 1. Session Plan for an SIP INVITE Request

Feature script execution points

Below are details of these points-in-session:
Note

For feature script execution points available in the mediation layer (the dark blue box) see: Sentinel Mediation Layer.

The feature endpoint for all sip execution points is SentinelSipMultiLegFeatureEndpoint

On initial trigger …​

The three major tasks Sentinel does on the first message of a new session (the initial trigger) are:

  • decide if the new session should be accepted for processing

  • if the new session is accepted, analyse the initial trigger and classify the session

  • do an initial credit check by querying the OCS for this session.

Should the session be accepted?
Point in session Execution point name Trigger object Trigger activity

Session Accept

SipAccess_SessionAccept

SipRequest

SipSession

Session Start

SipAccess_SessionStart

SipRequest

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse the incoming INVITE and decide if the new session should be accepted, or rejected. Properties of the INVITE can also be used to determine the network operator and the session type.

…​ analyse the initial trigger …​
Point in Session Execution Point Name Trigger Object Trigger Activity

Network Check

SipAccess_NetworkPreCreditCheck

SipRequest

SipSession

Session Check

SipAccess_SessionPreCreditCheck

SipRequest

SipSession

Subscriber Check

SipAccess_SubscriberPreCreditCheck

SipRequest

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse the INVITE and classify this session. The three execution points allow you to select feature execution scripts in phases, as you further classify details of the session. For example: the first execution point can select a feature execution script that is particular to the network operator; the next execution point can select a feature execution script that is particular to the session type; and the last execution point can select a feature execution script that is particular to the plan and subscription ids.

…​ take actions based on the outcome of the initial credit check …​
Point in Session Execution Point Name Trigger Object Trigger Activity

Initial Credit Allocated

SipAccess_CreditAllocatedPostCC

CCA

SipSession

Initial Credit Limit Reached

SipAccess_CreditLimitReachedPostCC

CCA

SipSession

Initial Control Not Required

SipAccess_ControlNotRequiredPostCC

CCA

SipSession

Initial Control Failure

SipAccess_OCSFailurePostCC

CCA

SipSession

Initial Control Reauthorise

SipAccess_ChargingReauth

RAR

SipSession

Initial Control Abort

SipAccess_ChargingAbort

ASR

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session based on the outcome of the initial credit check.

Monitoring the session …​

Sentinel monitors the session by exchanging messages with the S-CSCF and updating the credit allocated for this session with the OCS. Feature script execution points within the session monitoring phase play two roles:

  • execution points that are charging-centric (left-hand side). These feature script execution points run when the session needs more charging.

  • execution points that are signalling-centric (right-hand side). These feature script execution points run for SIP messages on each leg in a multi-leg session.

…​ take actions based on the outcome of an update credit check …​
Point in Session Execution Point Name Trigger Object Trigger Activity

Mid Session Credit Allocated

SipMidSession_CreditAllocatedPostCC

CCA

SipSession

Mid Session Credit Limit Reached

SipMidSession_CreditLimitReachedPostCC

CCA

SipSession

Mid Session Control Failure

SipMidSession_OCSFailurePostCC

CCA

SipSession

Mid Session Control Reauthorise

SipMidSession_ChargingReauth

RAR

SipSession

Mid Session Control Abort

SipMidSession_ChargingAbort

ASR

SipSession

Mid Session Credit Finalised

CreditFinalised

CCA

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session based on the outcome of an update credit check.

…​ as each leg is set up …​
Point in session Execution point name Trigger object Trigger activity

Setup Sip Request

SipAccess_PartyRequest

SipRequest

SipSession

Setup Sip Response

SipAccess_PartyResponse

SipResponse

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen as a new leg in a multi-leg session is set up.

…​ as each leg continues …​
Point in session Execution point name Trigger object Trigger activity

Mid Session Sip Request

SipMidSession_PartyRequest

SipRequest

SipSession

Mid Session Sip Response

SipMidSession_PartyResponse

SipResponse

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this leg, and the multi-leg session, as the leg proceeds.

…​ on a SUBSCRIBE request …​
Point in session Execution point name Trigger object Trigger activity

Subscription Request

SubscriptionSipRequest

SipRequest

SipSession

Subscription Response

SubscriptionSipResponse

SipResponse

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at these execution points should decide what will happen to this leg, its usages, charging, and the multi-leg session, as the leg proceeds.

…​ on an out-of-dialog SIP transaction …​
Point in session Execution point name Trigger object Trigger activity

Transaction Request

SipTransaction_Request

SipRequest

SipSession

Transaction Response

SipTransaction_Response

SipResponse

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at these execution points should decide what will happen to this leg, its usages, charging, and the multi-leg session, as the leg proceeds.

…​ …​ as each leg ends
Point in session Execution point name Trigger object Trigger activity

Leg End

SipLegEnd

LegEndEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen as the leg ends.

Ending the session …​

A session may end for many reasons (a subscriber hangs up a call, there is no credit and so on).

…​ on session end
Point in Session Execution Point Name Trigger Object Trigger Activity

End Session

SipEndSession

EndSessionEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour, such as sending notifications, when a session ends.

At any time …​

There are a number of feature script execution points that may be triggered at ant time within the lifetime of a session.

As timers expire
Point in Session Execution Point Name Trigger Object Trigger Activity

Service Timer

SipAccess_ServiceTimer

TimerEvent

NullActivity

Suggested role/purpose of features that run at this feature script execution point

Service timers that are not configured to invoke a feature directly trigger this feature script execution point. Features that run at this execution point should decide what will happen to this session when the service timer expires.

Tip See Sentinel Service Timer Provider for more details.
If instruction execution fails
Point in Session Execution Point Name Trigger Object Trigger Activity

Instruction Execution Failure

SipInstructionExecutionFailure

InstructionExecutionFailedEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session when a Leg or Charging Manager instruction failed to execute successfully.

As extension events are processed
Point in Session Execution Point Name Trigger Object Trigger Activity

Feature Extension Event

SipAccess_FeatureExtentionEvent

Object

Extension Activity

Suggested role/purpose of features that run at this feature script execution point

Features that are invoked directly by Sentinel run in the context of the this feature script execution point.

Tip See Sentinel Feature Extension Events and Sentinel Service Timer Provider to learn how a feature can be invoked directly.

SIP Sessions Initiated Via Third Party

Purpose

This session plan is triggered for a Voice session initiated via 3rd party call setup. Sentinel provides an HTTP interface for 3rd party call setup, so this session plan is triggered on receipt of an HTTP GET or HTTP POST request.

Feature Endpoint API

sentinel-sip-spi (SentinelSipMultiLegFeatureEndpoint)

The following diagram is a visual representation of the session plan. It shows:

  • the points-in-session where Sentinel will search for a feature execution script to run (the green boxes)

  • the most important points where Sentinel will make a decision about how the session should be processed further (the grey diamonds)

  • the points where Sentinel will delegate to the mediation layer to interact with an OCS (the blue mediation boxes) — see Session plans for the Mediation Layer for more details.

The session plan is multi-leg aware; for example, within a multi-leg communication session, some of the feature script execution points may be run within the context of a particular ‘leg’. The points-in-session for this session plan are described in detail below the diagram.

sip http session plan
Figure 2. Session Plan for Third Party Call Setup Request via HTTP

Feature script execution points

Below are details of these points-in-session:
Note

For feature script execution points available in the mediation layer (the dark blue box) see: Sentinel Mediation Layer.

The feature endpoint for all sip execution points is SentinelSipMultiLegFeatureEndpoint

On initial trigger …​

The three major tasks Sentinel does on the first message of a new session (the initial trigger) are:

  • decide if the new session should be accepted for processing

  • if the new session is accepted, analyse the initial trigger and classify the session

  • do an initial credit check by querying the OCS for this session.

Should the session be accepted?
Point in session Execution point name Trigger object Trigger activity

Session Accept

SipThirdPartyAccess_SessionAccept

HttpRequest (Event)

IncomingHttpRequestActivity

Session Start

SipThirdPartyAccess_SessionAccept

HttpRequest (Event)

IncomingHttpRequestActivity

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse properties of the incoming HTTP request and determine if the request for a third-party session setup should be accepted, or rejected. Properties of the HTTP request can also be used to determine the network operator. If the session is accepted, then Sentinel generates an INVITE that corresponds to HTTP request. Subsequent features run within the context of the INVITE.

…​ analyse the initial trigger …​
Point in Session Execution Point Name Trigger Object Trigger Activity

Network Check

SipThirdPartyAccess_NetworkPreCreditCheck

HttpRequest (Event)

IncomingHttpRequestActivity

Session Check

SipThirdPartyAccess_SessionPreCreditCheck

HttpRequest (Event)

IncomingHttpRequestActivity

Subscriber Check

SipThirdPartyAccess_SubscriberCheck

HttpRequest (Event)

IncomingHttpRequestActivity

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse the INVITE and classify this session. The three execution points allow you to select feature execution scripts in phases, as you further classify details of the session. For example: the first execution point can select a feature execution script that is particular to the network operator; the next execution point can select a feature execution script that is particular to the session type; and the last execution point can select a feature execution script that is particular to the plan and subscription ids.

…​ take actions based on the outcome of the initial credit check …​
Point in Session Execution Point Name Trigger Object Trigger Activity

Initial Credit Allocated

SipAccess_CreditAllocatedPostCC

CCA

SipSession

Initial Credit Limit Reached

SipAccess_CreditLimitReachedPostCC

CCA

SipSession

Initial Control Not Required

SipAccess_ControlNotRequiredPostCC

CCA

SipSession

Initial Control Failure

SipAccess_OCSFailurePostCC

CCA

SipSession

Initial Control Reauthorise

SipAccess_ChargingReauth

RAR

SipSession

Initial Control Abort

SipAccess_ChargingAbort

ASR

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session based on the outcome of the initial credit check.

Monitoring the session …​

Sentinel monitors the session by exchanging messages with the S-CSCF and updating the credit allocated for this session with the OCS. Feature script execution points within the session monitoring phase play two roles:

  • execution points that are charging-centric (left-hand side). These feature script execution points run when the session needs more charging.

  • execution points that are signalling-centric (right-hand side). These feature script execution points run for SIP messages on each leg in a multi-leg session.

…​ take actions based on the outcome of an update credit check …​
Point in Session Execution Point Name Trigger Object Trigger Activity

Mid Session Credit Allocated

SipMidSession_CreditAllocatedPostCC

CCA

SipSession

Mid Session Credit Limit Reached

SipMidSession_CreditLimitReachedPostCC

CCA

SipSession

Mid Session Control Failure

SipMidSession_OCSFailurePostCC

CCA

SipSession

Mid Session Control Reauthorise

SipMidSession_ChargingReauth

RAR

SipSession

Mid Session Control Abort

SipMidSession_ChargingAbort

ASR

SipSession

Mid Session Credit Finalised

CreditFinalised

CCA

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session based on the outcome of an update credit check.

…​ as each leg is set up …​
Point in session Execution point name Trigger object Trigger activity

Setup Sip Request

SipAccess_PartyRequest

SipRequest

SipSession

Setup Sip Response

SipAccess_PartyResponse

SipResponse

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen as a new leg in a multi-leg session is set up.

…​ as each leg continues …​
Point in session Execution point name Trigger object Trigger activity

Mid Session Sip Request

SipMidSession_PartyRequest

SipRequest

SipSession

Mid Session Sip Response

SipMidSession_PartyResponse

SipResponse

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this leg, and the multi-leg session, as the leg proceeds.

…​ on a SUBSCRIBE request …​
Point in session Execution point name Trigger object Trigger activity

Subscription Request

SubscriptionSipRequest

SipRequest

SipSession

Subscription Response

SubscriptionSipResponse

SipResponse

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at these execution points should decide what will happen to this leg, its usages, charging, and the multi-leg session, as the leg proceeds.

…​ on an out-of-dialog SIP transaction …​
Point in session Execution point name Trigger object Trigger activity

Transaction Request

SipTransaction_Request

SipRequest

SipSession

Transaction Response

SipTransaction_Response

SipResponse

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at these execution points should decide what will happen to this leg, its usages, charging, and the multi-leg session, as the leg proceeds.

…​ …​ as each leg ends
Point in session Execution point name Trigger object Trigger activity

Leg End

SipLegEnd

LegEndEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen as the leg ends.

Ending the session …​

A session may end for many reasons (a subscriber hangs up a call, there is no credit and so on).

…​ on session end
Point in Session Execution Point Name Trigger Object Trigger Activity

End Session

SipEndSession

EndSessionEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour, such as sending notifications, when a session ends.

At any time …​

There are a number of feature script execution points that may be triggered at ant time within the lifetime of a session.

As timers expire
Point in Session Execution Point Name Trigger Object Trigger Activity

Service Timer

SipAccess_ServiceTimer

TimerEvent

NullActivity

Suggested role/purpose of features that run at this feature script execution point

Service timers that are not configured to invoke a feature directly trigger this feature script execution point. Features that run at this execution point should decide what will happen to this session when the service timer expires.

Tip See Sentinel Service Timer Provider for more details.
If instruction execution fails
Point in Session Execution Point Name Trigger Object Trigger Activity

Instruction Execution Failure

SipInstructionExecutionFailure

InstructionExecutionFailedEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session when a Leg or Charging Manager instruction failed to execute successfully.

As extension events are processed
Point in Session Execution Point Name Trigger Object Trigger Activity

Feature Extension Event

SipAccess_FeatureExtentionEvent

Object

Extension Activity

Suggested role/purpose of features that run at this feature script execution point

Features that are invoked directly by Sentinel run in the context of the this feature script execution point.

Tip See Sentinel Feature Extension Events and Sentinel Service Timer Provider to learn how a feature can be invoked directly.

SIP sessions initiated via SIP SUBSCRIBE

Purpose

This session plan is triggered on receipt of a dialog initiating SIP SUBSCRIBE.

Feature Endpoint API

sentinel-sip-spi (SentinelSipMultiLegFeatureEndpoint)

The following diagram is a visual representation of the session plan. It shows:

  • the points-in-session where Sentinel will search for a feature execution script to run (the green boxes)

  • the most important points where Sentinel will make a decision about how the session should be processed further (the grey diamonds)

  • the points where Sentinel will delegate to the mediation layer to interact with an OCS (the blue mediation boxes) — see: Session plans for the Mediation Layer for more details.

The session plan is multi-leg aware; for example, within a multi-leg communication session, some of the feature script execution points may be run within the context of a particular ‘leg’. The points-in-session for this session plan are described in detail below the diagram.

sip subscribe session plan
Figure 3. Session Plan For a SIP SUBSCRIBE Request

Feature script execution points

Below are details of these points-in-session:
Note

For feature script execution points available in the mediation layer (the dark blue box) see: Sentinel Mediation Layer.

The feature endpoint for all sip execution points is SentinelSipMultiLegFeatureEndpoint

On initial trigger …​

The three major tasks Sentinel does on the first message of a new session (the initial trigger) are:

  • decide if the new session should be accepted for processing

  • if the new session is accepted, analyse the initial trigger and classify the session

  • do an initial credit check by querying the OCS for this session.

Should the session be accepted?
Point in session Execution point name Trigger object Trigger activity

Session Accept

SubscriptionAccept

SipRequest

SipSession

Session Start

SubscriptionStart

SipRequest

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse the incoming SUBSCRIBE and decide if the new session should be accepted, or rejected. Properties of the SUBSCRIBE can also be used to determine the network operator and the session type.

…​ analyse the initial trigger …​
Point in Session Execution point name Trigger Object Trigger Activity

Network Check

SubscriptionNetworkCheck

SipRequest

SipSession

Session Check

SubscriptionSessionCheck

SipRequest

SipSession

Subscriber Check

SubscriptionSubscriberCheck

SipRequest

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse the SUBSCRIBE and classify this session. The three execution points allow you to select feature execution scripts in phases, as you further classify details of the session. For example: the first execution point can select a feature execution script that is particular to the network operator; the next execution point can select a feature execution script that is particular to the session type; and the last execution point can select a feature execution script that is particular to the plan and subscription ids.

…​ take actions based on the outcome of the initial credit check …​
Point in Session Execution Point Name Trigger Object Trigger Activity

Initial Credit Allocated

SipAccess_CreditAllocatedPostCC

CCA

SipSession

Initial Credit Limit Reached

SipAccess_CreditLimitReachedPostCC

CCA

SipSession

Initial Control Not Required

SipAccess_ControlNotRequiredPostCC

CCA

SipSession

Initial Control Failure

SipAccess_OCSFailurePostCC

CCA

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session based on the outcome of the initial credit check.

Monitoring the session …​

Sentinel monitors the session by exchanging messages with the S-CSCF and updating the credit allocated for this session with the OCS. Feature script execution points within the session monitoring phase play two roles:

  • execution points that are charging-centric (left-hand side). These feature script execution points run when the session needs more charging.

  • execution points that are signalling-centric (right-hand side). These feature script execution points run for SIP messages on each leg in a multi-leg session.

…​ take actions based on the outcome of an update credit check …​
Point in Session Execution Point Name Trigger Object Trigger Activity

Mid Session Credit Allocated

SipMidSession_CreditAllocatedPostCC

CCA

SipSession

Mid Session Credit Limit Reached

SipMidSession_CreditLimitReachedPostCC

CCA

SipSession

Mid Session Control Failure

SipMidSession_OCSFailurePostCC

CCA

SipSession

Mid Session Credit Finalised

CreditFinalised

CCA

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session based on the outcome of the credit control interaction (e.g requested refund or credit finalisation).

…​ on a SUBSCRIBE request …​
Point in session Execution point name Trigger object Trigger activity

Subscription Request

SubscriptionSipRequest

SipRequest

SipSession

Subscription Response

SubscriptionSipResponse

SipResponse

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at these execution points should decide what will happen to this leg, its usages, charging, and the multi-leg session, as the leg proceeds.

…​ …​ as each leg ends
Point in session Execution point name Trigger object Trigger activity

Leg End

SipLegEnd

LegEndEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen as the leg ends.

Ending the session …​

A session may end for many reasons (a subscriber hangs up a call, there is no credit and so on).

…​ on session end
Point in Session Execution Point Name Trigger Object Trigger Activity

End Session

SipEndSession

EndSessionEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour, such as sending notifications, when a session ends.

At any time …​

There are a number of feature script execution points that may be triggered at ant time within the lifetime of a session.

As timers expire
Point in Session Execution Point Name Trigger Object Trigger Activity

Service Timer

SipAccess_ServiceTimer

TimerEvent

NullActivity

Suggested role/purpose of features that run at this feature script execution point

Service timers that are not configured to invoke a feature directly trigger this feature script execution point. Features that run at this execution point should decide what will happen to this session when the service timer expires.

Tip See Sentinel Service Timer Provider for more details.
If instruction execution fails
Point in Session Execution Point Name Trigger Object Trigger Activity

Instruction Execution Failure

SipInstructionExecutionFailure

InstructionExecutionFailedEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session when a Leg or Charging Manager instruction failed to execute successfully.

As extension events are processed
Point in Session Execution Point Name Trigger Object Trigger Activity

Feature Extension Event

SipAccess_FeatureExtentionEvent

Object

Extension Activity

Suggested role/purpose of features that run at this feature script execution point

Features that are invoked directly by Sentinel run in the context of the this feature script execution point.

Tip See Sentinel Feature Extension Events and Sentinel Service Timer Provider to learn how a feature can be invoked directly.

SIP sessions initiated via Out of Dialog Transaction

Purpose

This session plan is triggered on receipt of a out of dialog SIP Request.

Feature Endpoint API

sentinel-sip-spi (SentinelSipMultiLegFeatureEndpoint)

The following diagram is a visual representation of the session plan. It shows:

  • the points-in-session where Sentinel will search for a feature execution script to run (the green boxes)

  • the most important points where Sentinel will make a decision about how the session should be processed further (the grey diamonds)

  • the points where Sentinel will delegate to the mediation layer to interact with an OCS (the blue mediation boxes) — see: Session plans for the Mediation Layer for more details.

The session plan is multi-leg aware; for example, within a multi-leg communication session, some of the feature script execution points may be run within the context of a particular ‘leg’. The points-in-session for this session plan are described in detail below the diagram.

sip txn session plan
Figure 4. Session Plan for an Out-of-Dialog SIP Transaction

Feature script execution points

Below are details of these points-in-session:
Note

For feature script execution points available in the mediation layer (the dark blue box) see: Sentinel Mediation Layer.

The feature endpoint for all sip execution points is SentinelSipMultiLegFeatureEndpoint

On initial trigger …​

The three major tasks Sentinel does on the first message of a new session (the initial trigger) are:

  • decide if the new session should be accepted for processing

  • if the new session is accepted, analyse the initial trigger and classify the session

  • do an initial credit check by querying the OCS for this session.

Should the session be accepted?
Point in session Execution point name Trigger object Trigger activity

Session Accept

SipTransaction_Accept

SipRequest

SipSession

Session Start

SipTransaction_Start

SipRequest

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse the incoming initial request and decide if the new session should be accepted, or rejected. Properties of the request can also be used to determine the network operator and the session type.

…​ analyse the initial trigger …​
Point in Session Execution point name Trigger Object Trigger Activity

Network Check

SipTransaction_NetworkCheck

SipRequest

SipSession

Session Check

SipTransaction_SessionCheck

SipRequest

SipSession

Subscriber Check

SipTransaction_SubscriberCheck

SipRequest

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse the request and classify this session. The three execution points allow you to select feature execution scripts in phases, as you further classify details of the session. For example: the first execution point can select a feature execution script that is particular to the network operator; the next execution point can select a feature execution script that is particular to the session type; and the last execution point can select a feature execution script that is particular to the plan and subscription ids.

…​ take actions based on the outcome of the initial credit check …​
Point in Session Execution Point Name Trigger Object Trigger Activity

Initial Credit Allocated

SipAccess_CreditAllocatedPostCC

CCA

SipSession

Initial Credit Limit Reached

SipAccess_CreditLimitReachedPostCC

CCA

SipSession

Initial Control Not Required

SipAccess_ControlNotRequiredPostCC

CCA

SipSession

Initial Control Failure

SipAccess_OCSFailurePostCC

CCA

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session based on the outcome of the initial credit check.

Monitoring the session …​

Sentinel monitors the session by exchanging messages with the S-CSCF and updating the credit allocated for this session with the OCS. Feature script execution points within the session monitoring phase play two roles:

  • execution points that are charging-centric (left-hand side). These feature script execution points run when the session needs more charging.

  • execution points that are signalling-centric (right-hand side). These feature script execution points run for SIP messages on each leg in a multi-leg session.

…​ take actions based on the outcome of an update credit check …​
Point in Session Execution Point Name Trigger Object Trigger Activity

Mid Session Credit Allocated

SipMidSession_CreditAllocatedPostCC

CCA

SipSession

Mid Session Credit Limit Reached

SipMidSession_CreditLimitReachedPostCC

CCA

SipSession

Mid Session Control Failure

SipMidSession_OCSFailurePostCC

CCA

SipSession

Mid Session Credit Finalised

CreditFinalised

CCA

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session based on the outcome of the credit control interaction (e.g requested refund or credit finalisation).

…​ on an out-of-dialog SIP transaction …​
Point in session Execution point name Trigger object Trigger activity

Transaction Request

SipTransaction_Request

SipRequest

SipSession

Transaction Response

SipTransaction_Response

SipResponse

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at these execution points should decide what will happen to this leg, its usages, charging, and the multi-leg session, as the leg proceeds.

…​ …​ as each leg ends
Point in session Execution point name Trigger object Trigger activity

Leg End

SipLegEnd

LegEndEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen as the leg ends.

Ending the session …​

A session may end for many reasons (a subscriber hangs up a call, there is no credit and so on).

…​ on session end
Point in Session Execution Point Name Trigger Object Trigger Activity

End Session

SipEndSession

EndSessionEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour, such as sending notifications, when a session ends.

At any time …​

There are a number of feature script execution points that may be triggered at ant time within the lifetime of a session.

As timers expire
Point in Session Execution Point Name Trigger Object Trigger Activity

Service Timer

SipAccess_ServiceTimer

TimerEvent

NullActivity

Suggested role/purpose of features that run at this feature script execution point

Service timers that are not configured to invoke a feature directly trigger this feature script execution point. Features that run at this execution point should decide what will happen to this session when the service timer expires.

Tip See Sentinel Service Timer Provider for more details.
If instruction execution fails
Point in Session Execution Point Name Trigger Object Trigger Activity

Instruction Execution Failure

SipInstructionExecutionFailure

InstructionExecutionFailedEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session when a Leg or Charging Manager instruction failed to execute successfully.

As extension events are processed
Point in Session Execution Point Name Trigger Object Trigger Activity

Feature Extension Event

SipAccess_FeatureExtentionEvent

Object

Extension Activity

Suggested role/purpose of features that run at this feature script execution point

Features that are invoked directly by Sentinel run in the context of the this feature script execution point.

Tip See Sentinel Feature Extension Events and Sentinel Service Timer Provider to learn how a feature can be invoked directly.

SIP sessions initiated via Third Party REGISTER Request

Purpose

This session plan is triggered on receipt of third party REGISTER Request.

Feature Endpoint API

sentinel-sip-spi (SentinelSipMultiLegFeatureEndpoint)

The following diagram is a visual representation of the session plan. It shows:

  • the points-in-session where Sentinel will search for a feature execution script to run (the green boxes)

  • the most important points where Sentinel will make a decision about how the session should be processed further (the grey diamonds)

The session plan is multi-leg aware; for example, within a multi-leg communication session, some of the feature script execution points may be run within the context of a particular ‘leg’. The points-in-session for this session plan are described in detail below the diagram.

sip third party register session plan
Figure 5. Session Plan for a Third Party REGISTER request

Feature script execution points

Below are details of these points-in-session:
Note

The feature endpoint for all sip execution points is SentinelSipMultiLegFeatureEndpoint

On initial trigger …​

The two major tasks Sentinel does on the first message of a new session (the initial trigger) are:

  • decide if the new session can be accepted for processing

  • if the new session is accepted, analyse the initial trigger and classify the session

Should the session be accepted?
Point in session Execution point name Trigger object Trigger activity

Session Accept

SipRegistration_Accept

SIP REGISTER

SipSession

Session Start

SipRegistration_Start

SIP REGISTER

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point analyse the incoming third party REGISTER request and extract the embedded 1st party REGISTER request and response. Properties of the request can also be used to determine the network operator.

…​ analyse the initial trigger …​
Point in Session Execution point name Trigger Object Trigger Activity

Network Check

SipRegistration_NetworkCheck

SIP REGISTER

SipSession

Session Check

SipRegistration_SessionCheck

SIP REGISTER

SipSession

Subscriber Check

SipRegistration_SubscriberCheck

SIP REGISTER

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at these execution points should analyse the 1st party REGISTER request and response to classify this session. For example features should extract public and private identities and determine type of registrartion scenario (register vs re-register vs de-register).

The three execution points allow you to select feature execution scripts in phases, as you further classify details of the session. For example: the first execution point can select a feature execution script that is particular to the network operator; the next execution point can select a feature execution script that is particular to the session type; and the last execution point can select a feature execution script that is particular to the plan and subscription ids.

…​ on an out-of-dialog SIP transaction response …​
Point in session Execution point name Trigger object Trigger activity

Transaction Response

SipTransaction_Response

SipResponse

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at these execution points should decide what will happen to this leg, its usages, and the multi-leg session, as the leg proceeds.

…​ …​ as each leg ends
Point in session Execution point name Trigger object Trigger activity

Leg End

SipLegEnd

LegEndEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen as the leg ends.

Ending the session …​

A session may end for many reasons (a subscriber hangs up a call, there is no credit and so on).

…​ on session end
Point in Session Execution Point Name Trigger Object Trigger Activity

End Session

SipEndSession

EndSessionEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour, such as sending notifications, when a session ends.

At any time …​

There are a number of feature script execution points that may be triggered at ant time within the lifetime of a session.

As timers expire
Point in Session Execution Point Name Trigger Object Trigger Activity

Service Timer

SipAccess_ServiceTimer

TimerEvent

NullActivity

Suggested role/purpose of features that run at this feature script execution point

Service timers that are not configured to invoke a feature directly trigger this feature script execution point. Features that run at this execution point should decide what will happen to this session when the service timer expires.

Tip See Sentinel Service Timer Provider for more details.
If instruction execution fails
Point in Session Execution Point Name Trigger Object Trigger Activity

Instruction Execution Failure

SipInstructionExecutionFailure

InstructionExecutionFailedEvent

SipSession

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this session when a Leg or Charging Manager instruction failed to execute successfully.

As extension events are processed
Point in Session Execution Point Name Trigger Object Trigger Activity

Feature Extension Event

SipAccess_FeatureExtentionEvent

Object

Extension Activity

Suggested role/purpose of features that run at this feature script execution point

Features that are invoked directly by Sentinel run in the context of the this feature script execution point.

Tip See Sentinel Feature Extension Events and Sentinel Service Timer Provider to learn how a feature can be invoked directly.

Diameter Mediation

Purpose

This session plan is triggered on receipt of a new Credit Control Request

Feature Endpoint API

sentinel-diameter-spi

The following diagram is a visual representation of the session plan. It shows:

  • the points-in-session where Sentinel will search for a feature execution script to run (the green boxes)

  • the most important points where Sentinel will make a decision about how the session should be processed further (the grey diamonds)

  • the points where Sentinel will delegate to the mediation layer to interact with an OCS (the blue mediation boxes) — see: Session Plans for the Mediation Layer for more details.

diameter sp

Feature script execution points

Below are descriptions of these feature script execution points:

Tip For feature script execution points available in the mediation layer (the dark blue box) see: Sentinel Mediation Layer.

On initial trigger …​

The three major tasks Sentinel does on the first message of a new session (the initial trigger) are:

  • decide if the new session should be accepted for processing

  • if the new session is accepted, analyse the initial trigger and classify the session

  • do an initial credit check by querying the OCS for this session.

Should the session be accepted?
Point in session Execution point name Feature endpoint Trigger object Trigger activity

Session Accept

DiameterAccess_SessionAccept

SentinelDiameterStartSessionFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Session Start

DiameterAccess_SessionStart

SentinelDiameterStartSessionFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should analyse the initial Credit-Control-Request and decide if the new session should be accepted, or rejected. Properties of the Credit-Control-Request can also be used to determine the network operator and the session type.

…​ analyse the initial trigger …​
Point in session Execution point name Feature endpoint Trigger object Trigger activity

Network Pre Initial Credit Check

DiameterAccess_NetworkPreCreditCheck

SentinelDiameterInitialTriggerFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Session Pre Initial Credit Check

DiameterAccess_SessionPreCreditCheck

SentinelDiameterInitialTriggerFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Subscriber Pre Initial Credit Check

DiameterAccess_SubscriberPreCreditCheck

SentinelDiameterInitialTriggerFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Features that run at this execution point should analyse the initial Credit-Control-Request and classify this session. The three execution points allow you to select feature execution scripts in phases, as you further classify details of the session. For example; the first execution point can select a feature execution script that is particular to the network operator; the next execution point can select a feature execution script that is particular to the session type; and the last execution point can select a feature execution script that is particular to the plan and subscription ids.

Monitoring the session …​

Sentinel will monitor the session by using the mediation layer to pass requests to the OCS. There are no mid-session feature script execution points for this session plan.

Ending the session …​

A session may end for many reasons (credit control is not required, there is no credit available and so on).

…​ on session end
Point in session Execution point name Feature endpoint Trigger object Trigger activity

End Session

DiameterCharging_EndSession

SentinelDiameterEndSessionFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour, such as sending notifications, when a session ends.

Sentinel Mediation Layer

Purpose

This session plan is triggered when Sentinel makes a request of the OCS.

Feature Endpoint API

sentinel-diameter-mediation-spi

The following diagram is a visual representation of the session plan. It shows the points-in-session where Sentinel will search for a feature execution script to run (the purple boxes). The points-in-session for this session plan are described in detail below the diagram.

mediation sp

Feature script execution points

The feature script execution points are triggered whenever a front-end service (such as the SS7 or SIP front-end services) delegates to the mediation layer to interact with the OCS.

…​ diameter mediation …​

As a mediation session starts …​
Point in session Execution point name Feature endpoint Trigger object Trigger activity

Start Mediation

Mediation_Start

DiameterMediationStartFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Suggested role/purpose of features that run at this feature script execution point

One or more mediation sessions may run in the mediation layer during the lifetime of a front-end service session. For example, an SMS charging scenario may involve a charge and then a refund. This execution point runs once for each mediation session. Features that run at this execution point may take actions when interaction with the OCS starts.

Before each credit control request …​
Point in session Execution point name Feature endpoint Trigger object Trigger activity

Pre Credit Control Request

Mediation_PreOcsCC

DiameterMediationMidSessionFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point may inject behaviour (related to Diameter) before the mediation layer makes a request of the OCS.

…​ take actions based on the outcome of the initial credit check …​
Point in Session Execution Point Name Feature Endpoint Trigger Object Trigger Activity

Credit Allocated

Mediation_CreditAllocatedPostOcsCC

DiameterMediationMidSessionFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Credit Limit Reached

Mediation_CreditLimitReachedPostOcsCC

DiameterMediationMidSessionFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Credit Control Not Required

Mediation_ControlNotRequiredPostOcsCC

DiameterMediationMidSessionFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Credit Control Failure

Mediation_OCSFailurePostOcsCC

DiameterMediationMidSessionFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Suggested role/purpose of features that run at this feature script execution point

Features that run at this execution point should decide what will happen to this mediation session, based on the outcome of the response seen from the OCS.

…​as a mediation session ends
Point in session Execution point name Feature endpoint Trigger object Trigger activity

End Mediation

Mediation_End

DiameterMediationMidSessionFeatureEndpoint

CreditControlRequest (Event)

RoServerSessionActivity

Suggested role/purpose of features that run at this feature script execution point

One or more mediation sessions may run in the mediation layer during the lifetime of a front-end service session. For example, an SMS charging scenario may involve a charge and then a refund. This execution point runs once for each mediation session. Features that run at this execution point may take actions when an interaction with the OCS comes to an end. For example, if promotions are used then the PromotionsFreeReservations must run at this feature script execution point.

Session Plans for the Sentinel Charge

Purpose

This session plan is triggered when a custom front-end service makes a request of the OCS by using the Sentinel Charge component.

Feature Endpoint API

sentinel-diameter-mediation-spi

The following diagram is a visual representation of the session plan. It shows the points-in-session where Sentinel will search for a feature execution script to run (the purple boxes).

sentinel charge sp

Feature script execution points

The Sentinel Charge component encapsulates the Sentinel mediation layer, and makes it available for use by custom front-end services. The points-in-session are defined in: Sentinel mediation layer.

Feature Execution Scripts

Sentinel uses feature execution scripts to run one or more features, at a feature execution script execution point.

How do feature execution scripts work?

Each feature execution script has a unique name (it must be unique within the scope of the platform). The Sentinel default configuration includes a set of feature execution scripts. The default scripts may be changed or replaced to meet the needs of a deployment.

The feature execution script has run, if, while, do-while, and return statements. The conditions of the if, while, and do-while statements are Boolean expressions of the responses from the previous feature, previous scripts, Boolean session state fields, and enum session state fields.

The Boolean expressions may contain:

  • directives set by features such as feature.continueAndClose

  • Boolean fields from session state such as session.RoamingIndicator

  • enum fields from session state such as session.ChargingType.sessionCharging.

  • EventManager predicates such as LegManager.endSession (Sentinel SIP only).

For example, the Sentinel SS7 default_call_DirectAccess_NetworkPreCreditCheck script:

featurescript OnNetworkPreCreditCheck {
  run EmergencyAndSpecialNumber
  if not feature.continueAndClose {
    run ClassifyCallScenario
  }
}

The default_call_DirectAccess_NetworkPreCreditCheck script runs the EmergencyAndSpecialNumber feature.

It then runs the ClassifyCallScenario feature if the previous feature (in this case EmergencyAndSpecialNumber) did not respond with continueAndClose.

A feature may detect a failure, and report to the Sentinel core using feature.featureFailedToExecute or feature.featureCannotStart. The default behaviour of the feature execution script is to ignore the error and continue feature script execution. However, if specific behaviour is required on error, then feature.featureFailedToExecute or feature.featureCannotStart may be checked in a feature execution script condition.

Any exception that is thrown by a feature will by caught by the Sentinel core. Sentinel will treat this as a failure and take the following actions:

  1. invoke abortFeature() on the feature that threw the exception

  2. raise feature.featureFailedToExecute to reflect the error

  3. raise feature.featureHasFinished so the feature execution script can continue.

The behaviour is the same as in the case of a feature detecting the error itself, then raising feature.featureFailedToExecute and feature.featureHasFinished.

Tip It is good practice for features to catch and handle exceptions themselves, and then raise feature.featureFailedToExecute or feature.featureCannotStart, rather than relying on the Sentinel core to catch and handle exceptions on their behalf.
Note

You create and edit feature execution scripts using the Sentinel Element Manager. See the Provisioning section in the Sentinel Administration Guide.

Writing feature execution scripts

Feature execution scripts define how a set of features will be executed by the Sentinel core. Feature execution scripts always run to completion. Features influence the control of a session by making requests to the Sentinel core. For example, a feature may request of the Sentinel core to 'releaseAndClose' . The Sentinel core is responsible for accumulating all requests made and making a final determination as to what should happen next, once the script finishes.

The feature execution scripting language is very simple, with run FeatureName statements, if statements, while statements, do-while statements, and return statements. For more information see:

Statements

Below are summaries of the if, while, do-while, run, and return statements.

The if statement

You can control whether a feature should be executed by using if statements; for example, to play an announcement with the PlayAnnouncementFeature, whether a feature has decided the session should be ended. Each if statement has a condition, a block of statements to run if the if condition is true and, optionally, a block of statements to run if the if condition is false.

branch

The if statement conditions are Boolean expressions of a small set of Boolean flags and Boolean session state fields.

Boolean flags

These flags represent the response of the last feature to run, and the current aggregate view of the feature execution script being executed. Typically, branches that control which feature should be run next in a script are related to the last feature that ran (and refer to feature. flags). Branches that guard what should happen based on features earlier than the last feature or at a previous feature script execution point refer to the currentNextStep. flags.

Note Most predicates for Sentinel SIP are now provided by Sentinel SIP EventManager Predicates.

Here are the flags for the different front-end services:

Front-end service Requests made by the latest feature
that finished executing		 Current view of the script execution
as to what will be reported to Sentinel core

Sentinel SIP

 
feature.cannotStart
feature.failedToExecute
feature.issuedWarning

not applicable

Sentinel SS7

 
feature.refuseDialog
feature.relayDialog
feature.markSessionType
feature.doNotChargeSession
feature.doNotMonitorSession
feature.connectAndClose
feature.continueAndClose
feature.releaseAndClose
feature.enableOcsInteraction
feature.suppressOcsInteraction
feature.scheduleFutureInteraction
feature.cannotStart
feature.failedToExecute
feature.issuedWarning
 
currentNextStep.refuseDialog
currentNextStep.relayDialog
currentNextStep.markSessionType
currentNextStep.doNotChargeSession
currentNextStep.doNotMonitorSession
currentNextStep.connectAndClose
currentNextStep.continueAndClose
currentNextStep.releaseAndClose
currentNextStep.enableOcsInteraction
currentNextStep.suppressOcsInteraction
currentNextStep.scheduleFutureInteraction

Diameter

 
feature.cannotStart
feature.ccNotApplicable
feature.creditLimitReached
feature.endUserServiceDenied
feature.failedToExecute
feature.issuedWarning
feature.markChargingType
feature.markTargetChargingType
feature.ratingFailed
feature.redirect
 
currentNextStep.ccNotApplicable
currentNextStep.creditLimitReached
currentNextStep.endUserServiceDenied
currentNextStep.markChargingType
currentNextStep.markTargetChargingType
currentNextStep.ratingFailed
currentNextStep.redirect
currentNextStep.userUnknown
Boolean session state fields

You may use a Boolean session state field in an if statement condition. The syntax is:

session.<name of the session state field>

For example, session.SessionHasEnded.

boolean ss
Enum session state fields

You may use a session state field, that is a Java enum, in an if statement condition. The syntax is:

session.<name of the session state field>.<enum constant>

For example, session.ChargingType.sessionCharging. Such an expression evaluates to true if session.ChargingType is a Java enum and session.ChargingType.name() equals sessionCharging.

enum ss
The while statement

The while statement allows you to repeatedly execute a set of statements, whilst a condition is true. Each while statement has a condition and a block of statements (the loop body). The while loop condition is evaluated before each execution of the loop. Execution terminates if the condition evaluates to false. There is a default limit of 10 iterations for a while loop (to avoid infinite loops). You may specify your own while loop limit (a number in square brackets after the while keyword).

The following two examples demonstrate the format of the while statement:

featurescript AWhileLoopScript {
  while local.input1 {
    run x
    while local.input2 {
      run y
    }
  }
}
featurescript AnotherWhileLoopScript {
  while [5] local.input3 {
    run x
  }
}
while
The do-while statement

The do-while statement allows you to repeatedly execute a set of statements, whilst a condition is true. Each do-while statement has a condition and a block of statements (the loop body). The do-while loop condition is evaluated after each execution of the loop. Execution terminates if the condition evaluates to false. The body of the do-while statement will, therefore, execute at least once. There is a default limit of 10 iterations for a do-while loop (to avoid infinite loops). You may specify your own do-while loop limit (a number in square brackets after the do keyword).

The following two examples demonstrate the format of the do-while statement:

featurescript ADoWhileLoopScript {
  do {
    run x
  } while local.input1
}
featurescript AnotherDoWhileLoopScript {
  do [2] {
    run x
  } while local.input2
}
do while
The run statement

The run statement tells the Sentinel core to run a particular feature. The Sentinel core invokes startFeature() and hands control of the session to the feature. Responsibility for the session remains with the feature until it raises feature.featureHasFinished().

run
Note

Sentinel also supports a runcritical statement, which is used when it is critical that a feature should execute correctly. The syntax of the runcritical statement is identical to the run statement.

Currently, only the Sentinel SIP front end considers the outcome of a runcritical statement. The runcritical concept will eventually be applied in all other cores. See section Sentinel SIP Feature Execution Points for more information.
Feature parameters

The run statement can optionally be provided with additional feature parameters, which take the form of a map of key/values. This data is freeform, and the interpretation and use of the additional data is entirely up to the executed feature. The intended use of feature parameters is to provide additional context to a feature regarding how it should execute. For example, feature parameters could be used to instruct a feature to use different configurations when executing as part of alternate logic branches in a feature execution script.

If feature parameters are specified in the feature execution script, then the feature will be invoked with the alternate startFeature() method, which supplies the feature parameters as a map of string keys to ParameterValue objects. Each ParameterValue object contains either a single string value, or an array of string values.

There are two forms for specifying feature parameters to allow both simple strings and lists of strings to be supplied to a feature. For example:

String

 
featurescript somescript {
  run featureA param1 "value1" param2 "value2"
}

List

 
featurescript somescript {
  run featureB param1 ["value1", "value2"]
}
param value
The return statement

The return statement causes execution of the feature execution script to end, and control return to the Sentinel core.

Comments

Comments can appear anywhere in the script where whitespace is allowed. Single line comments begin with // and extend to the end of the line, while multi-line comments begin with /* and end with */.

Resolving conflicting responses from features

Since a feature execution script runs to completion, it is possible that several features may make conflicting requests of the Sentinel core. Sentinel core applies some simple rules for resolving such conflicts as it updates its view of the script execution result.

Below are rules that are common to all front ends and those specific to each.

Common rules

  1. The requests of Sentinel core made by the most recent feature have precedence.

  2. Sentinel core applies requests in the order they are made by a feature.

SS7 rules

  1. Sentinel core treats connectAndClose, continueAndClose, and releaseAndClose as mutually exclusive.
    For example, if continueAndClose is set, and the latest feature requests releaseAndClose, then Sentinel core will clear continueAndClose and raise releaseAndClose.

  2. Sentinel core treats suppressOcsInteraction and enableOcsInteraction as mutually exclusive.
    For example, if enableOcsInteraction is set, and the latest feature requests suppressOcsInteraction, then Sentinel core will clear enableOcsInteracion and raise suppressOcsInteraction.

  3. Sentinel core treats refuseDialog and relayDialog as mutually exclusive.
    For example, if refuseDialog is set, and the latest feature requests relayDialog, then Sentinel core will clear refuseDialog and raise relayDialog.

SIP rules

  1. Sentinel SIP now uses EventManagers (LegManager, Charging Manager) for feature responses.

Diameter rules

  1. Sentinel core treats ccNotApplicable, creditLimitReached, endUserServiceDenied, ratingFailed, redirect, reportBaseResult, and userUnknown as mutually exclusive. That is, only one of these inputs can be raised at any one time.
    For example, if the latest feature requests userUnknown then Sentinel core will raise userUnknown and ensure that ccNotApplicable, creditLimitReached, endUserServiceDenied, ratingFailed, redirect, and reportBaseResult are all clear.
Tip

You can make use of these precedence rules by using an if statement to run a feature that will override the requests made of an earlier feature. For example, if a feature has requested continueAndClose, but you want Sentinel to send a releaseAndClose, you can use an if statement such as:

if feature.continueAndClose {
  run releaseAndClose
}

Feature script execution points that are chained together

There are two cases where Sentinel executes several feature script execution points before it considers the aggregate result and takes action:

Feature script execution points The values of the currentNextStep. flags: 
Session Accept
Session Start

  1. are cleared before Session Accept

  2. are available at the start of Session Start, and have values that are the aggregate result of Session Accept

 
Network Pre Initial Credit Check
Session Pre Initial Credit Check
Subscriber Pre Initial Credit Check

  1. are cleared before Network Pre Initial Credit Check

  2. are available at the start of Session Pre Initial Credit Check, and have values that are the aggregate result of Network Pre Initial Credit Check

  3. are available at the start of Subscriber Pre Initial Credit Check, and have values that are the aggregate result of Network Pre Initial Credit Check and Session Pre Initial Credit Check.
Tip See Session plans for more information. For example, consider SS7 sessions initiated via SS7.

The currentNextStep. flags are cleared before all other feature script execution points.

Examples

See the following examples of future execution points in different contexts.

featurescript OnSessionStart {
  if not currentNextStep.refuseDialog and
     not currentNextStep.relayDialog
  {
    run AcceptProtocol
  }
}

The first two execution points, together, provide initial dialog analysis. In the first step we run features within the context of the platform operator. This script then runs within the context of the network operator.

The condition here says that we run the AcceptProtocol feature only if we have not already decided to refuseDialog or relayDialog.

 
featurescript OnNetworkPreCreditCheck {
  run EmergencyAndSpecialNumber
  if not feature.continueAndClose {
    run ClassifyCallScenario
  }
}

NetworkPreCC + SessionPreCC + SubscriberPreCC, together, provide the initial analysis of the InitialDP. We run features:

  • within the context of the network operator (NetworkPreCC)

  • within the context of the session (SessionPreCC)

  • within the context of the subscriber (SubscriberPreCC).

This is an example script that runs within the context of the network operator. The first step is to run the feature EmergencyAndSpecialNumber.

This feature will request that Sentinel core should continueAndClose if the number dialled is special (such as 111 in New Zealand) and Sentinel should not be involved anymore.

The next statement says that ClassifyCallScenario should only run if the latest feature that finished (in this case EmergencyAndSpecialNumber) did not request continueAndClose.

 
featurescript OnSessionPreCreditCheck {
  if not currentNextStep.continueAndClose {
    run CallForwardingDetection
    if not feature.doNotMonitorSession and
       not feature.doNotChargeSession
    {
      run ValidateInitialDP
      if not feature.releaseAndClose {
        run ShortCode
        run PrefixAndSuffixAnalysis
        run Normalization
        run Reorigination
        if not feature.connectAndClose {
          run SubscriberDetermination
          run SessionTracing
        }
      }
    }
  }
}

This is an example script that runs within the context of the session. The initial condition guards all feature execution by checking if we have currently been asked to continueAndClose. If we have, then we do not need to run any feature.

Otherwise we run the CallForwardingDetection feature. This checks to see if this is a forwarded leg that we should not process.

The if statement that follows has a condition that is in terms of the last feature that ran. So we only run more features if CallForwardingDetection did not request doNotMonitorSession or doNotChargeSession.

If that is the case, we then run ValidateInitialDP.

This feature will request that Sentinel core should releaseAndClose, so we check to see if this happened before running any further features.

Feature execution script grammar

The following tramline diagrams define the grammar of the Sentinel feature execution script language.

script block statement branch while run param-value return condition term factor identifier fsminput Boolean-ss enum-ss

tokens

Mappers

Mapping fields of incoming objects

Below are details of how mappers work, including how Sentinel selects them at runtime.

What is a mapper?

A mapper is a software component in Sentinel that builds an output object by “mapping” fields of an incoming object. You use mappers at the egress point for protocol messages, for example immediately before sending a CreditControlRequest. You can also use them in any features and other components that require protocol mapping. Sentinel comes with a standard set of mappers; and you can add new ones using the Sentinel SDK.

mapper

Mappers have access to session state, resource adaptor providers, and the from object to achieve their task. For example, a mapper that generates Diameter messages will use a Diameter provider to get a message factory for creating Diameter messages. It might read values from session state and the input from message to create Diameter AVPs; and once complete, return the newly created Diameter message as its result (the to object).

Sentinel uses the mapper concept to decouple Sentinel core from the details of how output messages are generated. Sentinel will select a mapper to apply at runtime, and apply it to generate output messages. The Sentinel SDK user can add new mappers and totally change the way Sentinel creates output messages.

How does Sentinel select mappers at runtime?

The Sentinel SDK generates a MapperRegistry that Sentinel uses at runtime to resolve which mapper to use. The interface to the Sentinel runtime is a MapperLibrary:

mappers-at-runtime

At runtime, Sentinel…​

  • uses mapper lookup configuration data to resolve which mapping to use

  • uses the “mapping name”, get a concrete mapper from the registry

  • returns the mapper to Sentinel core to use.

The mapper library implements dynamic lookup of mappers based on the SentinelSelectionKey, the from class, and the to class (as well as an optional MapperExecutionPoint). The library ultimately resolves the request for a mapper to a mapping name. The mapper registry that the Sentinel SDK generates provides a lookup table of mapping name → mapper implementation.

Dynamic mapper fallback selection

In the event that no exact match is found during a mapper lookup for the ‘from’ and ‘to’ classes, a more general MapperRegistry search is performed for mappers which partially fulfill the ‘from’ and ‘to’ classes via extension.

For example, if the Sentinel core requests a mapper from CAP2InitialDPArg to CreditControlRequest, but only a mapper from CCInitialDPArg to CreditControlRequest exists in the MapperRegistry, then this second mapper will be returned (as CAP2InitialDPArg extends CCInitialDPArg). This allows the creation of mappers which will work even when the exact ‘from’ class is not known at compile time, but is known to be a subclass of another class (such as CCInitialDPArg).

The order of mapper matching logic with dynamic fallback is as follows:

  1. Exact match of from class, to class, respecting mapping point.

  2. Generic match for from class, to class, respecting mapping point.

  3. Exact match of from class, to class, ignoring mapping point.

  4. Generic match for from class, to class, ignoring mapping point.

  5. If no mapper was found, throw a MapperException.

Tip Mappers are configured using the Mappers REST API or Managing Mappers web interface.

Promotions

Below is a description of Sentinel promotions, and how you might use them.

What is a promotion?

A promotion is a charging mechanism that deflects charging requests away from the OCS, to be charged to a specially provisioned account called a promotion bucket. The promotion bucket can be stored for example in session state or in a database which Sentinel can query and update directly. Each promotion consists of two main elements: a promotion bucket, which may be shared by multiple promotions, and a promotion condition.

sentinel promotions
Important Sentinel’s promotions are not a rating engine as found in an OCS — they can be used to charge eligible services against a particular bucket of units, but they cannot determine or affect the rate at which services are charged.

Promotion buckets

Promotion buckets are buckets of units provisioned on a per-subscriber or per-session basis. Each bucket has a unique name and is configured in Sentinel to be of one of the following access types:

  • External Database

  • Cassandra

  • SLEE Profile

  • Sentinel Session State

  • Unlimited.

A subscriber can be eligible for more than one promotion and thus units may be charged to different buckets for the same subscriber. A promotion bucket is distinct from the user’s main account in the OCS, in that it is held in session state or a separate database maintained by Sentinel directly. It usually (though not always) represents a particular unit-/type/ and provides units to be charged by one or more promotions.

Promotion conditions

A promotion condition is a filter that defines which charging requests are eligible for the promotion. Factors in this condition can include: service, amount of units, current time, and so on. The filter may be hardcoded in Java or scripted in the extensible Sentinel PromotionScript DSL for fast and easy deployment.

Below is an example of a scripted promotion condition for “anytime free data”:

chargingUnitTypeOneOf(CCInputOctets,CCOutputOctets,CCTotalOctets)

Why promotions?

Sentinel’s promotions meet a number of needs in real-time session control:

Granting special offers

Sentinel’s promotions make it simple to grant special offers and customized charging plans to subscribers for any combination of services and conditions. This is a key competitive advantage, because it significantly reduces the time-to-market on newly developed offers. It also opens up a whole range of options for charging plans.

OCS-offload

A key benefit of Sentinel’s promotions is to reduce OCS requests during special offers such as a “1000 free SMS” deal. This can be a major cost-saver when offering promotions to customers, as OCS’s are commonly licensed on a session or request per-second basis, and requests can increase dramatically during such special offers.

Maintaining fair-use policies

Sentinel’s promotions can also be used to maintain fair-use provisions, by restricting subscribers from abusing “unlimited” offers.

OCS failure-handling policies

In the event of OCS failure, an OCS Failure Handling Promotions can be used to provide a grace period to allows service to continue for a limited time. In an event-based charging scenario, a limited number of service events may be allowed until full service is restored. All accounting data can be reconciled later by using the call detail records that Sentinel records for each session.

Online or offline charging

If sessions are categorized at session start as ‘offline charged’, OCS interaction has to be switched off for the rest of the session, while units still need to be recorded in the CDR written at call end to enable offline processing and billing. This can be achieved with an appropriately named ‘unlimited’ promotion bucket against which all units of the offline charged session are booked. The session counters in the CDR will show the offline charged units being booked under the selected promotion bucket name.

Address List Overview

What is an address list?

An address list is a searchable collection of addresses. Each address in an address list may also have some associated data. You can use address lists for some of the features bundled with Sentinel, such as:

  • special prefixes — Prefix and Suffix Analysis Feature does a longest prefix match against a dialled number to see if the dialled address includes one of the prefixes.

  • short-codes — The Short Code Feature does an exact match against a dialled number to see if the dialled number is a short-code. Each short-code in the address list has the fully qualified address the short-code represents.

  • global-title addresses — The SS7 Determine Network Operator Feature does a longest prefix match against the destination SCCP address to determine which network operator the new session is for.

Each address list has a unique name. The addresses in the address list are stored in SLEE profiles. Sentinel manages a cached digit tree for each address list. The digit tree provides fast exact, longest prefix, and longest suffix matching of addresses.

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

Addresses in an address list are sequences of: 0 …​ 9, a …​ f, A …​ F, #, *, .

Tip You provision address lists using the Sentinel Element Manager. See the Sentinel Administration Guide for details.

Sentinel Selection Key

Sentinel calculates a key for every session in Sentinel (call, SMS, data session, and so on).

How does Sentinel use the selection key?

Sentinel uses a session’s selection key to select the features that will be run for that session, and the configuration that will be applied for those features.

The Sentinel selection key has several fields that progressively narrow the scope of feature and configuration selection:

sentinel selection key

  • Platform operator — identifies the operator of the Sentinel platform

  • Network operator — identifies the operator of the network which the session belongs too (may differ from platform operator if the network is a MVNO)

  • Session type — identifies the type of session (for example, MO-Call or SMS)

  • Plan Id — identifies the subscriber’s plan or subscriber type

  • Subscription Id — identifies the subscriber (for example MSISDN).

Call Detail Records

Sentinel writes a Call Detail Record (CDR) for each session. Sentinel defines out-of-the-box CDR formats for its various services, and allows customisation or even replacement of CDR formats.

For further information on out-of-the-box CDR formats refer to CDR Formats. See Customising CDRs in the Sentinel SDK documentation for more information about adding new fields to the Sentinel CDRs.

OCS Drivers

OCS drivers are the components which connect Sentinel to an actual OCS.

How are OCS drivers used?

OCS drivers fulfil two essential purposes:

  • providing implementations of session charging and immediate event charging functionality, triggered through the exposed OCS driver interface, by the Sentinel-internal mediation layer

  • translating between Diameter Ro, which is used internally in the mediation layer, and the actual protocol of the OCS in use.

OCS drivers are realized as child SBBs which are referenced by the main Sentinel front-end SBBs (SS7, Diameter, and SIP services). Each OCS driver moreover has a name which must be unique across the whole Sentinel system. During the course of a session, Sentinel examines the OcsEntityId session state field, and selects the OCS driver whose name matches one to be used for an OCS interaction.

Caution Do not change the OcsEntityId during the course of a session, following an OCS interaction (with a different OCS). Each OCS Driver module has an associated Mappers module, which holds the Sentinel mappers required to do the conversion between the Sentinel-internal Diameter Ro format and the format required by the actual OCS.

What can OCS drivers be used for?

  • OCSes with alternative protocols — connecting to OCSes which use a protocol different to Diameter Ro (such as Diameter CCA)

  • MSCC-Multiplexing — changing the implementation of the Session-Charging and Immediate-Event-Charging FSMs to provide an implementation which opens a dedicated session to the OCS for each Multiple-Services-Credit-Control (MSCC) AVP found in the original CCR from the mediation layer.

What OCS drivers does Sentinel provide?

  • Diameter Ro OCS Driver (ocsEntityId=DiameterRoOc)

Session Counters

Session counters are charging activity counters stored in session state.

How do session counters work?

Session counters are used to record the current status of the charging activity in a session. When a CDR is written for the session, the session counter data is transferred. The session counter data in the CDR records the final status of the charging when the session ended. The session counter data is used in post processing:

  • to determine any undebited units for the session

  • for statistical purposes, such as reporting on granted free units that are otherwise not recorded

  • for reconciliation of Sentinel with the OCS.

Session counter structure

The session counters' Session State field contains one or more session counters. Each session counter is a tree which records the sum of values of any child counters, unless it has none, in which case it holds its own counter values.

The root of a session counter has the following fields:

Field name Purpose Details 
subscriberId

Subscriber id associated with the charging values stored in this counter

 
bucketName

The name of the counter

 
cumulativeRequestedUnits

Cumulative requested unit reservations

Sum of Requested-Service-Units in CCR Multiple-Service-CreditControl AVPs associated with this counter.

 
cumulativeGrantedUnits

Cumulative granted unit reservations

Sum of Granted-Service-Units in CCA Multiple-Service-CreditControl AVPs associated with this counter.

 
cumulativeSentUsedUnits

Cumulative used units

Sum of Used-Service-Units in CCR Multiple-Service-CreditControl AVPs associated with this counter.

 
cumulativeCommittedUsedUnits

Cumulative committed used units

Sum of Used-Service-Units in CCR Multiple-Service-CreditControl AVPs associated with this counter which have received a CCA response successfully. Also used for the values reported in DIRECT_DEBIT CCRs.

 
cumulativeRequestedRefundUnits

Cumulative requested refund units

Sum of Requested-Service-Units in CCR(REFUND) Multiple-Service-CreditControl AVPs.

 
cumulativeGrantedRefundUnits

Cumulative requested refund units

Sum of Requested-Service-Units in CCR(REFUND) Multiple-Service-CreditControl AVPs associated with this counter which have received a CCA response successfully.
Important The values stored in counters are not always related to Diameter CCR and CCA AVP values. They may also represent the charging activity of promotions which do not use Diameter or the charging activity of a non-Diameter charging protocol.

A session counter has one or more sub-counters which store charging values related to a charging reference, such as a service identifier or unit type (for example, time units, service specific units, octets, and so on).

Field name Purpose 
subCounterId

An identifier for the contents of this sub-counter (such as service id or unit type).

 
cumulativeRequestedUnits

All values as above but associated with the sub-counter identifier.

 
cumulativeGrantedUnits
 
cumulativeSentUsedUnits
 
cumulativeCommittedUsedUnits
 
cumulativeRequestedRefundUnits
 
cumulativeGrantedRefundUnits

MediationClient, OCS, promotions counters

All Sentinel session will record charging activity in a session counter with bucketName set to MediationClient. This represents the charging activity from the perspective of the protocol client: SIP, SS7, Diameter, or custom protocol in the case of Sentinel Charge.

The MediationClient session counter shows the overall charging values. Other session counters in the session counter’s structure detail the various charging activities which are accumulated in the MediationClient counter. When there is only an OCS involved, then the OCS and MediationClient values will be identical. If a promotion and an OCS are involved in providing units, then there will be a counter for the promotion and for the OCS.

Examples

Below are examples of:

Successful MOC call

The following session counter shows the charging values at the end of the call. The call in this case was 5s long and had a successful 60s reservation. All units were successfully committed in the OCS. There are two sub-counter levels. The first level is used for the MSCC Service-Identifier. The second level is used for the unit type, in this case CC-Time.

sentinel session counter moc 2001

Successful MOC call with promotion

The following session counter shows the charging values at the end of the call:

  • The call in this case was 75s long and had a successful 60s reservation from the AnytimeOnNet promotions.

  • An update reservation to the promotion was unsuccessful, so the OCS was interrogated.

  • The unit reservation of 60s to the OCS was successful, of which 15s were used and reported to the OCS.

The session counters structure for this session has three counters: AnytimeOnNet, OCS, and MediationClient The view of the IN service is shown in MediationClient. The detail activity, including promotions and OCS interaction, is show in the AnytimeOnNet and OCS counters.

sentinel session counter moc promotions 1001

Unlimited SMS promotion

This session counters structure shows an SMS session which was successfully completed using units from the UnlimitedSMS promotion. For this session, the OCS was not necessary, so no session counter structure is shown.

Note In this session the lower sub-counters have id CCServiceSpecificUnits, which represents the unit type for an SMS session.
sentinel session counter sms promotions 1001

Diameter Ro OCS failure handling and undebited units handling

The session counters structure below is for a Diameter Ro charging session. The initial interrogation of the OCS failed.

The subscriber had some units available in the OCS failure handling bucket which were granted. Using these values from the CDR, the undebited units are identified and the subscriber’s balance correctly debited in post processing.

sentinel session counter diameter ocs failure 3001

Features

Features are software components you write (in Java), which Sentinel executes at feature execution points.

How do features work?

Features:

  • contain business logic; for example, the SS7 short-code feature will translates a short-code into a routable destination address

  • run at feature execution points in a session plan; for example, as the session starts, before Sentinel accesses the OCS, as the session ends, and so on

  • may influence how a session proceeds by making requests of Sentinel; for example to release the call or update parameters of the call

  • may perform business logic that does not effect the session; for example, playing an announcement, or generating a notification

  • may update session state.

 

sentinel-feature

Sentinel features may make use of:

Built-in and customisable

Sentinel comes with a rich set of built-in features that can be used by Operators, such as HomeZone, MOC, MTC, Balance Inquiry, and several more. You can also create new features, using the Sentinel Software Development Kit (SDK).

Tip

For details on the features bundled with Sentinel, see Features in the Sentinel Administration Guide.

To learn how to create your own features, see the Sentinel SDK.

Sentinel SIP Enhancements

Sentinel has been enhanced to make Sentinel SIP more flexible:

  • The Rhino platform now provides hot deployment and late binding of components into a SLEE service. This means Sentinel features, mappers, and so on can be replaced without re-deploying Sentinel services.

  • The event-processing model of Sentinel SIP now has local events (such as Leg End and Instruction Execution Failure events) and new feature script execution points.

  • Much of the core SIP processing behaviour is now implemented using features, so core SIP signalling behaviour can be easily customised.

  • Features can now:

    • interact with external resources using feature extension events

    • set their own timers

    • support multi-leg scenarios with the improved Leg Manager

    • support more flexible-charging scenarios with the new Charging Manager.

Note Many of these features are currently only available in Sentinel SIP, but will eventually be added to the other Sentinel services. Some enhancements (such using new Rhino features) are already available in other Sentinel services.
Tip

See:

Enhanced Sentinel SIP Architecture

Below is a high-level diagram of the enhanced Sentinel architecture of the Sentinel SIP platform.

enhanced sip architecture

Sentinel SIP Charging Architecture

The goal of the new charging architecture for Sentinel SIP is to separate SIP service logic and charging, while supporting as many use cases as possible.

Note

Sentinel SIP provides a flexible charging architecture that offers more control over how to apply charging to a session. While this architecture is only available to Sentinel SIP (and by extension Sentinel VOLTE), it will be used in other cores in the future.

Online charging

Online charging is both the primary and necessarily most feature-rich charging mode in Sentinel. There is support for:

  • session charging with unit reservation (SCUR)

  • event charging with unit reservation (ECUR)

  • immediate event charging (IEC).

The charged units have flexible semantics that can be customised to suit the need. For example, the main unit might be milliseconds for timing an INVITE session; while a secondary unit of CC-Service-Specific-Units might be used to charge a MESSAGE request in that same dialog.

Online charging takes advantage of the charging API to provide complete but extensible behaviour in a range of scenarios. Some examples of supported SIP scenarios are:

  • B2BUA

  • MMTel conference

  • charged or uncharged announcements

  • event notification and single transactions using IEC or ECUR.

Sentinel SIP supports several standard charging use cases out of the box. You can enable or enhance business through:

  • system-wide and feature-specific configuration

  • scenario-specific configuration, using the Sentinel selection key

  • selection and composition of charging rules using feature scripts (including ChargingManager predicates)

  • extending and adding features and mappers with the SDK, using Sentinel SIP’s simple and flexible Charging Manager.

Offline charging

Offline charging is supported by not running the charging features in the feature scripts, and just recording CDRs.

Components

Charging in Sentinel SIP uses these components:

Features and mappers

Nearly all charging business rules are encapsulated within features and mappers. Furthermore, charging behaviour is mostly decoupled from SIP functionality. The overlap of SIP logic with charging is usually limited to detecting call conditions that affect charging, temporarily suspending messages during a credit check, or ending legs due to charging conditions. That means the core SIP functionality can generally be provided by SIP features without regard to charging, which can be mixed in via charging-specific features.

Charging Mappers are used for a variety of purposes including to map SIP messages to SessionCounterAddresses, SessionCounters to CCRs, and CCAs back to SessionCounters.

Charging Manager

The Charging Manager provides a simple API (backed by the Sentinel mediation layer) for features to issue charging requests. During any credit check, Sentinel automatically ensures all incoming messages are queued in the SLEE until the CCA (or a timeout) is received; in other words, no further network events will be delivered to Sentinel or processed until the credit check is complete.

SIP Session Counters

SIP Session Counters are used to set and track the units sent and received in diameter mediation requests and responses

Service Timer Provider

The Service Timer Provider can be used to set validity time timers, SCUR reauth timers, or timers for any other purpose. It is already used by B2BUAScur for regular reauths; and the mediation layer already times validity and request timeouts for each charging instance.

B2BUAChargingFeatureUtil

The B2BUAChargingFeatureUtil provides a set of static utility methods and algorithms, for example to attribute granted units from a CCA to SessionCounters or to calculate used units. The utility is available in the b2bua-charging-sbb-part SDK module. The SCUR and other system charging features use it. It implements the individual steps in the Counter update algorithm pseudo code, and could be re-used by modified or alternative charging features.

Existing SIP charging features

Many charging-related SIP features come with Sentinel SIP to provide an out-of-the-box comprehensive set of common SIP charging business rules.

B2BUAScur pre and post features

B2BUAScur pre and post features implement the minimum required behaviour for SCUR-based charging of a SIP B2BUA, as well as foundational support for these behaviours for user-defined counters:

  • initialising the default SCUR charging instance and session counter on an initial incoming request

  • performing an initial credit check, suspending outgoing initial requests until a successful response is received

  • updating reservations as needed (based on the timer set from granted SCUR units on each CCA)

  • responding to RARs

  • calculating and setting used units on the SCUR counter with every reservation

  • allocating all (both SCUR and service-specific counters) units granted and sent on every CCA.

SDP comparison

SDP comparison extends basic SCUR charging with additional reauthorisations on every meaningful SDP change. It works like this:

  1. Detect meaningful SDP updates and issue a reauthorisation.

  2. If the credit check fails, roll back the SDP and reauthorise.

  3. If the rollback credit check fails, raise endSession.

B2BUAEcur pre and post features

The B2BUAEcur pre and post features implement the minimum required behaviour for ECUR-based charging of a SIP B2BUA, as well as foundational support for these behaviours for user-defined counters:

  • initialising the default ECUR charging instance and session counter on an initial incoming event-chargeable request

  • performing an initial credit check, suspending outgoing initial request until a successful response is received

  • calculating and setting used units on the ECUR counter for the reservation and termination

  • allocating all (both ECUR and service-specific counters) units granted and sent on both CCAs.

B2BUAIEC pre and post features

The B2BUAIEC pre and post features implement the minimum required behaviour for IEC-based charging of a SIP B2BUA, as well as foundational support for these behaviours for user-defined counters:

  • initialising the default IEC charging instance and session counter on an initial incoming event-chargeable request

  • performing a direct debit, suspending outgoing initial requests until a successful response is received

  • allocating all units (for both IEC and service-specific counters) granted and sent on both CCAs

  • issuing a refund on service delivery failure.

SipMidCallPlayAnnouncement feature

Though not a charging feature per se, this feature demonstrates that charging can be suspended by any feature at any time and for any purpose. The announcement properties include a field, SuspendCharging, which indicates to the SipMidCallPlayAnnouncement feature that it should suspend all charging instances while the call parties are disconnected. The result is that the time period for the announcement is not charged. Reauths will still be handled by the B2BUAScur feature, which will also compensate for the suspended time in its calculation of used units.

Charging Scenarios

The following examples demonstrate how Sentinel SIP’s charging features interact with a SIP Session, highlighting key points-in-session from a charging perspective.

Online charging — B2BUA with SCUR including SDP comparison

This scenario demonstrates how the basic charging business rules provided by B2BUAScur can be enhanced with SDPComparison to support reauthorisation on meaningful SDP changes.

To summarise, the steps in the scenario are:

  1. B2BUA feature creates outgoing leg and schedules INVITE to be B2BUA’d.

  2. B2BUAScur perform successful initial credit check, and suspends and resumes outgoing leg.

  3. B2BUAScur performs recurring reauths.

  4. B2BUAScur handles RAR.

  5. Re-INVITE with meaningful SDP change triggers reauth by SDP Comparison.

  6. Reauth fails and SDP reverts, followed by reauth, which is successful with final units indicated, allowing the call to continue with original parameters.

  7. The charging timer fires; however since final units were indicated on the latest CCA, instead of a reservation, B2BUAScur instructs endSession.

  8. All legs end, triggering a successful credit finalisation by B2BUAScur.

b2bua-scur-sdp-rollback-rar

Online charging — third-party call setup with SCUR

This scenario shows that it is possible to rely on only a subset of the charging rules in a feature.

Normally B2BUAScur will perform the initial credit check itself; but if there is no initial incoming request, it’s possible for another feature (such as Third Party Charging) to initialise the SCUR instance and handle the initial credit check. After that, B2BUAScur will take over charging the ongoing SIP session and teardown.

thirdparty-b2bua-scur

Online event charging (ECUR/IEC)

Event charging can be done through either ECUR or IEC. ECUR is similar to SCUR, except that only a single reservation is performed, followed by a termination request if necessary. IEC involves a single direct debit, and only requires a refund request if service delivery fails.

Any SIP session could be charged using event charging, but the usual case is to charge single transaction dialogs and subscription dialogs using event charging. This can be achieved by running either the IEC or ECUR features in the various Subscription and SipTransaction feature execution points as well as in the credit result execution points.

By default, B2BUAEcurPre will trigger a credit reservation on any SUBSCRIBE or single transaction request.

The following scenario shows a simple SUBSCRIBE request charged using ECUR.

b2bua-ecur

The next scenario shows an IEC direct debit and refund on a SIP error:

b2bua-iec-refund

Sentinel SIP Event-Processing Model

The event-processing model is the algorithm Sentinel uses to process events.

Event sources

Sentinel receives events from several sources:

Event source Received from Examples

SIP

an external SIP network element (such as an S-CSCF)

INVITE
SUBSCRIBE

HTTP

an external HTTP-enabled network element

an HTTP GET request that initiates a third-party call setup

Diameter

the Sentinel mediation layer (related to events from an external OCS)

Extension

external network elements for sessions initiated by features within Sentinel

Timer

timers that features raise using the ServiceTimerProvider

Local

raised internally by Sentinel, as a result of processing other events and instructions

EndSessionEvent, when the Sentinel session has ended (that is, no more SIP legs or charging instances remain active)

InstructionExecutionFailedEvent, when one or more event manager instruction failed during processing

LegEndEvent, when the Sentinel session continues, but one or more SIP legs have ended

What is an event manager?

While processing events, Sentinel delegates to and receives instruction from event managers. These are event-driven components that help process sessions within Sentinel. The most important event managers, from a feature-developer perspective, are:

  • Charging Manager — manages charging instances during the session

  • Leg Manager — manages all the SIP legs during the session.

An event manager is responsible for:

  • providing some core Sentinel behaviour

    For example: the Charging Manager manages all charging during the lifetime of the session; and the Leg Manager manages all the SIP legs during the lifetime of the session.

  • registering the set of events that the event manager should be triggered for

    For example, the Charging Manager is interested in events such as CreditControlAnswer, ReAuthRequest, and AbortSessionRequest.

  • determining the set of feature script execution points that are relevant for a particular event

    For example, the Charging Manager determines that the SipAccess_CreditAllocatedPostCC should be triggered when Sentinel receives a successful CreditControlAnswer in response to an initial credit reservation.

  • managing a set of pending instructions

    Note An “instruction” is a task that the event manager considers should be performed once all relevant feature script execution points have been processed.

    For example, the Charging Manager supports instructions such as CreditReservation, CreditFinalisation, and Refund. Instructions are queued as features execute, so a feature can make changes to the set of pending instructions.

Tip The Charging Manager and Leg Manager also provide an API for features to use. The actions features take may cause these managers to change their state (which includes adding, removing, and updating pending instructions). For example, a feature may create a new charging instance or create a new SIP leg.

Sentinel SIP event-processing algorithm

The following diagram is an overview of how Sentinel SIP processes events:

sip event model

As shown above:

1

Sentinel receives a real event, such as an INVITE request from the S-CSCF or a CreditControlAnswer from the Sentinel mediation layer. Sentinel starts an event loop:

Loop

Update Event Managers …​ Process Feature Script Execution Points …​ Process Event Manager Instructions

Until the local event queue is empty.

2

Event managers process the received event. They:

  • update their own state

    For example, the Leg Manager creates a new leg for an initial INVITE request; and the Charging Manager updates charging sessions on receipt of a CreditControlAnswer.

  • determine if one or more feature script execution points should be triggered for the event

    For example, the Leg Manager determines that the SipAccess_SessionAccept, SipAccess_SessionStart, SipAccess_NetworkCheck, SipAccess_SessionCheck, and SipAccess_SubscriberCheck execution points should be triggered in response to an initial INVITE request.

3

If there are any feature script execution points to trigger, then process them; otherwise see if event managers have any instructions to carry out.

4

Process each feature script execution point in turn. Features may update the state of the Charging and Leg Managers as they execute. For example, a feature might create a new SIP leg, or link two SIP legs.

Features may set timers or create sessions to external network elements. Related extension events and timer events may be received whilst Sentinel is processing feature script execution points.

Tip
See To learn how…​

Sentinel processes a feature script execution point

features may raise timers

features may receive extension events

Once all feature script execution points have been processed, then check if the event managers have any instructions to carry out.

5

Ask each event manager in turn to carry out any pending instructions that have accumulated while processing the event.

Each event manager manages a set of instructions while features are executing. For example, if a feature calls doRefund() on an ImmediateChargingInstance, then the charging instance will record a pending instruction of Refund.

Once all pending instructions have been processed, then see if there are any events in the local event queue. If the local event queue is empty, then wait for the next real event. Otherwise, de-queue a local event and process it.

6

Event processing ends once the session ends.

Inside Sentinel SIP

Charging Manager

The Charging Manager component is used by features to interact with the charging sub-system provided by Sentinel. Features use the Charging Manager to create one or more charging instances during the session. Each charging instance represents a charging conversation with an Online Charging System (OCS).

charging manager
Figure 7. Charging Manager and Charging Instances

  1. There is one ChargingManager instance for each session.

  2. Each ChargingManager may manage one or more charging instances. For example, the diagram shows that there is both SCUR and IEC based charging involved in the session.

Note

The first release implementation of the ChargingManager supports one charging instance per session. This limitation will be removed in a subsequent release of Sentinel so all possible approaches to charging a session will be supported.

The Charging Manager is currently only available in the Sentinel SIP frontend, but the concept eventually will be extended to the other cores.

See Using the SIP Charging Manager to learn how features access and use the Charging Manager component.

Leg Manager

The Leg Manager component is used by features to control one or more UAS, UAC, and B2BUA legs in the same SIP Sentinel Instance. Features can use the Leg Manager to provide complex services, such as a conferencing.

A SIP leg describes both the dialog that creates a SIP transaction and a SIP dialog. Sentinel SIP, by default, acts as a B2BUA for a two-party Sentinel SIP session the has two linked legs: callingParty and calledParty. Features use the SIP Leg Manager API to interact with the calling and called party legs and any additional legs that features may create.

Note

See Using the SIP Leg Manager to learn how features access and use the Leg Manager component.

Sentinel SIP Feature Execution Points

Enhanced Feature Execution Model

Sentinel SIP has improved the feature execution model in three important areas:

  1. Added the concept of a System Feature. Other features are now considered User Features

  2. Added the runcritical statement to the feature execution script language

  3. Expanded the method for how a feature script execution point is processed. In the new model a point-in-session is processed in three steps with a pre script, user script and a post script.

Note

System features and pre/post feature execution scripts are only available in the Sentinel SIP frontend, but the concept eventually will be extended to the other cores.

The rest of this section will explain these new concepts in more detail.

  1. User and System Features

  2. What is a Feature Execution Point

  3. How does Sentinel Process an Execution Point

User and System Features

There are two types of feature:

  1. User features are for customising the behaviour of a front-end sentinel service to the particular needs of sentinel installation. I.e features as we understand them in current front-ends

  2. System features are for customising/implementing substantive aspects of the the sentinel front-end service behaviour. For example, the B2BUA feature provides back-to-back user agent functionality to Sentinel

Tip

See Sentinel SIP User Features for a list of user features.

See Sentinel SIP System Features for a list of system features.

What is a Feature Execution Point

A Feature Execution Point is a step in the lifetime of a session that has some significance and where custom behaviour might be needed. Sentinel features are used to customise the behaviour of a front-end sentinel service to the particular needs of a sentinel installation. The method for executing features is:

  • feature run at a points-in-session called 'feature script execution points'. These points-in-session correspond to significant steps in the process of managing a session. For example, as the session is starting, or ending.

  • a set of features to run, the order the features run, and any conditions are described in a feature execution script (i.e a script that dictates and controls how features are executed).

  • Sentinel searches for an appropriate feature execution script at run time considering the point-in-session and the current value of the SentinelSelectionKey

  • feature execution scripts always run to completion. That is, if a feature fails, then Sentinell will continue with the next feature.

  • Sentinel only takes action only after the point-in-session has been processed

Tip

See section Sentinel Selection Key for more information about the sentinel selection key.

See Sentinel Feature Execution Scripts for more information on the feature script execution language.

How Does Sentinel Process an Execution Point

Sentinel processes a feature script execution point in three steps (as shown in the following diagram).

processing an ex point
Figure 8. Steps in processing a feature script execution point

  1. Sentinel searches for a pre script. A pre script defines how a number of system features should run and and will be processed before any user features are run. If a script is found, then Sentinel will execute it.

  2. If none of the critical features in the pre script failed, then Sentinel searches for a user script. A user script defines how a number of user features should run. If a script is found, then Sentinel will executes it. If any of the critical features in the pre script failed, then Sentinel does not search for a user script and skips to step 3.

  3. Sentinel searches for a post script. A post script defines how a number of system features should run and and will be processed after any user features have run. If a script is found, then Sentinel will execute it.

Tip

The pre, user and post scripts are resolved via a SentinelSelectionKey based lookup.

See: Managing Session Plans to learn how to associate a feature execution script to a point-in-session.

Responding to Features that Fail

Some system features are more important to the correct behaviour of Sentinel than others. For example, it is critical that a fundamental system feature such as the B2BUA feature feature runs successfully, otherwise the integrity of the active session is questionable.

Sentinel supports a variant of the run statement called runcritical. The runcritical statement works in exactly the same way as run except that Sentinel has additional behaviour if a runcritical feature fails. For example, the default pre script used at the Sentinel SIP session accept point-in-session is:

featurescript PreSessionAccept {
    runcritical B2BUA
}
Tip

A feature can fail in a number of way. If might issue featureCannotStart() or featureFailedToExecute() so Sentinel knows there was a problem. A feature may accidentally throw an unchecked exception, which Sentinel will manage by treating the feature as if it had featureFailedToExecute().

In particular, Sentinel monitors the execution of critical features in a pre script. If any critical feature in a pre script fails, then Sentinel will not try to find, and execute, a user scripts for the active point-in-session. It will still try to find and execute a post script.

Tip

See: The run Statement for more detail on the run statement and its syntax.

Sentinel SIP Feature Execution Script Predicates

Features in Sentinel SIP interact with EventManagers to control the behaviour of the system. Feature execution scripts can use conditions containing predicates which expose the internal state of the EventManagers.

Below are details of LegManager and ChargingManager predicates.

LegManager predicates

Predicate name Supersedes True when…​

LegManager.endSession

feature.endSession

a feature has requested endSession in this execution point

LegManager.currentLeg

there is a leg active at the current execution point

LegManager.currentLinkedLeg

the current execution point has an active leg linked to a second leg

LegManager.currentLeg.releaseLeg
LegManager.currentLinkedLeg.releaseLeg

feature.releaseLeg

there is a pending releaseLeg on the specified leg (currentLeg and currentLinkedLeg)

LegManager.currentLeg.pendingMessage
LegManager.currentLinkedLeg.pendingMessage

feature.sendMessage
feature.sendCancel

there is a pending message on the specified leg (currentLeg and currentLinkedLeg)

LegManager.proxyAndDoNotRecordRoute

feature.proxyAndDoNoRecordRoute

there proxyAndDoNotRecordRoute instruction on the triggering leg

LegManager.currentLeg.parallelFork
LegManager.currentLinkedLeg.parallelFork

feature.parallelFork

there is a pending parallelFork on the specified leg (currentLeg and currentLinkedLeg)

LegManager.detachAll

feature.terminateProcessing

detachAll has been requested

LegManager.currentLeg.upstreamFork
LegManager.currentLinkedLeg.upstreamFork

feature.upstreamFork

there is a pending upstreamFork on the specified leg (currentLeg and currentLinkedLeg)

LegManager.currentLeg.downstreamFork
LegManager.currentLinkedLeg.downstreamFork

feature.downstreamFork

there is a pending downstreamFork on the specified leg (currentLeg and currentLinkedLeg)

LegManager.currentLeg.endInviteSession
LegManager.currentLinkedLeg.endInviteSession

there is a pending endInviteSession on the specified leg (currentLeg and currentLinkedLeg)

LegManager.currentLeg.endSubscription
LegManager.currentLinkedLeg.endSubscription

there is a pending endSubscription on the specified leg (currentLeg and currentLinkedLeg)

LegManager.currentLeg.detachFromLeg
LegManager.currentLinkedLeg.detachFromLeg

there is a pending detachFromLeg on the specified leg (currentLeg and currentLinkedLeg)

LegManager.currentLeg.hasEndingInstruction
LegManager.currentLinkedLeg.hasEndingInstruction

any of detachAll, detachFromLeg, proxyAndDoNotRecordRoute, endSession, or releaseLeg are true; used as a convenience method to simplify execution script logic

ChargingManager predicates

Predicate name Supersedes What it indicates

ChargingManager.charging

feature.doNotCharge
feature.ceaseCharging

a charging instance exists

ChargingManager.sessionCharging

a session charging instance exists

ChargingManager.sessionCharging.reservation

feature.doCreditCheck

a feature has requested credit reservation

ChargingManager.sessionCharging.finalisation

a feature has requested credit finalisation

ChargingManager.immediateCharging

an immediate event charging instance exists

ChargingManager.immediateCharging.directDebit

a feature has requested a direct debit

ChargingManager.immediateCharging.refund

a feature has requested a refund

Feature Extension Events

Sentinel provides a mechanism that features may use to interact with external resources and receive incoming messages as events. These incoming events are called “extension events”.

When would you use an extension event?

There are many situations where a feature may need to interact with an external resource as a part of its business logic. For example, it may need to query a network element via HTTP.

The following sections explains how you may develop features that use the extension event mechanism:

Note Extension Events are currently only available in the Sentinel SIP frontend, but the concept eventually will be extended to the other cores.

What you need to know to use extension events

To use extension events, you need to know:

  • how to write an event handler method that is triggered in receipt of events from an external resource

  • how a feature can process an extension event

  • how to use the SentinelEndpoint to tell Sentinel about activities your feature has created.

The following high-level diagram shows how these three processes work together.

extension event
Figure 9. Sentinel extension events

  1. Sentinel is triggered by an event that starts a new session (such as an INVITE request).

  2. While processing the request, Sentinel triggers a feature MyFeature and calls startFeature(), with the INVITE as the trigger event.

  3. MyFeature sends a message to an external resource (Network Element) as a part of its business logic (request).

  4. The Network Element responds. An event is received (response — an extension event), which triggers an event handler method in MyFeature SBBPart (onEvent()).

  5. MyFeature SBBPart delegates to Sentinel (by using the SentinelEndpoint) to deliver the response extension event.

  6. Sentinel routes the extension event to MyFeature for processing and calls startFeature(), with the response as the trigger event.

When are extension events processed?

Extension events may be processed when:

Feature blocks and waits for the extension event

In this scenario a feature creates an outgoing session to an external resource and waits for the response before continuing. In this case no other feature will run until a response is received, or the feature times out.

extension event blocking
Figure 10. Feature waits for the extension event before returning

Here, a feature (MyFeature) creates an outgoing session to an external resource (Network Element).
MyFeature:

  • uses a provider object related to the external resource

  • creates a new session

  • gets a SLEE ActivityContextInterface related to the session

  • uses the attach operation on the feature endpoint to tell Sentinel about the new activity; Sentinel attaches to this activity so incoming messages related to this activity can be received as events

  • sends a message to the external resource (request).

MyFeature does not return control to Sentinel, and is waiting for a response from the external resource. The current feature execution script is still active, and no more features will run in txn #1.

At some point in the future, Network Element will finish its work and generate a response. MyFeature SBBPart has an event handler method for response events that is triggered in txn #2. The event handler method will delegate to Sentinel to route the event by using the SentinelEndpoint and calling processEvent() with the response event and the name of the feature to be triggered ("MyFeature").

Sentinel routes the response event to MyFeature by calling startFeature() with response as the trigger event. MyFeature will continue its work and then return control to Sentinel by sending featureHasFinished(). The current feature execution script will continue in txn #2 and further features may run.

Note

  • The feature execution script that starts MyFeature spans two SLEE transactions (the script starts in txn #1 and ends in txn #2).

  • A feature that is waiting for a response on an activity will receive an ActivityEndEvent if the activity ends without a response event being delivered into the SLEE.

Feature does not block and is invoked later with the extension event

In this scenario, a feature creates an outgoing session to an external resource and returns control to Sentinel immediately. In this case, other features may run whilst the external resource does its work.

extension event non block
Figure 11. Feature returns immediately and is triggered in the future with the extension event

Here a feature (MyFeature) creates an outgoing session to an external resource (Network Element).
MyFeature:

  • uses a provider object related to the external resource

  • creates a new session

  • gets a SLEE ActivityContextInterface related to the session

  • uses the attach operation on the feature endpoint to tell Sentinel about the new activity; Sentinel attaches to this activity, so incoming messages related to this activity can be received as events

  • sends a message to the external resource (request)

  • returns control to Sentinel by sending featureHasFinished().

The current feature execution script will continue and other features may run in txn #1.

At some point in the future, Network Element will finish its work and generate a response. MyFeature SBBPart has an event handler method for response events that is triggered in txn #2. The event handler method will delegate to Sentinel to route the event by using the SentinelEndpoint and calling processEvent() with the response event and the name of the feature to be triggered ("MyFeature").

Sentinel routes the response event to MyFeature by calling startFeature() with response as the trigger event. MyFeature will continue its work and then return control to Sentinel by sending featureHasFinished(). In this case, MyFeature has been invoked directly, so no other feature will run as a consequence of Sentinel receiving the response event in txn #2.

Note

The feature execution script that starts MyFeature runs to completion within one SLEE transactions (the script starts and ends in txn #1).
Tip

A feature may include the name of a different feature to be invoked.

Writing a feature that uses extension events

The following example shows how to write a feature that uses extension events.

Requirements

A feature SendHttpRequestAndWaitFeature will create a new outgoing http activity and issue a GET request. +It must wait to be invoked a second time with an http response (an extension event).

There are two aspects to developing this feature:

  1. Writing the feature

  2. Writing the feature SBBPart

Writing the feature

SendHttpRequestAndWaitFeature sends and receives http messages, so it needs access to an http provider. The implementation of startFeature() can then use the http provider to create an outgoing http session and receive an http response.

Injecting the http provider

In the following code sample, the raProviderJndiNames attribute of the @SentinelFeature annotation is set with values for the http provider and the http activity context interface factory. The feature implements InjectResourceAdaptorProvider and stores references to the provider and activity context interface factory objects in private attributes of the feature class:

@SentinelFeature(
    featureName = SendHttpRequestAndWaitFeature.NAME,
    // ...
    raProviderJndiNames = {
        "slee/resources/http/provider",
        "slee/resources/http/activitycontextinterfacefactory"
    }
)
// ...
public class SendHttpRequestAndWaitFeature
        extends BaseFeature<NullSentinelSessionState, SentinelSipMultiLegFeatureEndpoint>
        implements InjectResourceAdaptorProvider
{
    // ...
    @Override
    public void injectResourceAdaptorProvider(Object provider) {
        if(provider instanceof HttpProvider){
            this.httpProvider = (HttpProvider)provider;
        }
        else if(provider instanceof HttpActivityContextInterfaceFactory){
            this.httpAciFactory = (HttpActivityContextInterfaceFactory)provider;
        }
    }
    // ...
    private HttpProvider httpProvider;
    private HttpActivityContextInterfaceFactory httpAciFactory;
}
Implementing startFeature()

The startFeature() method can be invoked with three types of trigger object:

  • an INVITE — SendHttpRequestAndWaitFeature creates and sends a new GET request using the http provider. It uses the http activity context interface factory to get the SLEE ActivityContextInterface related to the new outgoing activity, and tells Sentinel to attach(httpAci). Any incoming events will be received by Sentinel (and then routed to SendHttpRequestAndWaitFeature as an extension event). In this scenario, SendHttpRequestAndWaitFeature waits for a response before ending, so it issues featureWaiting(). The script within which SendHttpRequestAndWaitFeature is triggered will complete in the SLEE transaction associated with the http response event.

  • an HttpResponse — SendHttpRequestAndWaitFeature simply traces properties of the HttpResponse and issues featureHasfinished(). The script within which SendHttpRequestAndWaitFeature is triggered will now continue within this SLEE transaction

  • an ActivityEndEvent — SendHttpRequestAndWaitFeature issues featureHasfinished(). The script within which SendHttpRequestAndWaitFeature is triggered will now continue within this SLEE transaction.

Note

A feature can only receive an ActivityEndEvent on an activity on which it has issued featureWaiting().

For example:

@Override
public void startFeature(Object trigger, Object activity, ActivityContextInterface aci) {
    final Tracer tracer = getTracer();

    if (trigger instanceof HttpResponse) {
        // I am being invoked a second time with the http response
        final HttpResponse httpResponse = (HttpResponse) trigger;
        if (tracer.isFinerEnabled()) {
            tracer.finer("Received an HttpResponse: " + httpResponse);
            tracer.finer(" StatusCode : " + httpResponse.getStatusCode());
            tracer.finer(" StatusReason : " + httpResponse.getStatusReason());
        }
        // now I am done
        getCaller().featureHasFinished();

        if(tracer.isFineEnabled()) tracer.fine("Feature has finished");
    }
    else if (trigger instanceof ActivityEndEvent) {
        // I am being invoked with an ActivityEndEvent ... something went wrong!
        getCaller().featureFailedToExecute(
            new FeatureError(FeatureError.Cause.unclassified,
                             "Received an ActivityEndEvent instead of an HttpResponse"));
        getCaller().featureHasFinished();

        if(tracer.isFineEnabled())
            tracer.fine("Received an ActivityEndEvent ... feature has finished");
    }
    else {
        // I am being invoked the first time with an INVITE
        try {
            // create the request
            final HttpRequest request =
                httpProvider.createRequest(HttpRequest.GET, new URL(DESTINATION));

            // send the request
            final OutgoingHttpRequestActivity httpActivity =
                httpProvider.sendRequest(request);
            final ActivityContextInterface httpAci =
                httpAciFactory.getActivityContextInterface(httpActivity);

            // ... and attach to the activity
            getCaller().attach(httpAci);

            // not finished yet, I expect to be invoked a second time with an extension
            // event (the http response).
            if(tracer.isFineEnabled())
                tracer.fine("Alerting core that feature is waiting on activity: " + httpAci);
            getCaller().featureWaiting(httpAci);
        }
        catch (IOException e) {
            // I failed, record the error and finish
            getCaller().featureFailedToExecute(
                new FeatureError(FeatureError.Cause.unclassified,
                                 "Exception sending HTTP Request",
                                 e));
            getCaller().featureHasFinished();
        }
    }
}

Writing the feature SBBPart

The SendHttpRequestAndWaitFeature needs a companion SBB part that has an event handler method for HTTP response events. The event handler method uses the SentinelEndpoint to request Sentinel to route the event to a named feature.

Accessing HTTP resource adaptor classes

The SBB part needs access to HTTP resource adaptor classes such as the HttpResponse event. Adding an @RATypeBindings annotation to the SBB part class will ensure that SendAndReceiveHttpSbbPart can access all HTTP resource adaptor type classes. Like so:

@SBBPart(
    id = @ComponentId(name = "...", vendor = "...", version = "..."),
    // ...
    sbbPartClasses = @SBBPartClasses(
        sbbPartClass = @SBBPartClass(
            className="com.opencloud.sentinel.feature.eventhandler.SendHttpRequestAndWaitSbbPart"
        )
    )
)
@RATypeBindings(
    raTypeBindings = {
        @RATypeBinding(
            raType = @ComponentId(name = "HTTP", vendor = "OpenCloud", version = "2.2")
        )
    }
)
public class SendHttpRequestAndWaitSbbPart {
    // ...
}

Implementing the event handler method

The SendHttpRequestAndWaitSbbPart event handler method (onHttpResponse) has an @EventMethod annotation for the HttpResponse event. When an HttpResponse event is received by the SLEE, it will trigger the SendAndReceiveHttpSbbPart event handler method onHttpResponse. The event handler method gets a reference to the SentinelEndpoint by calling getSbbLocalObject() on the SBB part context and casting the result to SentinelEndpoint. The httpResponseEvent is delivered by calling processEvent on the SentinelEndpoint, with:

  • the name of the feature to invoke

  • the httpResponseEvent object

  • the associated ActivityContextInterface and EventContext objects.

For example:

@EventMethod(
    initialEvent = false,
    eventType = @ComponentId(name = "com.opencloud.slee.resources.http.HttpResponse",
                             vendor = "OpenCloud",
                             version = "2.2")
)
public void onHttpResponse(HttpResponse httpResponseEvent,
                           ActivityContextInterface aci,
                           EventContext eventContext)
{
    if (rootTracer.isFinerEnabled()) rootTracer.finer("Received: " + httpResponseEvent);

    final String featureToInvoke = "SendHttpRequestAndWaitFeature";
    try {
        // get the SentinelEndpoint
        final SentinelEndpoint sentinelEndpoint =
            (SentinelEndpoint)sbbPartContext.getSbbLocalObject();
        // process the http response by calling the 'featureToInvoke' feature
        sentinelEndpoint.processEvent(featureToInvoke, httpResponseEvent, false, aci, eventContext);
    }
    catch (Exception e) {
        rootTracer.fine("Caught exception in processEvent for HttpResponse", e);
    }
}

@Inject private Tracer rootTracer;
@Inject private SbbPartContext sbbPartContext;
Tip

Remember that the SendHttpRequestAndWaitFeature told Sentinel to attach to the outgoing http activity. Sentinel will therefore receive all incoming http events (such as the httpResponseEvent) on this activity.

Whilst this simple example hard-codes the name of the feature to invoke as "SendAndReceiveHttpFeature", the SBB part may include the name of any feature to invoke. For example, it might derive the name of the feature to invoke from parameters of the received event.

Service Timer Provider

What is the ServiceTimerProvider?

The ServiceTimerProvider API can be used by features to set feature specific timers and receive TimerEvents, when the timers fire.

Note ServiceTimerProvider is currently only available in the Sentinel SIP frontend, but the concept eventually will be extended to the other cores.
Tip

The full ServiceTimerProvider API is available here.

Accessing the ServiceTimerProvider

A feature gets a reference to a ServiceTimerProvider as a resource adaptor provider object with the well known name "sentinel/servicetimerprovider". Your feature should implement InjectResourceAdaptorProvider as shown in the example below.

@SentinelFeature(
    featureName = MyFeature.NAME,
    ...
    raProviderJndiNames = "sentinel/servicetimerprovider"
)
...
public class MyFeature
        extends BaseFeature<..., ...>
        implements InjectResourceAdaptorProvider
{
    // ...

    @Override
    public void injectResourceAdaptorProvider(Object provider) {
        if(provider instanceof ServiceTimerProvider){
            this.serviceTimerProvider = (ServiceTimerProvider)provider;
        }
    }

    private ServiceTimerProvider serviceTimerProvider;

    public static final String NAME = "MyFeature";
}

Processing Service Timer Events

The purpose of the ServiceTimerProvider is to provide features with a mechanism to be triggered at a scheduled time in the future via a TimerEvent. Service Timer Events may be processed by:

  1. directly invoking a feature

  2. invoking a feature execution script

In general, features should not attempt to perform their own Timer management using the SLEE Timer Facility. Instead, they should use the ServiceTimerProvider to perform all timer operations.

Processing a Service Timer Event by Directly Invoking a Feature

If you want Sentinel to directly invoke a particular feature when your timer fires, use the setTimer operations of the SentinelTimerProvider interface that take a String feature name as the first argument. For example:

// set a timer to expire in 5000ms, and cause a feature to be invoked.
long nowT = System.currentTimeMillis();
long expireT = nowT + 5000; // expire in 5000ms from now
TimerID timer = timerProvider.setTimer(NAME,     // invoke me when the timer fires
                                       expireT); // when to expire
Tip

You may also register an existing Timer with the ServiceTimerProvider (and have the TimerEvents processed by a named feature) with the registerTimer operation.

In the following diagram, a feature MyFeature sets a timer using the ServiceTimerProvider. The ServiceTimerProvider remembers that MyFeature should be triggered when the timer expires and uses the SLEE timer facility to set the timer. Finally the feature tells Sentinel it is done via featureHasFinished().

At some point in the future the timer expires. The SLEE triggers Sentinel in a new SLEE transaction. Sentinel defers to the ServiceTimerProvider to find the name of a feature to invoke, and then directly invokes it by calling startFeature() with the TimerEvent as the trigger.

service timer to feature
Figure 12. Setting up a feature timer that will trigger a feature directly on a TimerEvent
Tip

A feature may set several timers.

A feature may include the name of a different feature to be invoked.

Processing a Service Timer Event by Invoking a Feature Execution Script

If you want Sentinel to find, and run, a feature execution script when your timer fires, use the setTimer operations of the SentinelTimerProvider interface that do not take a feature name argument. For example:

// set a timer to expire in 5000ms, and cause a feature execution script to be run.
long nowT = System.currentTimeMillis();
long expireT = nowT + 5000; // expire in 5000ms from now
TimerID timer = timerProvider.setTimer(expireT); // when to expire
Tip

You may also register an existing Timer with the ServiceTimerProvider (and have the TimerEvents processed by a feature execution script) with the registerTimer operation.

In the following diagram, a feature MyFeature sets a timer using the ServiceTimerProvider. The ServiceTimerProvider uses the SLEE timer facility to set the timer. Finally the feature tells Sentinel it is done via featureHasFinished().

At some point in the future the timer expires. The SLEE triggers Sentinel in a new SLEE transaction. Sentinel searches for a feature execution script to run at the SipAccess_ServiceTimer feature script execution point using the current value of the SentinelSelectionKey. If a script is found, then Sentinel will run it.

service timer to script
Figure 13. Setting up a feature timer that will trigger a feature execution script on a TimerEvent
Tip

See section Sentinel Selection Key for more information about the sentinel selection key.

See section Feature Execution Scripts for more information about feature execution scripts.

Cancelling a Timer

You cancel a timer that has been registered with the ServiceTimerProvider with the cancelTimer operation. For example:

// get the TimerID from session state
final TimerID timerID = sessionState.getNoResponseTimerID();
if (timerID != null) {
    if (facilities.getTracer().isFinestEnabled())
        facilities.getTracer().finest("Cancelling NoResponse timer: " + timerID);
    // if we have a timer, then cancel it
    timerProvider.cancelTimer(timerID);
}

Testing if a Timer is Set

You can check if a timer is currently set and registered with the provider with the timerIsSet operation. For example:

final TimerID timerID = sessionState.getNoResponseTimerID();
if (timerProvider.timerIsSet(timerID)) {
    // cancel the timer
    timerProvider.cancelTimer(timerID);
}

New Session Counters

Session counters are session and charging activity counters stored in session state. For SIP sessions, "new" session counters replace the original session counters (which are still used with SS7 and Diameter front ends).

What are session counters?

Session counters record the current status of the charging activity in a session. The CDR written for a session includes session counter data that records the final status of the charging when the session ended.

This data may be used in post-processing, for:

  • determining any undebited units for the session

  • statistical purposes, such as reporting on granted free units that are otherwise not recorded

  • reconciliation of Sentinel with the OCS

  • analysis of any issues encountered during Sentinel operations.

Session counter structure

Session counters are stored in a ChargingInstance which is accessed from the ChargingManager. Each charging instance contains one or more session counters. A session counter has an address that consists of a set of name/value pairs and is unique for the charging instance.

The ChargingManager is accessed via the SentinelSipMultiLegFeatureEndpoint. For example:

ChargingInstance chargingInstance = getCaller().getChargingManager()
               .getChargingInstance(B2BUAChargingFeatureUtil.DEFAULT_ECUR_CHARGING_INSTANCE);
SessionCounters sessionCounters = chargingInstance.getSessionCounters();

Each session counter has the following fields:

Field name Purpose Details

Counter Addressing

 
address

Counter addressing

Set of name/value pairs uniquely identifying this session counter within a charging instance.

Session Time and Duration

 
startTime

Session start time

The start time is recorded when the session starts consuming units. For instance, when the session is established. Milliseconds since the epoch (January 1, 1970, 00:00:00 GMT).

 
endTime

Session end time

The end time is recorded when the session ceases consuming units. For instance, when the session being charged is terminated. Milliseconds since the epoch (January 1, 1970, 00:00:00 GMT).

 
cumulativeSuspendedDuration

Cumulative suspended duration

Cumulative duration of all periods where charging on the session was suspended in milliseconds.

 
grantedUnitValidityExpiry

Unit validity

Expiry time for granted units in milliseconds since the epoch (January 1, 1970, 00:00:00 GMT).

Unit Counters

 
reportedUsed

Units reported as used to be sent in the next CCR

 
pendingRequested

Units to be requested in the next CCR

 
cumulativeRequested

Cumulative requested unit reservations

Sum of Requested-Service-Units in CCR Multiple-Service-CreditControl AVPs associated with this counter.

 
cumulativeGranted

Cumulative granted unit reservations

Sum of Granted-Service-Units in CCA Multiple-Service-CreditControl AVPs associated with this counter.

 
cumulativeSentUsed

Cumulative used units

Sum of Used-Service-Units in CCR Multiple-Service-CreditControl AVPs associated with this counter.

 
cumulativeCommittedUsed

Cumulative committed used units

Sum of Used-Service-Units in CCR Multiple-Service-CreditControl AVPs associated with this counter which have received a CCA response successfully.

 
cumulativeRequestedRefund

Cumulative requested refund units

Sum of Requested-Service-Units in CCR(REFUND) Multiple-Service-CreditControl AVPs.

 
cumulativeGrantedRefund

Cumulative requested refund units

Sum of Requested-Service-Units in CCR(REFUND) Multiple-Service-CreditControl AVPs associated with this counter which have received a CCA response successfully.
Important The values stored in counters are not strictly related to Diameter CCR and CCA AVP values but may be used for other purposes. For instance, session counter fields may record charging activity of promotions which do not use Diameter or the charging activity of a non-Diameter charging protocol.

The Session Time, Duration, and Unit Counters fields are maintained by Sentinel system features. Where necessary, user features may update the reportedUsed and pendingRequested fields for counters created by system features. Session counters added by user features may have all fields updated by the user features as required.

Access to session counters is via a SessionCounters interface:

Function Description 
getAddresses

Get a list of the addresses of all session counters.

 
add

Add a new session counter.

 
get

Get a session counter for an address.

 
getSessionCounters

Get all session counters.

 
getSessionCountersByAddressSubset

Get all session counters which have addresses which are a subset of the requested address.

 
getAggregateSessionCounter

Get a session counter which contains the aggregated values of all session counters which have addresses that are supersets of the requested address.

Default address name values

The following default address name values are used in the system. Other values may be used as required by the feature developer.

Cc-Total-Octets
Cc-Service-Specific-Units
Cc-Output-Octets
Cc-Input-Octets
Cc-Money
Cc-Time
Cc-Unit-Type
Rating-Group
Service-Id
Subscriber-Id

Counter update algorithm pseudo code

Here is the counter update algorithm pseudo code, which updates counters for granted units.

Create a list of session counters which have pendingRequested units
Create a list MSCCs with Granted-Service-Units from the CCA

// Handle the common case where there is a single MSCC/GSU and single session counter expecting granted units
IF there is one and only one MSCC
   AND one session counter awaiting granted units
   AND MSCC GSU unit type is an address key of session counter THEN

    Perform GSU updates to the session counter using values from MSCC

    RETURN
ENDIF


// Exact matching cases
FOREACH MSCC DO

    Create a session counter address for the MSCC based on configured ordered list of AVPs to consider (e.g. [Unit-Type, Service-Id, Rating-Group, Custom-Attribute]

    Get session counter from charging instance using session counter address calculated from the MSCC

    IF a session counter exists for the MSCC address THEN

        Perform GSU updates to the session counter using values from MSCC

        Mark MSCC processed

        CONTINUE
    ENDIF

DONE

// Best effort matching
FOREACH unmatched MSCC DO

    Create a session counter address from the MSCC using the configured ordered list of AVPs to
    consider (e.g. [Service-Id, Rating-Group, Unit-Type, Custom-Attribute])

    Create a list of addresses based on the configured ordered list of AVPs with first address
    including all then removing the last AVP until only first address left i.e.
    [[Unit-Type, Service-Id, Rating-Group, Custom-Attribute],
     [Unit-Type, Service-Id, Rating-Group],
     [Unit-Type, Service-Id],
     [Unit-Type]]

    FOREACH address DO
        Get matching session counters

        IF there is a matching session counter THEN

            Perform GSU updates to the first session counter

            Mark MSCC processed

            CONTINUE
        ENDIF
    DONE
DONE

// Record values from any unmatched MSCCs
FOREACH unmatched MSCC DO

    Create a new session counter using the full MSCC session counter address if it does not already exist.

    Perform GSU updates to the session counter using values from MSCC.  Surplus units for an existing
    counter will be applied to the counter at this point.
DONE

Updates for sent used units on successfully sending a CCR-U or CCR-T to the OCS:

IF CCR-U or CCR-T with USU sent THEN
    Update cummulativeSentUsed for the counter matching the MSCC
ENDIF

Updates for committed used units on receiving a CCA-U or CCR-T from the OCS:

Update cummulativeCommittedUsed values for all USU sent in the CCR

Session counter address mappers

The SipRequestToSessionCounterAddress mapper creates the default session counter address for SIP sessions.

The CCAToSessionCounterList mapper creates a list of GSU counters which are processed by the counter update algorithm. The priority order of the address name/value pairs is based on the order in which the name/value pairs are added when creating the address.

Below are three examples:

SIP call with session charging with unit reservation

The following session counter shows the charging values at the end of the SIP call. The call has a successful 60s reservation and is 5s long . All units are successfully committed in the OCS.

Point in call flow Pending Requested Reported Used Requested Granted Sent Used Committed Used

1 CCR-I

1.1 new charging instance

 
60000
 
0
 
0
 
0
 
0
 
0

1.2 CCR-I sent

 
60000
 
0
 
60000
 
0
 
0
 
0

1.3 CCA-I received

 
0
 
0
 
60000
 
60000
 
0
 
0

2 CCR-U

2.1 Charging Timer Expiry

 
60000
 
60000
 
60000
 
60000
 
0
 
0

2.2 CCR-U sent

 
60000
 
0
 
120000
 
60000
 
60000
 
0

2.3 CCA-U received

 
0
 
0
 
120000
 
120000
 
60000
 
60000

3 CCR-T

3.1 Party hangs up

 
0
 
30000
 
120000
 
120000
 
60000
 
60000

3.2 CCR-T sent

 
0
 
0
 
120000
 
120000
 
90000
 
60000

3.3 CCA-T received

 
0
 
0
 
120000
 
120000
 
90000
 
90000

Final counter state:

address:                       {"Subscriber-Id":"tel:34600000002",
                                "Cc-Unit-Type":"Cc-Time",
                                "Service-Id":"1"}
reportedUsed:                  0
pendingRequested:              0
cumulativeRequested:      120000
cumulativeGranted:        120000
cumulativeSendUsed:        90000
cumulativeCommittedUsed:   90000
cumulativeRequestedRefund:     0
cumulativeGrantedRefund:       0
SIP event charging with unit reservation

The following session counter shows the charging values at the end of the SIP event charging session. The session has a successful 1 unit reservation, and 1 unit is used. All units are successfully committed in the OCS.

address:                       {"Subscriber-Id":"tel:34600000002",
                                "Cc-Unit-Type":"Cc-Service-Specific-Units",
                                "Service-Id":"1"}
reportedUsed:                  0
pendingRequested:              0
cumulativeRequested:           1
cumulativeGranted:             1
cumulativeSendUsed:            1
cumulativeCommittedUsed:       1
cumulativeRequestedRefund:     0
cumulativeGrantedRefund:       0
SIP immediate event charging with refund

The following session counter shows the charging values at the end of the SIP event charging session. The session has a successful 1 unit reservation, and 1 unit is used. All units are successfully committed in the OCS.

address:                       {"Subscriber-Id":"tel:34600000002",
                                "Cc-Unit-Type":"Cc-Service-Specific-Units",
                                "Service-Id":"1"}
reportedUsed:                  0
pendingRequested:              0
cumulativeRequested:           1
cumulativeGranted:             1
cumulativeSendUsed:            0
cumulativeCommittedUsed:       0
cumulativeRequestedRefund:     1
cumulativeGrantedRefund:       1

SDP Comparison

What is SDP comparison?

When using Sentinel SIP, the SDP offer answer model is used to negotiate the media streams and associated codecs for the session, and the addition and removal of streams and associated codecs while a session is in progress.

When codecs and the number and type of streams change, Sentinel may consult the SDP media codec configuration to determine if the change was a material change, from a rating conditions perspective. The SDP media codec configuration defines a set of equivalence classes. When the two SDPs being compared have equivalent codecs in the same number of streams, the comparison will return a match which will indicate an immaterial change. When the number of streams or the codecs in the streams are not matched based on the configured equivalence classes, a material change will be indicated.

If the difference between the previous and newly negotiated SDP is material from a rating condition perspective, then Sentinel will perform a client-initiated credit re-authorization towards the Online Charging System (OCS). The OCS will be notified that the reason is due to rating conditions changing. While the re-authorization is in progress, the outgoing message is suspended. On successful response from the OCS, the outbound message processing is resumed.

If the reauthorization fails with a ServiceDenied reason and the message was a SIP UPDATE or INVITE, the newly negotiated SDP is discarded and 401 error response is sent to the originator. A CCR for the previous SDP is sent then to the OCS, to reestablish charging for the session at the previous rate. If this also fails, the session is ended.

If a change is immaterial, then the current credit reservation remains.

Note See SDP Comparison Feature for details on the SDP comparison feature.
Note See SDP Comparison for Rating Condition Change Determination for details of configuring the SDP comparison.

The Sentinel Software Development Kit

What is the Sentinel SDK?

The Sentinel Software Development Kit (SDK) lets you create a custom Sentinel install package. For example:

sentinel sdk roles

  1. A developer from Acme Inc uses the Sentinel SDK installer to create a development environment they can use to create their own custom version of Sentinel. The development environment uses:

    • Apache Ant for building

    • Apache Ivy for dependency management. The development environment resolves OpenCloud dependencies (such as Sentinel core components and libraries, and OpenCloud resource adaptor components and libraries) from an OpenCloud Sentinel Ivy repository.

  2. Acme developers use the Sentinel SDK to create their own version of Sentinel.

  3. The development environment generates a Sentinel install package that includes all the changes created by Acme Inc developers.

Important Only registered users of the Sentinel SDK can resolve the required dependencies from the OpenCloud Ivy repository. Contact OpenCloud for the required credentials to access the OpenCloud Ivy repository.

What can you use it for?

You use the Sentinel SDK to:

  • create your own features (this includes the feature as well as any provisioning elements in the Sentinel Element Manager)

  • create your own mappers

  • add your own extensions to the call detail records (CDRs) that Sentinel writes

  • add new session state fields

  • extend the promotions scripting language

  • add new or modify existing OCS drivers.

Tip See the Sentinel SDK for more information about building a customised Sentinel using the Sentinel SDK.