# Sentinel Overview and Concepts

Sentinel Express - Version 2.7.1

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.

### Audience and scope

#### Intended audience

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

#### Scope

This document provides an overview of the OpenCloud Sentinel product.

## Introducing Sentinel

### What is Sentinel?

Sentinel is a services platform and a powerful services framework.

#### Sentinel is a services platform …​

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

Features:

- is very extensible, flexible, and configurable

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

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

- supports multi-tenancy to support MVNO configurations

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

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

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

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

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

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

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

- Sentinel for SS7

- Sentinel for SIP

- Sentinel for Diameter to Diameter

- Logical Service ID

## Sentinel for SS7

What does it provide? | Sentinel as an SCP
Front-end interfaces | SS7, HTTP
Session plans | SS7 SMS sessions initiated via SS7 SS7 sessions initiated via SS7 SS7 sessions initiated via third party
Features | General Features — features usable in many networks Query And Notification Features — features for querying GSM network elements and sending notifications Mediation and promotion features — used when communicating with one or more OCS CAMEL Features — features for CAMEL networks

## Logical Service ID

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

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

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

### Motivation for a Logical Service ID

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

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

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

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

As an example the following timeline can occur

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Sentinel for SIP

What does it provide? | Sentinel as a SIP AS
Front-end interfaces | SIP, HTTP
Session plans | SIP sessions initiated via SIP INVITE SIP sessions initiated via third party SIP sessions initiated via SIP SUBSCRIBE SIP sessions initiated via Out of Dialog Transaction SIP sessions initiated via Third Party REGISTER Request
Features | General Features — features usable in many networks Query And Notification Features — features for querying GSM network elements and sending notifications Mediation and promotion features — used when communicating with one or more OCS SIP Features

| Support for re-INVITE Sentinel emits re-INVITEs as a means to check activity liveness and accepts/proxies re-INVITEs mid-session. Sentinel does not (yet) implement the rules outlined in RFC3261 and RFC6141 to update the SDP or participate in SDP negotiation.

## Sentinel for Diameter to Diameter

What does it provide? | Diameter to Diameter mediation scenarios
Front-end interfaces | Diameter Ro, HTTP
Session plans | Diameter Mediation
Features | General Features — features usable in many networks Query And Notification Features — features for querying GSM network elements and sending notifications Mediation and promotion features — used when communicating with one or more OCS Diameter Service Features — features for Diameter-Diameter mediation

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

### Sentinel Charge

What does it provide? | Sentinel Charge provides the Sentinel mediation layer for use of SLEE services
Front-end interfaces | As required by the custom front end
Features | Query And Notification Features — features for querying GSM network elements and sending notifications Mediation and promotion features — used when communicating with one or more OCS

## 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:

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

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

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

The Sentinel application server also includes configuration data related to:

- session plans

- features and feature execution scripts

- feature configuration

- mappers

- promotion scripts.

## 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 three phases of processing a session

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

### Session plans in Sentinel

See the following topics for specific session plans:

- Session plans for the SS7 service

- Session plans for the SIP service

- Session plans for the Diameter service

- Session plans for the Mediation layer

- Session plans for the Sentinel charge

## 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:

On Initial Trigger …​ Should the session be accepted? …​ analyse the initial trigger …​ …​ take actions based on the outcome of the initial credit check …​ Monitoring the session …​ Ending the session …​ …​ on session end

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

On Initial Trigger …​ Should the session be accepted? …​ analyse the initial trigger …​ …​ take actions based on the outcome of the initial credit check …​ Monitoring the session …​ …​ before each credit update …​ Ending the session …​ …​ on session end

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

On initial trigger …​ Should the session be accepted? …​ analyse the initial trigger …​ …​ take actions based on the outcome of the initial credit check …​ Monitoring the session …​ …​ before each credit update …​ Ending the session …​ …​ on session end

| 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 (`SentinelSipMultiLegFeatureEndpoint`)

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

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

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

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

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

Figure 1. Session Plan for an SIP INVITE Request

### Feature script execution points

Below are details of these points-in-session:

On initial trigger …​ Should the session be accepted? …​ analyse the initial trigger …​ …​ take actions based on the outcome of the initial credit check …​ Monitoring the session …​ take actions based on the outcome of an update credit check …​ as each leg is set up …​ as each leg continues …​ on a SIP SUBSCRIBE …​ on a SIP out-of-dialog transaction …​ …​ on leg end Ending the session …​ …​ on session end At any time …​ As timers expire…​ If instruction execution fails…​ As extension events are processed…​

| For feature script execution points available in the mediation layer (the dark blue box) see: Sentinel Mediation Layer. The feature endpoint for all sip execution points is `SentinelSipMultiLegFeatureEndpoint`

#### On initial trigger …​

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

- decide if the new session should be accepted for processing

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

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

##### Should the session be accepted?

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Session Accept | SipAccess_SessionAccept | SipRequest | SipSession
Session Start | SipAccess_SessionStart | SipRequest | SipSession

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

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

##### …​ analyse the initial trigger …​

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Network Check | SipAccess_NetworkPreCreditCheck | SipRequest | SipSession
Session Check | SipAccess_SessionPreCreditCheck | SipRequest | SipSession
Subscriber Check | SipAccess_SubscriberPreCreditCheck | SipRequest | SipSession

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

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

##### …​ take actions based on the outcome of the initial credit check …​

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Initial Credit Allocated | SipAccess_CreditAllocatedPostCC | CCA | SipSession
Initial Credit Limit Reached | SipAccess_CreditLimitReachedPostCC | CCA | SipSession
Initial Control Not Required | SipAccess_ControlNotRequiredPostCC | CCA | SipSession
Initial Control Failure | SipAccess_OCSFailurePostCC | CCA | SipSession
Initial Control Reauthorise | SipAccess_ChargingReauth | RAR | SipSession
Initial Control Abort | SipAccess_ChargingAbort | ASR | SipSession

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

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

#### Monitoring the session …​

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

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

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

##### …​ take actions based on the outcome of an update credit check …​

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Mid Session Credit Allocated | SipMidSession_CreditAllocatedPostCC | CCA | SipSession
Mid Session Credit Limit Reached | SipMidSession_CreditLimitReachedPostCC | CCA | SipSession
Mid Session Control Failure | SipMidSession_OCSFailurePostCC | CCA | SipSession
Mid Session Control Reauthorise | SipMidSession_ChargingReauth | RAR | SipSession
Mid Session Control Abort | SipMidSession_ChargingAbort | ASR | SipSession
Mid Session Credit Finalised | CreditFinalised | CCA | SipSession

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

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

##### …​ as each leg is set up …​

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Setup Sip Request | SipAccess_PartyRequest | SipRequest | SipSession
Setup Sip Response | SipAccess_PartyResponse | SipResponse | SipSession

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

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

##### …​ as each leg continues …​

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Mid Session Sip Request | SipMidSession_PartyRequest | SipRequest | SipSession
Mid Session Sip Response | SipMidSession_PartyResponse | SipResponse | SipSession

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

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

