This document provides a high-level overview of Sentinel.
Topics
-
Introducing Sentinel — what Sentinel is, and the many different ways you can use it
-
Inside Sentinel — the Sentinel architecture and what’s behind it
-
The Sentinel Software Development Kit — how you can build a custom version of Sentinel, using the Sentinel SDK.
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.
Features:
-
is very extensible, flexible, and configurable
-
supports session control for SS7, SIP, and Diameter sessions with a rich set of built-in features
-
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.
 |
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.
| |
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).
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.
| |
The profiles are managed using the Sentinel element manager and the Sentinel machine API. |
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.
-
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
-
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
-
initial installation, the Service ID has name="Sentinel Service", vendor="OpenCloud", version="3.1.0.0"
-
first bind operation occurs, creating a Service ID with name="Sentinel Service", vendor="OpenCloud", version="3.1.0.0-copy#1". This copy is activated.
-
some time passes, and new features are introduced. This may create a new Service ID with name="Sentinel Service", vendor="OpenCloud", version="3.1.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 ("3.1.0.0-copy#1). Yet during the timeline above, at some point, the active Service ID is now "3.1.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.
Service Link Components
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
-
initial installation, the Service ID name="Sentinel Service", vendor="OpenCloud", version="3.1.0.0" is installed, two link components are created
-
Link Component name="Sentinel Service", vendor="OpenCloud", version="current" points to Service ID name="Sentinel Service", vendor="OpenCloud", version="3.1.0.0"
-
Link Component name="Sentinel Service", vendor="OpenCloud", version="3.1.0" points to Service ID name="Sentinel Service", vendor="OpenCloud", version="3.1.0.0"
-
-
first bind operation occurs, creating a Service ID with name="Sentinel Service", vendor="OpenCloud", version="3.1.0.0-copy#1". This copy is activated.
-
both link components are updated such that they point to Service ID with name="Sentinel Service", vendor="OpenCloud", version="3.1.0.0-copy#1"
-
-
some time passes, and new features are introduced. This may create a new Service ID with name="Sentinel Service", vendor="OpenCloud", version="3.1.0.0-copy#2". The earlier copy (-copy#1) is deactivated and the new copy is activated.
-
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="3.1.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:
-
SIS compositions - a composition can use a constant Service ID (link) in the composition
-
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 |
| |
Support for re-INVITE
|
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).
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.
-
 |
