Sentinel uses feature execution scripts to run one or more features, at a feature execution script execution point.
How do feature execution scripts work?
Each feature execution script has a unique name (it must be unique within the scope of the platform). The Sentinel default configuration includes a set of feature execution scripts. The default scripts may be changed or replaced to meet the needs of a deployment.
The feature execution script has run, if, while, do-while, and return statements.
The conditions of the if, while, and do-while statements are Boolean expressions of the responses from the
previous feature, previous scripts, Boolean session state fields, and enum session state fields.
The Boolean expressions may contain:
-
directives set by features such as
feature.continueAndClose -
Boolean fields from session state such as
session.RoamingIndicator -
enum fields from session state such as
session.ChargingType.sessionCharging. -
EventManagerpredicates such asLegManager.endSession(Sentinel SIP only).
For example, the Sentinel SS7 default_call_DirectAccess_NetworkPreCreditCheck script:
featurescript OnNetworkPreCreditCheck {
run EmergencyAndSpecialNumber
if not feature.continueAndClose {
run ClassifyCallScenario
}
}
|
The It then runs the |
A feature may detect a failure, and report to the Sentinel core using feature.featureFailedToExecute or feature.featureCannotStart.
The default behaviour of the feature execution script is to ignore the error and continue feature script execution.
However, if specific behaviour is required on error, then feature.featureFailedToExecute or feature.featureCannotStart may be checked in a feature execution script condition.
Any exception that is thrown by a feature will by caught by the Sentinel core. Sentinel will treat this as a failure and take the following actions:
-
invoke
abortFeature()on the feature that threw the exception -
raise
feature.featureFailedToExecuteto reflect the error -
raise
feature.featureHasFinishedso the feature execution script can continue.
The behaviour is the same as in the case of a feature detecting the error itself, then raising feature.featureFailedToExecute and feature.featureHasFinished.
|
It is good practice for features to catch and handle exceptions themselves, and then raise feature.featureFailedToExecute or feature.featureCannotStart, rather than relying on the Sentinel core to catch and handle exceptions on their behalf.
|
|
You create and edit feature execution scripts using the Sentinel Element Manager. See the Provisioning section in the Sentinel Administration Guide. |
Writing feature execution scripts
Feature execution scripts define how a set of features will be executed by the Sentinel core. Feature execution scripts always run to completion. Features influence the control of a session by making requests to the Sentinel core. For example, a feature may request of the Sentinel core to 'releaseAndClose' . The Sentinel core is responsible for accumulating all requests made and making a final determination as to what should happen next, once the script finishes.
The feature execution scripting language is very simple, with run FeatureName statements, if statements, while statements, do-while statements, and return statements. For more information see:
Statements
The if statement
You can control whether a feature should be executed by using if statements; for example, to play an announcement with the PlayAnnouncementFeature, whether a feature has decided the session should be ended. Each if statement has a condition, a block of statements to run if the if condition is true and, optionally, a block of statements to run if the if condition is false.
The if statement conditions are Boolean expressions of a small set of Boolean flags and Boolean session state fields.
Boolean flags
These flags represent the response of the last feature to run, and the current aggregate view of the feature execution script being executed.
Typically, branches that control which feature should be run next in a script are related to the last feature that ran (and refer to feature. flags).
Branches that guard what should happen based on features earlier than the last feature or at a previous feature script execution point refer to the currentNextStep. flags.
|
|
Most predicates for Sentinel SIP are now provided by Sentinel SIP EventManager Predicates. |
Here are the flags for the different front-end services:
| Front-end service | Requests made by the latest feature that finished executing |
Current view of the script execution as to what will be reported to Sentinel core |
|---|---|---|
Sentinel SIP |
feature.cannotStart feature.failedToExecute feature.issuedWarning |
not applicable |
Sentinel SS7 |
feature.refuseDialog feature.relayDialog feature.markSessionType feature.doNotChargeSession feature.doNotMonitorSession feature.connectAndClose feature.continueAndClose feature.releaseAndClose feature.enableOcsInteraction feature.suppressOcsInteraction feature.scheduleFutureInteraction feature.cannotStart feature.failedToExecute feature.issuedWarning |
currentNextStep.refuseDialog currentNextStep.relayDialog currentNextStep.markSessionType currentNextStep.doNotChargeSession currentNextStep.doNotMonitorSession currentNextStep.connectAndClose currentNextStep.continueAndClose currentNextStep.releaseAndClose currentNextStep.enableOcsInteraction currentNextStep.suppressOcsInteraction currentNextStep.scheduleFutureInteraction |
Diameter |
feature.cannotStart feature.ccNotApplicable feature.creditLimitReached feature.endUserServiceDenied feature.failedToExecute feature.issuedWarning feature.markChargingType feature.markTargetChargingType feature.ratingFailed feature.redirect |
currentNextStep.ccNotApplicable currentNextStep.creditLimitReached currentNextStep.endUserServiceDenied currentNextStep.markChargingType currentNextStep.markTargetChargingType currentNextStep.ratingFailed currentNextStep.redirect currentNextStep.userUnknown |
Boolean session state fields
You may use a Boolean session state field in an if statement condition. The syntax is:
session.<name of the session state field>
For example, session.SessionHasEnded.
Enum session state fields
You may use a session state field, that is a Java enum, in an if statement condition.
The syntax is:
session.<name of the session state field>.<enum constant>
For example, session.ChargingType.sessionCharging.
Such an expression evaluates to true if session.ChargingType is a Java enum and session.ChargingType.name() equals sessionCharging.
The while statement
The while statement allows you to repeatedly execute a set of statements, whilst a condition is true.
Each while statement has a condition and a block of statements (the loop body).
The while loop condition is evaluated before each execution of the loop.
Execution terminates if the condition evaluates to false.
There is a default limit of 10 iterations for a while loop (to avoid infinite loops).
You may specify your own while loop limit (a number in square brackets after the while keyword).
The following two examples demonstrate the format of the while statement:
featurescript AWhileLoopScript {
while local.input1 {
run x
while local.input2 {
run y
}
}
}
featurescript AnotherWhileLoopScript {
while [5] local.input3 {
run x
}
}
The do-while statement
The do-while statement allows you to repeatedly execute a set of statements, whilst a condition is true. Each do-while statement has a condition and a block of statements (the loop body). The do-while loop condition is evaluated after each execution of the loop. Execution terminates if the condition evaluates to false. The body of the do-while statement will, therefore, execute at least once. There is a default limit of 10 iterations for a do-while loop (to avoid infinite loops). You may specify your own do-while loop limit (a number in square brackets after the do keyword).
The following two examples demonstrate the format of the do-while statement:
featurescript ADoWhileLoopScript {
do {
run x
} while local.input1
}
featurescript AnotherDoWhileLoopScript {
do [2] {
run x
} while local.input2
}
The run statement
The run statement tells the Sentinel core to run a particular feature.
The Sentinel core invokes startFeature() and hands control of the session to the feature.
Responsibility for the session remains with the feature until it raises feature.featureHasFinished().
|
|
Sentinel also supports a Currently, only the Sentinel SIP front end considers the outcome of a |
Feature parameters
The run statement can optionally be provided with additional feature parameters, which take the form of a map of key/values.
This data is freeform, and the interpretation and use of the additional data is entirely up to the executed feature.
The intended use of feature parameters is to provide additional context to a feature regarding how it should execute.
For example, feature parameters could be used to instruct a feature to use different configurations when executing as part of alternate logic branches in a feature execution script.
If feature parameters are specified in the feature execution script, then the feature will be invoked with the alternate startFeature() method, which supplies the feature parameters as a map of string keys to ParameterValue objects.
Each ParameterValue object contains either a single string value, or an array of string values.
There are two forms for specifying feature parameters to allow both simple strings and lists of strings to be supplied to a feature. For example:
String |
featurescript somescript {
run featureA param1 "value1" param2 "value2"
} |
|---|---|
List |
featurescript somescript {
run featureB param1 ["value1", "value2"]
} |
Resolving conflicting responses from features
Since a feature execution script runs to completion, it is possible that several features may make conflicting requests of the Sentinel core. Sentinel core applies some simple rules for resolving such conflicts as it updates its view of the script execution result.
Below are rules that are common to all front ends and those specific to each.
Common rules |
|
|---|---|
SS7 rules |
|
SIP rules |
|
Diameter rules |
|
|
|
You can make use of these precedence rules by using an if feature.continueAndClose {
run releaseAndClose
}
|
Feature script execution points that are chained together
There are two cases where Sentinel executes several feature script execution points before it considers the aggregate result and takes action:
| Feature script execution points | The values of the currentNextStep. flags: |
|---|---|
Session Accept Session Start |
|
Network Pre Initial Credit Check Session Pre Initial Credit Check Subscriber Pre Initial Credit Check |
|
|
|
See Session plans for more information. For example, consider SS7 sessions initiated via SS7. |
The currentNextStep. flags are cleared before all other feature script execution points.
Examples
See the following examples of future execution points in different contexts.
featurescript OnSessionStart {
if not currentNextStep.refuseDialog and
not currentNextStep.relayDialog
{
run AcceptProtocol
}
}
|
The first two execution points, together, provide initial dialog analysis. In the first step we run features within the context of the platform operator. This script then runs within the context of the network operator. The condition here says that we run the |
featurescript OnNetworkPreCreditCheck {
run EmergencyAndSpecialNumber
if not feature.continueAndClose {
run ClassifyCallScenario
}
}
|
This is an example script that runs within the context of the network operator. The first step is to run the feature This feature will request that Sentinel core should The next statement says that |
featurescript OnSessionPreCreditCheck {
if not currentNextStep.continueAndClose {
run CallForwardingDetection
if not feature.doNotMonitorSession and
not feature.doNotChargeSession
{
run ValidateInitialDP
if not feature.releaseAndClose {
run ShortCode
run PrefixAndSuffixAnalysis
run Normalization
run Reorigination
if not feature.connectAndClose {
run SubscriberDetermination
run SessionTracing
}
}
}
}
}
|
This is an example script that runs within the context of the session. The initial condition guards all feature execution by checking if we have currently been asked to Otherwise we run the The If that is the case, we then run This feature will request that Sentinel core should |
Feature execution script grammar
The following tramline diagrams define the grammar of the Sentinel feature execution script language.
|
|