##### …​ on a SUBSCRIBE request …​

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Subscription Request | SubscriptionSipRequest | SipRequest | SipSession
Subscription Response | SubscriptionSipResponse | SipResponse | SipSession

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

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

##### …​ on an out-of-dialog SIP transaction …​

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Transaction Request | SipTransaction_Request | SipRequest | SipSession
Transaction Response | SipTransaction_Response | SipResponse | SipSession

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

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

##### …​ …​ as each leg ends

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Leg End | SipLegEnd | LegEndEvent | SipSession

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

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

#### Ending the session …​

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

##### …​ on session end

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
End Session | SipEndSession | EndSessionEvent | SipSession

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

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

#### At any time …​

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

- As timers expire…​

- If instruction execution fails…​

- As extension events are processed…​

##### 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 (`SentinelSipMultiLegFeatureEndpoint`)

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

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

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

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

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

Figure 2. Session Plan for Third Party Call Setup Request via HTTP

### Feature script execution points

Below are details of these points-in-session:

On initial trigger …​ Should the session be accepted? …​ analyse the initial trigger …​ …​ take actions based on the outcome of the initial credit check …​ Monitoring the session …​ take actions based on the outcome of an update credit check …​ on a SIP out-of-dialog transaction …​ …​ on leg end Ending the session …​ …​ on session end At any time …​ As timers expire…​ If instruction execution fails…​ As extension events are processed…​

| For feature script execution points available in the mediation layer (the dark blue box) see: Sentinel Mediation Layer. The feature endpoint for all sip execution points is `SentinelSipMultiLegFeatureEndpoint`

#### On initial trigger …​

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

- decide if the new session should be accepted for processing

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

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

##### Should the session be accepted?

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Session Accept | SipThirdPartyAccess_SessionAccept | HttpRequest (Event) | IncomingHttpRequestActivity
Session Start | SipThirdPartyAccess_SessionAccept | HttpRequest (Event) | IncomingHttpRequestActivity

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

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

##### …​ analyse the initial trigger …​

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Network Check | SipThirdPartyAccess_NetworkPreCreditCheck | HttpRequest (Event) | IncomingHttpRequestActivity
Session Check | SipThirdPartyAccess_SessionPreCreditCheck | HttpRequest (Event) | IncomingHttpRequestActivity
Subscriber Check | SipThirdPartyAccess_SubscriberCheck | HttpRequest (Event) | IncomingHttpRequestActivity

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

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

##### …​ take actions based on the outcome of the initial credit check …​

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Initial Credit Allocated | SipAccess_CreditAllocatedPostCC | CCA | SipSession
Initial Credit Limit Reached | SipAccess_CreditLimitReachedPostCC | CCA | SipSession
Initial Control Not Required | SipAccess_ControlNotRequiredPostCC | CCA | SipSession
Initial Control Failure | SipAccess_OCSFailurePostCC | CCA | SipSession
Initial Control Reauthorise | SipAccess_ChargingReauth | RAR | SipSession
Initial Control Abort | SipAccess_ChargingAbort | ASR | SipSession

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

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

#### Monitoring the session …​

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

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

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

##### …​ take actions based on the outcome of an update credit check …​

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Mid Session Credit Allocated | SipMidSession_CreditAllocatedPostCC | CCA | SipSession
Mid Session Credit Limit Reached | SipMidSession_CreditLimitReachedPostCC | CCA | SipSession
Mid Session Control Failure | SipMidSession_OCSFailurePostCC | CCA | SipSession
Mid Session Control Reauthorise | SipMidSession_ChargingReauth | RAR | SipSession
Mid Session Control Abort | SipMidSession_ChargingAbort | ASR | SipSession
Mid Session Credit Finalised | CreditFinalised | CCA | SipSession

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

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

##### …​ as each leg is set up …​

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Setup Sip Request | SipAccess_PartyRequest | SipRequest | SipSession
Setup Sip Response | SipAccess_PartyResponse | SipResponse | SipSession

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

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

##### …​ as each leg continues …​

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Mid Session Sip Request | SipMidSession_PartyRequest | SipRequest | SipSession
Mid Session Sip Response | SipMidSession_PartyResponse | SipResponse | SipSession

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

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

##### …​ on a SUBSCRIBE request …​

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Subscription Request | SubscriptionSipRequest | SipRequest | SipSession
Subscription Response | SubscriptionSipResponse | SipResponse | SipSession

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

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

##### …​ on an out-of-dialog SIP transaction …​

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Transaction Request | SipTransaction_Request | SipRequest | SipSession
Transaction Response | SipTransaction_Response | SipResponse | SipSession

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

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

##### …​ …​ as each leg ends

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Leg End | SipLegEnd | LegEndEvent | SipSession

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

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

#### Ending the session …​

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

##### …​ on session end

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
End Session | SipEndSession | EndSessionEvent | SipSession

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

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

#### At any time …​

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

- As timers expire…​

- If instruction execution fails…​

- As extension events are processed…​

##### 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 (`SentinelSipMultiLegFeatureEndpoint`)

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

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

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

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

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

Figure 3. Session Plan For a SIP SUBSCRIBE Request

### Feature script execution points

Below are details of these points-in-session:

On initial trigger …​ Should the session be accepted? …​ analyse the initial trigger …​ …​ take actions based on the outcome of the initial credit check …​ Monitoring the session …​ take actions based on the outcome of an update credit check …​ on a SIP SUBSCRIBE …​ …​ on leg end Ending the session …​ …​ on session end At any time …​ As timers expire…​ If instruction execution fails…​ As extension events are processed…​

| For feature script execution points available in the mediation layer (the dark blue box) see: Sentinel Mediation Layer. The feature endpoint for all sip execution points is `SentinelSipMultiLegFeatureEndpoint`

#### On initial trigger …​

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

- decide if the new session should be accepted for processing

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

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

##### Should the session be accepted?

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Session Accept | SubscriptionAccept | SipRequest | SipSession
Session Start | SubscriptionStart | SipRequest | SipSession

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

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

##### …​ analyse the initial trigger …​

Point in Session | Execution point name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Network Check | SubscriptionNetworkCheck | SipRequest | SipSession
Session Check | SubscriptionSessionCheck | SipRequest | SipSession
Subscriber Check | SubscriptionSubscriberCheck | SipRequest | SipSession

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

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

##### …​ take actions based on the outcome of the initial credit check …​

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Initial Credit Allocated | SipAccess_CreditAllocatedPostCC | CCA | SipSession
Initial Credit Limit Reached | SipAccess_CreditLimitReachedPostCC | CCA | SipSession
Initial Control Not Required | SipAccess_ControlNotRequiredPostCC | CCA | SipSession
Initial Control Failure | SipAccess_OCSFailurePostCC | CCA | SipSession

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

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

#### Monitoring the session …​

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

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

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