The resource adaptors and profiles used in Sentinel charge are the same as Sentinel services. |
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.
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.
There are three layers:
-
Session control — There is a SLEE service per triggering protocol (such as SS7 or Diameter).
-
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).
-
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:
-
feature configuration
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.
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 for the SS7 Service
Sentinel provides three types of session plan for SS7:
-
SS7 sessions initiated via SS7 — This session plan is triggered on receipt of a CAMEL InitialDP.
-
SS7 sessions initiated via third party — This session plan is triggered for a Voice session initiated via 3rd party call setup.
-
SS7 SMS sessions initiated via SS7 — This session plan is triggered on receipt of a CAMEL phase three InitialDPSMS.
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.
Feature script execution points
Below are details of these points-in-session:
| |
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.
| |
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.
| |
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.
Feature script execution points
Below are details of these points-in-session:
| |
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.
Feature script execution points
Below are details of these points-in-session:
 |
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 — This session plan is triggered on receipt of a new SIP INVITE.
-
SIP sessions initiated via third party — This session plan is triggered for a Voice session initiated via third party call setup.
-
SIP sessions initiated via SIP SUBSCRIBE — This session plan is triggered on receipt of a new SIP SUBSCRIBE.
-
SIP sessions initiated via Out of Dialog Transaction — This session plan is triggered on receipt of a out of dialog SIP Request.
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 ( |
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.
Feature script execution points
Below are details of these points-in-session:
|
|
| |
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 |
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.
| |
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.
| |
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 ( |
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.
Feature script execution points
Below are details of these points-in-session:
|
|
| |
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 |
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.
| |
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.
| |
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 ( |
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.
Feature script execution points
Below are details of these points-in-session:
|
|
| |
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 |
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.
| |
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.
| |
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 ( |
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.
Feature script execution points
Below are details of these points-in-session:
|
|
| |
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 |
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.
| |
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.
| |
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 ( |
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.
Feature script execution points
Below are details of these points-in-session:
|
|
| |
The feature endpoint for all sip execution points is |
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.
| |
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.
| |
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.
Feature script execution points
Below are descriptions of these feature script execution points:
| |
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.
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).
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. -
EventManagerpredicates such asLegManager.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 It then runs the |
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:
-
invoke
abortFeature()on the feature that threw the exception -
raise
feature.featureFailedToExecuteto reflect the error -
raise
feature.featureHasFinishedso 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.
| |
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. |
| |
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
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.
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.
| |
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.
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.
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
}
}
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
}
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().
| |
Sentinel also supports a Currently, only the Sentinel SIP front end considers the outcome of a |
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"]
}
|
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 |
|
|---|---|
SS7 rules |
|
SIP rules |
|
Diameter rules |
|
| |
You can make use of these precedence rules by using an 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 |
|
Network Pre Initial Credit Check Session Pre Initial Credit Check Subscriber Pre Initial Credit Check |
|
| |
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 |
featurescript OnNetworkPreCreditCheck {
run EmergencyAndSpecialNumber
if not feature.continueAndClose {
run ClassifyCallScenario
}
}
|
This is an example script that runs within the context of the network operator. The first step is to run the feature This feature will request that Sentinel core should The next statement says that |
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 Otherwise we run the The If that is the case, we then run This feature will request that Sentinel core should |
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.
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:
|
|
At runtime, Sentinel…
|
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:
-
Exact match of from class, to class, respecting mapping point.
-
Generic match for from class, to class, respecting mapping point.
-
Exact match of from class, to class, ignoring mapping point.
-
Generic match for from class, to class, ignoring mapping point.
-
If no mapper was found, throw a
MapperException.
| |
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’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 cost-effective and fully customizable special offers and charging plans
-
allowing OCS-offload during special offers
-
maintaining fair-use policies during “unlimited” offers
-
defining OCS failure-handling policies
-
configuring online or offline charging.
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.
Addresses in an address list are sequences of: 0 … 9, a … f, A … F, #, *, .
| |
You provision address lists using the Sentinel Element Manager. See the Sentinel Administration Guide for details. |
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:
-
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.
 |
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.
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. |
| |
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.
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
75slong and had a successful60sreservation from theAnytimeOnNetpromotions. -
An update reservation to the promotion was unsuccessful, so the OCS was interrogated.
-
The unit reservation of
60sto the OCS was successful, of which15swere 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.
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.
| |
In this session the lower sub-counters have id CCServiceSpecificUnits, which represents the unit type for an SMS session. |
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.
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 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).
| |
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 EndandInstruction Execution Failureevents) 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.
-
| |
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. |
| |
See:
|
Enhanced Sentinel SIP Architecture
Below is a high-level diagram of the enhanced Sentinel architecture of the Sentinel SIP platform.
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.
| |
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:
-
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:
-
Detect meaningful SDP updates and issue a reauthorisation.
-
If the credit check fails, roll back the SDP and reauthorise.
-
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:
-
B2BUA feature creates outgoing leg and schedules INVITE to be B2BUA’d.
-
B2BUAScur perform successful initial credit check, and suspends and resumes outgoing leg.
-
B2BUAScur performs recurring reauths.
-
B2BUAScur handles RAR.
-
Re-INVITE with meaningful SDP change triggers reauth by SDP Comparison.
-
Reauth fails and SDP reverts, followed by reauth, which is successful with final units indicated, allowing the call to continue with original parameters.
-
The charging timer fires; however since final units were indicated on the latest CCA, instead of a reservation, B2BUAScur instructs endSession.
-
All legs end, triggering a successful credit finalisation by B2BUAScur.
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.
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.
The next scenario shows an IEC direct debit and refund on a SIP error:
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) |
|
HTTP |
an external HTTP-enabled network element |
an HTTP |
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 |
|
Local |
raised internally by Sentinel, as a result of processing other events and instructions |
|
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, andAbortSessionRequest. -
determining the set of feature script execution points that are relevant for a particular event
For example, the Charging Manager determines that the
SipAccess_CreditAllocatedPostCCshould be triggered when Sentinel receives a successfulCreditControlAnswerin response to an initial credit reservation. -
managing a set of pending instructions
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, andRefund. Instructions are queued as features execute, so a feature can make changes to the set of pending instructions.
| |
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:
As shown above:
1 |
Sentinel receives a real event, such as an Loop
Until the |
||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
2 |
Event managers process the received event. They:
|
||||||||||
3 |
If there are any |
||||||||||
4 |
Process each Features may set timers or create sessions to external network elements. Related
Once all |
||||||||||
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 Once all pending instructions have been processed, then see if there are any events in the |
||||||||||
6 |
Event processing ends once the session ends. |
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).
-
There is one
ChargingManagerinstance for each session. -
Each
ChargingManagermay manage one or more charging instances. For example, the diagram shows that there is both SCUR and IEC based charging involved in the session.
| |
The first release implementation of the 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 |
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.
| |
See Using the SIP Leg Manager to learn how features access and use the |
Sentinel SIP Feature Execution Points
Enhanced Feature Execution Model
Sentinel SIP has improved the feature execution model in three important areas:
-
Added the concept of a
System Feature. Other features are now consideredUser Features -
Added the
runcriticalstatement to the feature execution script language -
Expanded the method for how a feature script execution point is processed. In the new model a
point-in-sessionis processed in three steps with aprescript,userscript and apostscript.
| |
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.
User and System Features
There are two types of feature:
-
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
-
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
| |
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-sessioncalled 'feature script execution points'. Thesepoints-in-sessioncorrespond 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-sessionand the current value of theSentinelSelectionKey -
feature execution scripts always run to completion. That is, if a feature fails, then Sentinel will continue with the next feature.
-
Sentinel only takes action only after the
point-in-sessionhas been processed
| |
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).
-
Sentinel searches for a
prescript. Aprescript defines how a number ofsystem featuresshould run and and will be processed before anyuserfeatures are run. If a script is found, then Sentinel will execute it. -
If none of the critical features in the
prescript failed, then Sentinel searches for auserscript. Auserscript defines how a number ofuser featuresshould run. If a script is found, then Sentinel will executes it. If any of the critical features in theprescript failed, then Sentinel does not search for auserscript and skips to step 3. -
Sentinel searches for a
postscript. Apostscript defines how a number ofsystem featuresshould run and and will be processed after anyuserfeatures have run. If a script is found, then Sentinel will execute it.
| |
The See: Managing Session Plans to learn how to associate a feature execution script to a |
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
}
| |
A feature can fail in a number of way. If might issue |
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.
| |
See: The |
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 |
feature.releaseLeg |
there is a pending releaseLeg on the specified leg (currentLeg and currentLinkedLeg) |
LegManager.currentLeg.pendingMessage |
feature.sendMessage |
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 |
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 |
feature.upstreamFork |
there is a pending upstreamFork on the specified leg (currentLeg and currentLinkedLeg) |
LegManager.currentLeg.downstreamFork |
feature.downstreamFork |
there is a pending downstreamFork on the specified leg (currentLeg and currentLinkedLeg) |
LegManager.currentLeg.endInviteSession |
there is a pending endInviteSession on the specified leg (currentLeg and currentLinkedLeg) |
|
LegManager.currentLeg.endSubscription |
there is a pending endSubscription on the specified leg (currentLeg and currentLinkedLeg) |
|
LegManager.currentLeg.detachFromLeg |
there is a pending detachFromLeg on the specified leg (currentLeg and currentLinkedLeg) |
|
LegManager.currentLeg.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 |
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:
| |
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
SentinelEndpointto tell Sentinel about activities your feature has created.
The following high-level diagram shows how these three processes work together.
-
Sentinel is triggered by an event that starts a new session (such as an
INVITErequest). -
While processing the request, Sentinel triggers a feature
MyFeatureand callsstartFeature(), with theINVITEas the trigger event. -
MyFeaturesends a message to an external resource (Network Element) as a part of its business logic (request). -
The
Network Elementresponds. An event is received (response— anextension event), which triggers an event handler method inMyFeature SBBPart(onEvent()). -
MyFeature SBBPartdelegates to Sentinel (by using theSentinelEndpoint) to deliver theresponseextension event. -
Sentinel routes the
extension eventtoMyFeaturefor processing and callsstartFeature(), with theresponseas 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.
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
ActivityContextInterfacerelated to the session -
uses the
attachoperation 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.
| |
|
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.
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
ActivityContextInterfacerelated to the session -
uses the
attachoperation 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.
| |
The feature execution script that starts |
| |
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.
A feature
SendHttpRequestAndWaitFeaturewill create a new outgoing http activity and issue a GET request. +It must wait to be invoked a second time with an http response (anextension event).
There are two aspects to developing this feature:
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—SendHttpRequestAndWaitFeaturecreates and sends a newGETrequest using the http provider. It uses the http activity context interface factory to get the SLEEActivityContextInterfacerelated to the new outgoing activity, and tells Sentinel toattach(httpAci). Any incoming events will be received by Sentinel (and then routed toSendHttpRequestAndWaitFeatureas an extension event). In this scenario,SendHttpRequestAndWaitFeaturewaits for a response before ending, so it issuesfeatureWaiting(). The script within whichSendHttpRequestAndWaitFeatureis triggered will complete in the SLEE transaction associated with the http response event. -
an
HttpResponse—SendHttpRequestAndWaitFeaturesimply traces properties of theHttpResponseand issuesfeatureHasfinished(). The script within whichSendHttpRequestAndWaitFeatureis triggered will now continue within this SLEE transaction -
an
ActivityEndEvent—SendHttpRequestAndWaitFeatureissuesfeatureHasfinished(). The script within whichSendHttpRequestAndWaitFeatureis triggered will now continue within this SLEE transaction.
| |
A feature can only receive an |
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
httpResponseEventobject -
the associated
ActivityContextInterfaceandEventContextobjects.
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;| |
Remember that the Whilst this simple example hard-codes the name of the feature to invoke as |
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.
| |
ServiceTimerProvider is currently only available in the Sentinel SIP frontend, but the concept eventually will be extended to the other cores. |
| |
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:
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| |
You may also register an existing Timer with the |
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.
| |
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| |
You may also register an existing Timer with the |
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.
| |
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 |
cumulativeGranted |
Cumulative granted unit reservations |
Sum of |
cumulativeSentUsed |
Cumulative used units |
Sum of |
cumulativeCommittedUsed |
Cumulative committed used units |
Sum of |
cumulativeRequestedRefund |
Cumulative requested refund units |
Sum of |
cumulativeGrantedRefund |
Cumulative requested refund units |
Sum of |
| |
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. |
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.
DONEUpdates 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
ENDIFUpdates for committed used units on receiving a CCA-U or CCR-T from the OCS:
Update cummulativeCommittedUsed values for all USU sent in the CCRSession 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: 0SIP 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: 0SIP 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: 1SDP 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.
| |
See SDP Comparison Feature for details on the SDP comparison feature. |
| |
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:
-
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.
-
-
Acme developers use the Sentinel SDK to create their own version of Sentinel.
-
The development environment generates a Sentinel install package that includes all the changes created by Acme Inc developers.
| |
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.
| |
See the Sentinel SDK for more information about building a customised Sentinel using the Sentinel SDK. |