##### …​ take actions based on the outcome of an update credit check …​

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Mid Session Credit Allocated | SipMidSession_CreditAllocatedPostCC | CCA | SipSession
Mid Session Credit Limit Reached | SipMidSession_CreditLimitReachedPostCC | CCA | SipSession
Mid Session Control Failure | SipMidSession_OCSFailurePostCC | CCA | SipSession
Mid Session Credit Finalised | CreditFinalised | CCA | SipSession

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

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

##### …​ on a SUBSCRIBE request …​

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Subscription Request | SubscriptionSipRequest | SipRequest | SipSession
Subscription Response | SubscriptionSipResponse | SipResponse | SipSession

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

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

##### …​ …​ as each leg ends

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Leg End | SipLegEnd | LegEndEvent | SipSession

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

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

#### Ending the session …​

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

##### …​ on session end

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
End Session | SipEndSession | EndSessionEvent | SipSession

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

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

#### At any time …​

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

- As timers expire…​

- If instruction execution fails…​

- As extension events are processed…​

##### 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 (`SentinelSipMultiLegFeatureEndpoint`)

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

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

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

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

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

Figure 4. Session Plan for an Out-of-Dialog SIP Transaction

### Feature script execution points

Below are details of these points-in-session:

On initial trigger …​ Should the session be accepted? …​ analyse the initial trigger …​ …​ take actions based on the outcome of the initial credit check …​ Monitoring the session …​ take actions based on the outcome of an update credit check …​ on a SIP out-of-dialog transaction …​ …​ on leg end Ending the session …​ …​ on session end At any time …​ As timers expire…​ If instruction execution fails…​ As extension events are processed…​

| For feature script execution points available in the mediation layer (the dark blue box) see: Sentinel Mediation Layer. The feature endpoint for all sip execution points is `SentinelSipMultiLegFeatureEndpoint`

#### On initial trigger …​

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

- decide if the new session should be accepted for processing

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

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

##### Should the session be accepted?

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Session Accept | SipTransaction_Accept | SipRequest | SipSession
Session Start | SipTransaction_Start | SipRequest | SipSession

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

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

##### …​ analyse the initial trigger …​

Point in Session | Execution point name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Network Check | SipTransaction_NetworkCheck | SipRequest | SipSession
Session Check | SipTransaction_SessionCheck | SipRequest | SipSession
Subscriber Check | SipTransaction_SubscriberCheck | SipRequest | SipSession

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

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

##### …​ take actions based on the outcome of the initial credit check …​

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Initial Credit Allocated | SipAccess_CreditAllocatedPostCC | CCA | SipSession
Initial Credit Limit Reached | SipAccess_CreditLimitReachedPostCC | CCA | SipSession
Initial Control Not Required | SipAccess_ControlNotRequiredPostCC | CCA | SipSession
Initial Control Failure | SipAccess_OCSFailurePostCC | CCA | SipSession

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

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

#### Monitoring the session …​

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

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

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

##### …​ take actions based on the outcome of an update credit check …​

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Mid Session Credit Allocated | SipMidSession_CreditAllocatedPostCC | CCA | SipSession
Mid Session Credit Limit Reached | SipMidSession_CreditLimitReachedPostCC | CCA | SipSession
Mid Session Control Failure | SipMidSession_OCSFailurePostCC | CCA | SipSession
Mid Session Credit Finalised | CreditFinalised | CCA | SipSession

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

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

##### …​ on an out-of-dialog SIP transaction …​

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Transaction Request | SipTransaction_Request | SipRequest | SipSession
Transaction Response | SipTransaction_Response | SipResponse | SipSession

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

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

##### …​ …​ as each leg ends

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Leg End | SipLegEnd | LegEndEvent | SipSession

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

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

#### Ending the session …​

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

##### …​ on session end

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
End Session | SipEndSession | EndSessionEvent | SipSession

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

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

#### At any time …​

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

- As timers expire…​

- If instruction execution fails…​

- As extension events are processed…​

##### 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 (`SentinelSipMultiLegFeatureEndpoint`)

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

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

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

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

Figure 5. Session Plan for a Third Party REGISTER request

### Feature script execution points

Below are details of these points-in-session:

On initial trigger …​ Should the session be accepted? …​ analyse the initial trigger …​ Monitoring the session …​ on a SIP out-of-dialog transaction response …​ …​ on leg end Ending the session …​ …​ on session end At any time …​ As timers expire…​ If instruction execution fails…​ As extension events are processed…​

| The feature endpoint for all sip execution points is `SentinelSipMultiLegFeatureEndpoint`

#### On initial trigger …​

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

- decide if the new session can be accepted for processing

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

##### Should the session be accepted?

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Session Accept | SipRegistration_Accept | SIP REGISTER | SipSession
Session Start | SipRegistration_Start | SIP REGISTER | SipSession

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

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

##### …​ analyse the initial trigger …​

Point in Session | Execution point name | Trigger Object | Trigger Activity
--- | --- | --- | ---
Network Check | SipRegistration_NetworkCheck | SIP REGISTER | SipSession
Session Check | SipRegistration_SessionCheck | SIP REGISTER | SipSession
Subscriber Check | SipRegistration_SubscriberCheck | SIP REGISTER | SipSession

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

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

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

##### …​ on an out-of-dialog SIP transaction response …​

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Transaction Response | SipTransaction_Response | SipResponse | SipSession

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

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

##### …​ …​ as each leg ends

Point in session | Execution point name | Trigger object | Trigger activity
--- | --- | --- | ---
Leg End | SipLegEnd | LegEndEvent | SipSession

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

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

#### Ending the session …​

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

##### …​ on session end

Point in Session | Execution Point Name | Trigger Object | Trigger Activity
--- | --- | --- | ---
End Session | SipEndSession | EndSessionEvent | SipSession

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

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

#### At any time …​

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

- As timers expire…​

- If instruction execution fails…​

- As extension events are processed…​

##### 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:

- On initial trigger

  - Should the session be accepted?

  - …​ analyse the initial trigger …​

- Monitoring the session …​

- Ending the session …​

  - …​ on session end

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

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

For example, the Sentinel SS7 `default_call_DirectAccess_NetworkPreCreditCheck script`:

    featurescript OnNetworkPreCreditCheck {
      run EmergencyAndSpecialNumber
      if not feature.continueAndClose {
        run ClassifyCallScenario
      }
    }
| The `default_call_DirectAccess_NetworkPreCreditCheck` script runs the `EmergencyAndSpecialNumber` feature. It then runs the `ClassifyCallScenario` feature if the previous feature (in this case `EmergencyAndSpecialNumber`) did not respond with `continueAndClose`.

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

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

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

2. raise `feature.featureFailedToExecute` to reflect the error

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

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

| 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

- Comments

- Resolving conflicting responses from features

- Examples

- Feature execution script grammar

#### Statements

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

##### The `if` statement

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

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 `runcritical` statement, which is used when it is critical that a feature should execute correctly. The syntax of the `runcritical` statement is identical to the `run` statement. Currently, only the Sentinel SIP front end considers the outcome of a `runcritical` statement. The `runcritical` concept will eventually be applied in all other cores. See section Sentinel SIP Feature Execution Points for more information.

###### Feature parameters

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

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

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

String |
    featurescript somescript {
      run featureA param1 "value1" param2 "value2"
    }
List |
    featurescript somescript {
      run featureB param1 ["value1", "value2"]
    }

##### The `return` statement

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

#### Comments

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

### Resolving conflicting responses from features

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

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

Common rules | The requests of Sentinel core made by the most recent feature have precedence. Sentinel core applies requests in the order they are made by a feature.
SS7 rules | Sentinel core treats `connectAndClose`, `continueAndClose`, and `releaseAndClose` as mutually exclusive. For example, if `continueAndClose` is set, and the latest feature requests `releaseAndClose`, then Sentinel core will clear `continueAndClose` and raise `releaseAndClose`. Sentinel core treats `suppressOcsInteraction` and `enableOcsInteraction` as mutually exclusive. For example, if `enableOcsInteraction` is set, and the latest feature requests `suppressOcsInteraction`, then Sentinel core will clear `enableOcsInteracion` and raise `suppressOcsInteraction`. Sentinel core treats `refuseDialog` and `relayDialog` as mutually exclusive. For example, if `refuseDialog` is set, and the latest feature requests `relayDialog`, then Sentinel core will clear `refuseDialog` and raise `relayDialog`.
SIP rules | Sentinel SIP now uses `EventManagers` (`LegManager`, Charging Manager) for feature responses.
Diameter rules | Sentinel core treats `ccNotApplicable`, `creditLimitReached`, `endUserServiceDenied`, `ratingFailed`, `redirect`, `reportBaseResult`, and `userUnknown` as mutually exclusive. That is, only one of these inputs can be raised at any one time. For example, if the latest feature requests `userUnknown` then Sentinel core will raise `userUnknown` and ensure that `ccNotApplicable`, `creditLimitReached`, `endUserServiceDenied`, `ratingFailed`, `redirect`, and `reportBaseResult` are all clear.

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

#### Feature script execution points that are chained together

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

Feature script execution points | The values of the `currentNextStep.` flags:
--- | ---
    Session Accept
    Session Start
| are cleared before `Session Accept` are available at the start of `Session Start`, and have values that are the aggregate result of `Session Accept`
    Network Pre Initial Credit Check
    Session Pre Initial Credit Check
    Subscriber Pre Initial Credit Check
| are cleared before `Network Pre Initial Credit Check` are available at the start of `Session Pre Initial Credit Check`, and have values that are the aggregate result of `Network Pre Initial Credit Check` are available at the start of `Subscriber Pre Initial Credit Check`, and have values that are the aggregate result of `Network Pre Initial Credit Check` and `Session Pre Initial Credit Check`.

| See Session plans for more information. For example, consider SS7 sessions initiated via SS7.

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

### Examples

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

    featurescript OnSessionStart {
      if not currentNextStep.refuseDialog and
         not currentNextStep.relayDialog
      {
        run AcceptProtocol
      }
    }
| The first two execution points, together, provide initial dialog analysis. In the first step we run features within the context of the platform operator. This script then runs within the context of the network operator. The condition here says that we run the `AcceptProtocol` feature only if we have not already decided to `refuseDialog` or `relayDialog`.

    featurescript OnNetworkPreCreditCheck {
      run EmergencyAndSpecialNumber
      if not feature.continueAndClose {
        run ClassifyCallScenario
      }
    }
| `NetworkPreCC` + `SessionPreCC` + `SubscriberPreCC`, together, provide the initial analysis of the `InitialDP`. We run features: within the context of the network operator (`NetworkPreCC`) within the context of the session (`SessionPreCC`) within the context of the subscriber (`SubscriberPreCC`). This is an example script that runs within the context of the network operator. The first step is to run the feature `EmergencyAndSpecialNumber`. This feature will request that Sentinel core should `continueAndClose` if the number dialled is special (such as 111 in New Zealand) and Sentinel should not be involved anymore. The next statement says that `ClassifyCallScenario` should only run if the latest feature that finished (in this case `EmergencyAndSpecialNumber`) did not request `continueAndClose`.

    featurescript OnSessionPreCreditCheck {
      if not currentNextStep.continueAndClose {
        run CallForwardingDetection
        if not feature.doNotMonitorSession and
           not feature.doNotChargeSession
        {
          run ValidateInitialDP
          if not feature.releaseAndClose {
            run ShortCode
            run PrefixAndSuffixAnalysis
            run Normalization
            run Reorigination
            if not feature.connectAndClose {
              run SubscriberDetermination
              run SessionTracing
            }
          }
        }
      }
    }
| This is an example script that runs within the context of the session. The initial condition guards all feature execution by checking if we have currently been asked to `continueAndClose`. If we have, then we do not need to run any feature. Otherwise we run the `CallForwardingDetection` feature. This checks to see if this is a forwarded leg that we should not process. The `if` statement that follows has a condition that is in terms of the last feature that ran. So we only run more features if `CallForwardingDetection` did not request `doNotMonitorSession` or `doNotChargeSession`. If that is the case, we then run `ValidateInitialDP`. This feature will request that Sentinel core should `releaseAndClose`, so we check to see if this happened before running any further features.

### Feature execution script grammar

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

## 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…​ uses mapper lookup configuration data to resolve which mapping to use uses the “mapping name”, get a concrete mapper from the registry returns the mapper to Sentinel core to use.

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

##### Dynamic mapper fallback selection

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

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

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

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

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

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

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

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

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

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

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

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

### What OCS drivers does Sentinel provide?

- Diameter Ro OCS Driver (`ocsEntityId=DiameterRoOc`)

## Session Counters

Session counters are charging activity counters stored in session state.

### How do session counters work?

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

- to determine any undebited units for the session

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

- for reconciliation of Sentinel with the OCS.

### Session counter structure

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

The root of a session counter has the following fields:

Field name | Purpose | Details
--- | --- | ---
    subscriberId
| Subscriber id associated with the charging values stored in this counter |
    bucketName
| The name of the counter |
    cumulativeRequestedUnits
| Cumulative requested unit reservations | Sum of Requested-Service-Units in CCR Multiple-Service-CreditControl AVPs associated with this counter.
    cumulativeGrantedUnits
| Cumulative granted unit reservations | Sum of Granted-Service-Units in CCA Multiple-Service-CreditControl AVPs associated with this counter.
    cumulativeSentUsedUnits
| Cumulative used units | Sum of Used-Service-Units in CCR Multiple-Service-CreditControl AVPs associated with this counter.
    cumulativeCommittedUsedUnits
| Cumulative committed used units | Sum of Used-Service-Units in CCR Multiple-Service-CreditControl AVPs associated with this counter which have received a CCA response successfully. Also used for the values reported in DIRECT_DEBIT CCRs.
    cumulativeRequestedRefundUnits
| Cumulative requested refund units | Sum of Requested-Service-Units in CCR(REFUND) Multiple-Service-CreditControl AVPs.
    cumulativeGrantedRefundUnits
| Cumulative requested refund units | Sum of Requested-Service-Units in CCR(REFUND) Multiple-Service-CreditControl AVPs associated with this counter which have received a CCA response successfully.

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

- a successful MOC call

- a successful MOC call with a promotion

- an unlimited SMS promotion

- Diameter Ro OCS failure handling and undebited units handling

#### 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 `75s` long and had a successful `60s` reservation from the `AnytimeOnNet` promotions.

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

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

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

#### 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: Session state Address lists Mappers Feature configuration Resource adaptor providers.

### 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 End` and `Instruction Execution Failure` events) and new feature script execution points.

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

- Features can now:

  - interact with external resources using feature extension events

  - set their own timers

  - support multi-leg scenarios with the improved Leg Manager

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

| 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 to learn how the Sentinel architecture has changed Inside Sentinel SIP to learn about many new components of Sentinel SIP. Sentinel Registrar Overview and Concepts to learn how Third Party Registration is supported

## Enhanced Sentinel SIP Architecture

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

Key Sentinel SIP event processing model More flexible charging architecture Enhanced feature execution model Feature extension events Service timer provider Support for multi-leg scenarios

## 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:

- B2BUA

- MMTel conference

- charged or uncharged announcements

- event notification and single transactions using IEC or ECUR.

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

- system-wide and feature-specific configuration

- scenario-specific configuration, using the Sentinel selection key

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

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

### Offline charging

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

### Components

Charging in Sentinel SIP uses these components:

- features and mappers

- the Charging Manager

- SIP session counters

- the Service Timer Provider

- B2BUAChargingFeatureUtil

- existing SIP charging features.

#### Features and mappers

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

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

#### Charging Manager

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

#### SIP Session Counters

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

#### Service Timer Provider

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

#### B2BUAChargingFeatureUtil

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

#### Existing SIP charging features

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

##### B2BUAScur pre and post features

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

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

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

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

- responding to RARs

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

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

##### SDP comparison

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

1. Detect meaningful SDP updates and issue a reauthorisation.

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

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

##### B2BUAEcur pre and post features

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

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

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

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

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

##### B2BUAIEC pre and post features

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

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

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

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

- issuing a refund on service delivery failure.

##### SipMidCallPlayAnnouncement feature

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

## Charging Scenarios

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

### Online charging — B2BUA with SCUR including SDP comparison

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

To summarise, the steps in the scenario are:

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

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

3. B2BUAScur performs recurring reauths.

4. B2BUAScur handles RAR.

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

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

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

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

### 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) | `INVITE` `SUBSCRIBE`
HTTP | an external HTTP-enabled network element | an HTTP `GET` request that initiates a third-party call setup
Diameter | the Sentinel mediation layer (related to events from an external OCS) |
Extension | external network elements for sessions initiated by features within Sentinel |
Timer | timers that features raise using the `ServiceTimerProvider` |
Local | raised internally by Sentinel, as a result of processing other events and instructions | `EndSessionEvent`, when the Sentinel session has ended (that is, no more SIP legs or charging instances remain active) `InstructionExecutionFailedEvent`, when one or more event manager instruction failed during processing `LegEndEvent`, when the Sentinel session continues, but one or more SIP legs have ended

### What is an event manager?

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

- Charging Manager— manages charging instances during the session

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

An event manager is responsible for:

- providing some core Sentinel behaviour

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

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

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

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

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

- managing a set of pending instructions

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

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

| 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 `INVITE` request from the S-CSCF or a `CreditControlAnswer` from the Sentinel mediation layer. Sentinel starts an event loop: Loop `Update Event Managers` …​ `Process Feature Script Execution Points` …​ `Process Event Manager Instructions` Until the `local event queue` is empty.
2 | Event managers process the received event. They: update their own state For example, the Leg Manager creates a new leg for an initial `INVITE` request; and the Charging Manager updates charging sessions on receipt of a `CreditControlAnswer`. determine if one or more feature script execution points should be triggered for the event For example, the Leg Manager determines that the `SipAccess_SessionAccept`, `SipAccess_SessionStart`, `SipAccess_NetworkCheck`, `SipAccess_SessionCheck`, and `SipAccess_SubscriberCheck` execution points should be triggered in response to an initial `INVITE` request.
3 | If there are any `feature script execution points` to trigger, then process them; otherwise see if event managers have any instructions to carry out.
4 | Process each `feature script execution point` in turn. Features may update the state of the Charging and Leg Managers as they execute. For example, a feature might create a new SIP leg, or link two SIP legs. Features may set timers or create sessions to external network elements. Related `extension events` and `timer events` may be received whilst Sentinel is processing `feature script execution points`.
See | To learn how…​
--- | ---
Sentinel SIP Feature Execution Points | Sentinel processes a feature script execution point
Sentinel Service Timer Provider | features may raise timers
Sentinel Feature Extension Events | features may receive extension events
Once all `feature script execution points` have been processed, then check if the event managers have any instructions to carry out.
5 | Ask each event manager in turn to carry out any pending instructions that have accumulated while processing the event. Each event manager manages a set of instructions while features are executing. For example, if a feature calls `doRefund()` on an `ImmediateChargingInstance`, then the charging instance will record a pending instruction of `Refund`. Once all pending instructions have been processed, then see if there are any events in the `local event queue`. If the `local event queue` is empty, then wait for the next real event. Otherwise, de-queue a local event and process it.
6 | Event processing ends once the session ends.

## Inside Sentinel SIP

- Charging Manager

- Leg Manager

- Sentinel SIP Feature Execution Points

- Sentinel SIP Feature Execution Script Predicates

- Feature Extension Events

- Service Timer Provider

- New Session Counters

- SDP Comparison

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

Figure 7. Charging Manager and Charging Instances

1. There is one `ChargingManager` instance for each session.

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

| The first release implementation of the `ChargingManager` supports one charging instance per session. This limitation will be removed in a subsequent release of Sentinel so all possible approaches to charging a session will be supported. The Charging Manager is currently only available in the Sentinel SIP frontend, but the concept eventually will be extended to the other cores. See Using the SIP Charging Manager to learn how features access and use the `Charging Manager` component.

## Leg Manager

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

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

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

## Sentinel SIP Feature Execution Points

### Enhanced Feature Execution Model

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

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

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

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

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

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

1. User and System Features

2. What is a Feature Execution Point

3. How does Sentinel Process an Execution Point

### User and System Features

There are two types of feature:

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

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

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

### What is a Feature Execution Point

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

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

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

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

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

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

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

Figure 8. Steps in processing a feature script execution point

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

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

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

| The `pre`, `user` and `post` scripts are resolved via a `SentinelSelectionKey` based lookup. See: Managing Session Plans to learn how to associate a feature execution script to a `point-in-session`.

### Responding to Features that Fail

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

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

    featurescript PreSessionAccept {
        runcritical B2BUA
    }

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

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

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

## Sentinel SIP Feature Execution Script Predicates

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

Below are details of LegManager and ChargingManager predicates.

### LegManager predicates

Predicate name | Supersedes | True when…​
--- | --- | ---
LegManager.endSession | feature.endSession | a feature has requested endSession in this execution point
LegManager.currentLeg |  | there is a leg active at the current execution point
LegManager.currentLinkedLeg |  | the current execution point has an active leg linked to a second leg
LegManager.currentLeg.releaseLeg LegManager.currentLinkedLeg.releaseLeg | feature.releaseLeg | there is a pending releaseLeg on the specified leg (currentLeg and currentLinkedLeg)
LegManager.currentLeg.pendingMessage LegManager.currentLinkedLeg.pendingMessage | feature.sendMessage feature.sendCancel | there is a pending message on the specified leg (currentLeg and currentLinkedLeg)
LegManager.proxyAndDoNotRecordRoute | feature.proxyAndDoNoRecordRoute | there proxyAndDoNotRecordRoute instruction on the triggering leg
LegManager.currentLeg.parallelFork LegManager.currentLinkedLeg.parallelFork | feature.parallelFork | there is a pending parallelFork on the specified leg (currentLeg and currentLinkedLeg)
LegManager.detachAll | feature.terminateProcessing | detachAll has been requested
LegManager.currentLeg.upstreamFork LegManager.currentLinkedLeg.upstreamFork | feature.upstreamFork | there is a pending upstreamFork on the specified leg (currentLeg and currentLinkedLeg)
LegManager.currentLeg.downstreamFork LegManager.currentLinkedLeg.downstreamFork | feature.downstreamFork | there is a pending downstreamFork on the specified leg (currentLeg and currentLinkedLeg)
LegManager.currentLeg.endInviteSession LegManager.currentLinkedLeg.endInviteSession |  | there is a pending endInviteSession on the specified leg (currentLeg and currentLinkedLeg)
LegManager.currentLeg.endSubscription LegManager.currentLinkedLeg.endSubscription |  | there is a pending endSubscription on the specified leg (currentLeg and currentLinkedLeg)
LegManager.currentLeg.detachFromLeg LegManager.currentLinkedLeg.detachFromLeg |  | there is a pending detachFromLeg on the specified leg (currentLeg and currentLinkedLeg)
LegManager.currentLeg.hasEndingInstruction LegManager.currentLinkedLeg.hasEndingInstruction |  | any of detachAll, detachFromLeg, proxyAndDoNotRecordRoute, endSession, or releaseLeg are true; used as a convenience method to simplify execution script logic

### ChargingManager predicates

Predicate name | Supersedes | What it indicates
--- | --- | ---
ChargingManager.charging | feature.doNotCharge feature.ceaseCharging | a charging instance exists
ChargingManager.sessionCharging |  | a session charging instance exists
ChargingManager.sessionCharging.reservation | feature.doCreditCheck | a feature has requested credit reservation
ChargingManager.sessionCharging.finalisation |  | a feature has requested credit finalisation
ChargingManager.immediateCharging |  | an immediate event charging instance exists
ChargingManager.immediateCharging.directDebit |  | a feature has requested a direct debit
ChargingManager.immediateCharging.refund |  | a feature has requested a refund

## Feature Extension Events

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

### When would you use an extension event?

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

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

- Overview of extension events

- Processing extension events

- Writing a feature that uses extension events

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

### What you need to know to use extension events

To use extension events, you need to know:

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

- how a feature can process an `extension event`

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

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

Figure 9. Sentinel extension events

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

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

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

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

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

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

### When are extension events processed?

Extension events may be processed when:

- a feature blocks and waits for an extension event to be received

- a feature returns, and another feature is triggered in the future with an extension event.

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

Figure 10. Feature waits for the extension event before returning

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

- uses a provider object related to the external resource

- creates a new session

- gets a SLEE `ActivityContextInterface` related to the session

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

- sends a message to the external resource (`request`).

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

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

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

| The feature execution script that starts `MyFeature` spans two SLEE transactions (the script starts in `txn #1` and ends in `txn #2`). A feature that is waiting for a response on an activity will receive an `ActivityEndEvent` if the activity ends without a response event being delivered into the SLEE.

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

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

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

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

- uses a provider object related to the external resource

- creates a new session

- gets a SLEE `ActivityContextInterface` related to the session

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

- sends a message to the external resource (`request`)

- returns control to Sentinel by sending `featureHasFinished()`.

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

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

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

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

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

### Writing a feature that uses extension events

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

Requirements

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

There are two aspects to developing this feature:

1. Writing the feature

2. Writing the feature SBBPart

#### Writing the feature

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

##### Injecting the http provider

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

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

##### Implementing `startFeature()`

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

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

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

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

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

For example:

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

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

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

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

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

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

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

#### Writing the feature SBBPart

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

#### Accessing HTTP resource adaptor classes

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

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

#### Implementing the event handler method

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

- the name of the feature to invoke

- the `httpResponseEvent` object

- the associated `ActivityContextInterface` and `EventContext` objects.

For example:

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

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

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

| Remember that the `SendHttpRequestAndWaitFeature` told Sentinel to `attach` to the outgoing http activity. Sentinel will therefore receive all incoming http events (such as the `httpResponseEvent`) on this activity. Whilst this simple example hard-codes the name of the feature to invoke as `"SendAndReceiveHttpFeature"`, the `SBB part` may include the name of any feature to invoke. For example, it might derive the name of the feature to invoke from parameters of the received event.

## Service Timer Provider

### What is the ServiceTimerProvider?

The ServiceTimerProvider API can be used by features to set feature specific timers and receive TimerEvents, when the timers fire.

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

1. directly invoking a feature

2. invoking a feature execution script

In general, features should not attempt to perform their own Timer management using the SLEE Timer Facility. Instead, they should use the `ServiceTimerProvider` to perform all timer operations.

#### Processing a Service Timer Event by Directly Invoking a Feature

If you want Sentinel to directly invoke a particular feature when your timer fires, use the `setTimer` operations of the `SentinelTimerProvider` interface that take a `String` feature name as the first argument. For example:

    // set a timer to expire in 5000ms, and cause a feature to be invoked.
    long nowT = System.currentTimeMillis();
    long expireT = nowT + 5000; // expire in 5000ms from now
    TimerID timer = timerProvider.setTimer(NAME,     // invoke me when the timer fires
                                           expireT); // when to expire

| You may also register an existing Timer with the `ServiceTimerProvider` (and have the TimerEvents processed by a named feature) with the `registerTimer` operation.

In the following diagram, a feature `MyFeature` sets a timer using the `ServiceTimerProvider`. The `ServiceTimerProvider` remembers that `MyFeature` should be triggered when the timer expires and uses the SLEE timer facility to set the timer. Finally the feature tells Sentinel it is done via `featureHasFinished()`.

At some point in the future the timer expires. The SLEE triggers Sentinel in a new SLEE transaction. Sentinel defers to the `ServiceTimerProvider` to find the name of a feature to invoke, and then directly invokes it by calling `startFeature()` with the `TimerEvent` as the trigger.

Figure 12. Setting up a feature timer that will trigger a feature directly on a TimerEvent

| 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 `ServiceTimerProvider` (and have the TimerEvents processed by a feature execution script) with the `registerTimer` operation.

In the following diagram, a feature `MyFeature` sets a timer using the `ServiceTimerProvider`. The `ServiceTimerProvider` uses the SLEE timer facility to set the timer. Finally the feature tells Sentinel it is done via `featureHasFinished()`.

At some point in the future the timer expires. The SLEE triggers Sentinel in a new SLEE transaction. Sentinel searches for a feature execution script to run at the `SipAccess_ServiceTimer` feature script execution point using the current value of the `SentinelSelectionKey`. If a script is found, then Sentinel will run it.

Figure 13. Setting up a feature timer that will trigger a feature execution script on a TimerEvent

| See section Sentinel Selection Key for more information about the sentinel selection key. See section Feature Execution Scripts for more information about feature execution scripts.

### Cancelling a Timer

You cancel a timer that has been registered with the `ServiceTimerProvider` with the `cancelTimer` operation. For example:

    // get the TimerID from session state
    final TimerID timerID = sessionState.getNoResponseTimerID();
    if (timerID != null) {
        if (facilities.getTracer().isFinestEnabled())
            facilities.getTracer().finest("Cancelling NoResponse timer: " + timerID);
        // if we have a timer, then cancel it
        timerProvider.cancelTimer(timerID);
    }

### Testing if a Timer is Set

You can check if a timer is currently set and registered with the provider with the `timerIsSet` operation. For example:

    final TimerID timerID = sessionState.getNoResponseTimerID();
    if (timerProvider.timerIsSet(timerID)) {
        // cancel the timer
        timerProvider.cancelTimer(timerID);
    }

## New Session Counters

Session counters are session and charging activity counters stored in session state. For SIP sessions, "new" session counters replace the original session counters (which are still used with SS7 and Diameter front ends).

### What are session counters?

Session counters record the current status of the charging activity in a session. The CDR written for a session includes session counter data that records the final status of the charging when the session ended.

This data may be used in post-processing, for:

- determining any undebited units for the session

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

- reconciliation of Sentinel with the OCS

- analysis of any issues encountered during Sentinel operations.

### Session counter structure

Session counters are stored in a `ChargingInstance` which is accessed from the `ChargingManager`. Each charging instance contains one or more session counters. A session counter has an address that consists of a set of name/value pairs and is unique for the charging instance.

The `ChargingManager` is accessed via the `SentinelSipMultiLegFeatureEndpoint`. For example:

    ChargingInstance chargingInstance = getCaller().getChargingManager()
                   .getChargingInstance(B2BUAChargingFeatureUtil.DEFAULT_ECUR_CHARGING_INSTANCE);
    SessionCounters sessionCounters = chargingInstance.getSessionCounters();

Each session counter has the following fields:

Field name | Purpose | Details
--- | --- | ---
Counter Addressing
    address
| Counter addressing | Set of name/value pairs uniquely identifying this session counter within a charging instance.
Session Time and Duration
    startTime
| Session start time | The start time is recorded when the session starts consuming units. For instance, when the session is established. Milliseconds since the epoch (January 1, 1970, 00:00:00 GMT).
    endTime
| Session end time | The end time is recorded when the session ceases consuming units. For instance, when the session being charged is terminated. Milliseconds since the epoch (January 1, 1970, 00:00:00 GMT).
    cumulativeSuspendedDuration
| Cumulative suspended duration | Cumulative duration of all periods where charging on the session was suspended in milliseconds.
    grantedUnitValidityExpiry
| Unit validity | Expiry time for granted units in milliseconds since the epoch (January 1, 1970, 00:00:00 GMT).
Unit Counters
    reportedUsed
| Units reported as used to be sent in the next CCR |
    pendingRequested
| Units to be requested in the next CCR |
    cumulativeRequested
| Cumulative requested unit reservations | Sum of `Requested-Service-Units` in CCR `Multiple-Service-CreditControl` AVPs associated with this counter.
    cumulativeGranted
| Cumulative granted unit reservations | Sum of `Granted-Service-Units` in CCA `Multiple-Service-CreditControl` AVPs associated with this counter.
    cumulativeSentUsed
| Cumulative used units | Sum of `Used-Service-Units` in CCR `Multiple-Service-CreditControl` AVPs associated with this counter.
    cumulativeCommittedUsed
| Cumulative committed used units | Sum of `Used-Service-Units` in CCR `Multiple-Service-CreditControl` AVPs associated with this counter which have received a CCA response successfully.
    cumulativeRequestedRefund
| Cumulative requested refund units | Sum of `Requested-Service-Units` in CCR(REFUND) `Multiple-Service-CreditControl` AVPs.
    cumulativeGrantedRefund
| Cumulative requested refund units | Sum of `Requested-Service-Units` in CCR(REFUND) `Multiple-Service-CreditControl` AVPs associated with this counter which have received a CCA response successfully.

| The values stored in counters are not strictly related to Diameter CCR and CCA AVP values but may be used for other purposes. For instance, session counter fields may record charging activity of promotions which do not use Diameter or the charging activity of a non-Diameter charging protocol.

The `Session Time`, `Duration`, and `Unit Counters` fields are maintained by Sentinel system features. Where necessary, user features may update the `reportedUsed` and `pendingRequested` fields for counters created by system features. Session counters added by user features may have all fields updated by the user features as required.

Access to session counters is via a `SessionCounters` interface:

Function | Description
--- | ---
    getAddresses
| Get a list of the addresses of all session counters.
    add
| Add a new session counter.
    get
| Get a session counter for an address.
    getSessionCounters
| Get all session counters.
    getSessionCountersByAddressSubset
| Get all session counters which have addresses which are a subset of the requested address.
    getAggregateSessionCounter
| Get a session counter which contains the aggregated values of all session counters which have addresses that are supersets of the requested address.

#### Default address name values

The following default address name values are used in the system. Other values may be used as required by the feature developer.

    Cc-Total-Octets
    Cc-Service-Specific-Units
    Cc-Output-Octets
    Cc-Input-Octets
    Cc-Money
    Cc-Time
    Cc-Unit-Type
    Rating-Group
    Service-Id
    Subscriber-Id

### Counter update algorithm pseudo code

Here is the counter update algorithm pseudo code, which updates counters for granted units.

    Create a list of session counters which have pendingRequested units
    Create a list MSCCs with Granted-Service-Units from the CCA

    // Handle the common case where there is a single MSCC/GSU and single session counter expecting granted units
    IF there is one and only one MSCC
       AND one session counter awaiting granted units
       AND MSCC GSU unit type is an address key of session counter THEN

        Perform GSU updates to the session counter using values from MSCC

        RETURN
    ENDIF

    // Exact matching cases
    FOREACH MSCC DO

        Create a session counter address for the MSCC based on configured ordered list of AVPs to consider (e.g. [Unit-Type, Service-Id, Rating-Group, Custom-Attribute]

        Get session counter from charging instance using session counter address calculated from the MSCC

        IF a session counter exists for the MSCC address THEN

            Perform GSU updates to the session counter using values from MSCC

            Mark MSCC processed

            CONTINUE
        ENDIF

    DONE

    // Best effort matching
    FOREACH unmatched MSCC DO

        Create a session counter address from the MSCC using the configured ordered list of AVPs to
        consider (e.g. [Service-Id, Rating-Group, Unit-Type, Custom-Attribute])

        Create a list of addresses based on the configured ordered list of AVPs with first address
        including all then removing the last AVP until only first address left i.e.
        [[Unit-Type, Service-Id, Rating-Group, Custom-Attribute],
         [Unit-Type, Service-Id, Rating-Group],
         [Unit-Type, Service-Id],
         [Unit-Type]]

        FOREACH address DO
            Get matching session counters

            IF there is a matching session counter THEN

                Perform GSU updates to the first session counter

                Mark MSCC processed

                CONTINUE
            ENDIF
        DONE
    DONE

    // Record values from any unmatched MSCCs
    FOREACH unmatched MSCC DO

        Create a new session counter using the full MSCC session counter address if it does not already exist.

        Perform GSU updates to the session counter using values from MSCC.  Surplus units for an existing
        counter will be applied to the counter at this point.
    DONE

Updates for sent used units on successfully sending a CCR-U or CCR-T to the OCS:

    IF CCR-U or CCR-T with USU sent THEN
        Update cummulativeSentUsed for the counter matching the MSCC
    ENDIF

Updates for committed used units on receiving a CCA-U or CCR-T from the OCS:

    Update cummulativeCommittedUsed values for all USU sent in the CCR

#### Session counter address mappers

The `SipRequestToSessionCounterAddress` mapper creates the default session counter address for SIP sessions.

The `CCAToSessionCounterList` mapper creates a list of GSU counters which are processed by the counter update algorithm. The priority order of the address name/value pairs is based on the order in which the name/value pairs are added when creating the address.

Below are three examples:

- SIP call with session charging with unit reservation

- SIP Event Charging with Unit Reservation

- SIP Immediate Event Charging with Refund.

#### SIP call with session charging with unit reservation

The following session counter shows the charging values at the end of the SIP call. The call has a successful 60s reservation and is 5s long . All units are successfully committed in the OCS.

Point in call flow | Pending Requested | Reported Used | Requested | Granted | Sent Used | Committed Used
--- | --- | --- | --- | --- | --- | ---
1 CCR-I
1.1 new charging instance |
    60000
    0
    0
    0
    0
    0
1.2 CCR-I sent |
    60000
    0
    60000
    0
    0
    0
1.3 CCA-I received |
    0
    0
    60000
    60000
    0
    0
2 CCR-U
2.1 Charging Timer Expiry |
    60000
    60000
    60000
    60000
    0
    0
2.2 CCR-U sent |
    60000
    0
    120000
    60000
    60000
    0
2.3 CCA-U received |
    0
    0
    120000
    120000
    60000
    60000
3 CCR-T
3.1 Party hangs up |
    0
    30000
    120000
    120000
    60000
    60000
3.2 CCR-T sent |
    0
    0
    120000
    120000
    90000
    60000
3.3 CCA-T received |
    0
    0
    120000
    120000
    90000
    90000

Final counter state:

    address:                       {"Subscriber-Id":"tel:34600000002",
                                    "Cc-Unit-Type":"Cc-Time",
                                    "Service-Id":"1"}
    reportedUsed:                  0
    pendingRequested:              0
    cumulativeRequested:      120000
    cumulativeGranted:        120000
    cumulativeSendUsed:        90000
    cumulativeCommittedUsed:   90000
    cumulativeRequestedRefund:     0
    cumulativeGrantedRefund:       0

##### SIP event charging with unit reservation

The following session counter shows the charging values at the end of the SIP event charging session. The session has a successful `1` unit reservation, and `1` unit is used. All units are successfully committed in the OCS.

    address:                       {"Subscriber-Id":"tel:34600000002",
                                    "Cc-Unit-Type":"Cc-Service-Specific-Units",
                                    "Service-Id":"1"}
    reportedUsed:                  0
    pendingRequested:              0
    cumulativeRequested:           1
    cumulativeGranted:             1
    cumulativeSendUsed:            1
    cumulativeCommittedUsed:       1
    cumulativeRequestedRefund:     0
    cumulativeGrantedRefund:       0

##### SIP immediate event charging with refund

The following session counter shows the charging values at the end of the SIP event charging session. The session has a successful `1` unit reservation, and `1` unit is used. All units are successfully committed in the OCS.

    address:                       {"Subscriber-Id":"tel:34600000002",
                                    "Cc-Unit-Type":"Cc-Service-Specific-Units",
                                    "Service-Id":"1"}
    reportedUsed:                  0
    pendingRequested:              0
    cumulativeRequested:           1
    cumulativeGranted:             1
    cumulativeSendUsed:            0
    cumulativeCommittedUsed:       0
    cumulativeRequestedRefund:     1
    cumulativeGrantedRefund:       1

## SDP Comparison

### What is SDP comparison?

When using Sentinel SIP, the SDP offer answer model is used to negotiate the media streams and associated codecs for the session, and the addition and removal of streams and associated codecs while a session is in progress.

When codecs and the number and type of streams change, Sentinel may consult the SDP media codec configuration to determine if the change was a material change, from a rating conditions perspective. The SDP media codec configuration defines a set of equivalence classes. When the two SDPs being compared have equivalent codecs in the same number of streams, the comparison will return a match which will indicate an immaterial change. When the number of streams or the codecs in the streams are not matched based on the configured equivalence classes, a material change will be indicated.

If the difference between the previous and newly negotiated SDP is material from a rating condition perspective, then Sentinel will perform a client-initiated credit re-authorization towards the Online Charging System (OCS). The OCS will be notified that the reason is due to rating conditions changing. While the re-authorization is in progress, the outgoing message is suspended. On successful response from the OCS, the outbound message processing is resumed.

If the reauthorization fails with a ServiceDenied reason and the message was a SIP UPDATE or INVITE, the newly negotiated SDP is discarded and 401 error response is sent to the originator. A CCR for the previous SDP is sent then to the OCS, to reestablish charging for the session at the previous rate. If this also fails, the session is ended.

If a change is immaterial, then the current credit reservation remains.

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

1. A developer from Acme Inc uses the Sentinel SDK installer to create a development environment they can use to create their own custom version of Sentinel. The development environment uses:

   - Apache Ant for building

   - Apache Ivy for dependency management. The development environment resolves OpenCloud dependencies (such as Sentinel core components and libraries, and OpenCloud resource adaptor components and libraries) from an OpenCloud Sentinel Ivy repository.

2. Acme developers use the Sentinel SDK to create their own version of Sentinel.

3. The development environment generates a Sentinel install package that includes all the changes created by Acme Inc developers.

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